package io.perfmark;

import io.perfmark.impl.Mark;
import java.util.concurrent.atomic.AtomicLong;

/**
 * A link represents a linkage between asynchronous tasks.
 */
public final class Link {
  static final Link NONE = new Link(Mark.NO_LINK_ID);

  static final AtomicLong linkIdAlloc = new AtomicLong();

  private final long id;

  Link(long linkId) {
    this.id = linkId;
  }

  public void link() {
    PerfMark.link(id);
  }

  // For Testing
  long getId() {
    return id;
  }

  @Override
  public String toString() {
    return "Link(" + id + ")";
  }

  /**
   * Equality on Links is not well defined, since the created tag can depend on if PerfMark was
   * enabled at the time of creation.
   */
  @Override
  @Deprecated // Don't use equality on links
  public boolean equals(Object obj) {
    return super.equals(obj);
  }
}

@@ -155,16 +155,408 @@
 s tasks.
+  A link is created inside of a started%0A * task.  The resulting %7B@link Link%7D object can then be passed to other asynchronous tasks to%0A * associate them with the original task.%0A *%0A * %3Cp%3EA source task may have multiple outbound links pointing to other tasks.  However, calling%0A * %7B@link Link#link()%7D only work if it is the first such call.  Subsequent calls to %7B@code link()%7D%0A * have no effect.
 %0A */%0Apub
@@ -767,16 +767,223 @@
 d;%0A  %7D%0A%0A
+  /**%0A   * Associate this link with the most recently started task.  There may be at most one inbound%0A   * linkage per task: the first call to %7B@code link()%7D decides which outbound task is the origin.%0A   */%0A
   public

add Link docs