document expected count values

mcculls · mcculls · commit a3633a969d01 · 2025-02-05T18:57:19.000Z
also remove BARRIER as that was only necessary for previous implementation where cancel always deprecated the count

we now use a magic value of MAX_INT/2 to represent a hold, to distinguish it from an individual activation
diff --git a/dd-trace-core/src/main/java/datadog/trace/core/scopemanager/ScopeContinuation.java b/dd-trace-core/src/main/java/datadog/trace/core/scopemanager/ScopeContinuation.java
@@ -20,14 +20,32 @@ final class ScopeContinuation implements AgentScope.Continuation {
 
   // these boundaries were selected to allow for speculative counting and fuzzy checks
   private static final int CANCELLED = Integer.MIN_VALUE >> 1;
-  private static final int BARRIER = Integer.MIN_VALUE >> 2;
   private static final int HELD = (Integer.MAX_VALUE >> 1) + 1;
 
   final ContinuableScopeManager scopeManager;
   final AgentSpan spanUnderScope;
   final byte source;
   final AgentTraceCollector traceCollector;
 
+  /**
+   * When positive this reflects the number of outstanding activations as well as whether there is
+   * an active hold on the continuation:
+   *
+   * <table>
+   * <tr><th>Value</th> <th>Meaning</th></tr>
+   * <tr><td>0</td><td>Not held or activated</td></tr>
+   * <tr><td>1..HELD-1</td><td>Activated, not held</td></tr>
+   * <tr><td>HELD</td><td>Held, not yet activated</td></tr>
+   * <tr><td>HELD..MAX_INT</td><td>Activated and held</td></tr>
+   * </table>
+   *
+   * where HELD is at the mid-point between 1 and MAX_INT.
+   *
+   * <p>A negative value of CANCELLED reflects that the continuation has either been activated and
+   * all associated scopes are now closed, or it has been explicitly cancelled. This value was
+   * chosen to be half the size of MIN_INT to avoid speculative additions in {@link #activate()}
+   * from overflowing to a positive count.
+   */
   private volatile int count = 0;
 
   ScopeContinuation(
@@ -73,7 +91,7 @@ public void cancel() {
       COUNT.compareAndSet(this, current, current - HELD);
       current = count;
     }
-    while (current <= 0 && current > BARRIER) {
+    while (current == 0) {
       // no outstanding activations and hold has been removed
       if (COUNT.compareAndSet(this, current, CANCELLED)) {
         traceCollector.cancelContinuation(this);
