Package org.apache.groovy.runtime.async

Class SelectClaim

java.lang.Object
org.apache.groovy.runtime.async.SelectClaim
public final class SelectClaim extends Object
The single-winner state of one selection: the arbiter through which a group of competing offers (the branches of a ChannelSelect, or a lone channel operation) commits exactly one outcome between them.

A claim is a three-state machine: OPEN, PENDING, or COMMITTED. PENDING is a revertible reservation held while a two-party pairing (a send offer meeting a receive offer, each belonging to a different selection) verifies that both sides still stand; the reservation always resolves promptly — its holder does only lock-free work, never completes a future and never takes a lock while holding it — so competitors may spin on it. When two claims must be reserved together they are taken in ascending id order, which keeps every waits-for chain strictly increasing and therefore cycle-free: the shared-memory form of the commit protocol for generalized (input and output) guards of Buckley & Silberschatz (TOPLAS 1983).

A committed claim records the winning party — the completion of the branch that won, or the cancelled marker — so cancellation can distinguish "this branch won, refuse the cancel: its delivery is imminent or done" from "a sibling won, this loser may unpark freely".

Since:
6.0.0

  • Constructor Summary

    Constructors
    Constructor
    Description
    SelectClaim()
     

  • Method Summary

    Modifier and Type
    Method
    Description
    boolean
    allowCancel(Object future)
    Gate for cancelling the given parked completion.
    void
    commit(Object token, Object winner)
    Commits a reservation made with pend(); cannot fail while the token is held.
    boolean
    isCommitted()
    Whether the claim has reached a terminal state (a reservation in flight is not terminal).
    Object
    pend()
    Reserves this claim, waiting out any other party's reservation.
    static int
    pendBoth(SelectClaim a, SelectClaim b, Object[] tokens)
    Reserves two parties' claims, in ascending id order regardless of argument order, reverting the first if the second turns out committed.
    void
    revert(Object token)
    Reverts a reservation made with pend(), reopening the claim.
    boolean
    tryCommit(Object winner)
    Commits in one step when no partner needs verifying: a value provably present under the channel lock, or a send into free buffer space.
    boolean
    tryCommitCancel()
    Commits to cancellation: once this succeeds, no branch can deliver.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Constructor Details

    • SelectClaim

      public SelectClaim()

  • Method Details

    • pend

      public Object pend()
      Reserves this claim, waiting out any other party's reservation.
      Returns:
      the token to commit(java.lang.Object, java.lang.Object) or revert(java.lang.Object) with, or null if the claim is already committed

    • commit

      public void commit(Object token, Object winner)
      Commits a reservation made with pend(); cannot fail while the token is held.
      Parameters:
      token - the reservation token
      winner - the completion of the branch that won

    • revert

      public void revert(Object token)
      Reverts a reservation made with pend(), reopening the claim.
      Parameters:
      token - the reservation token

    • tryCommit

      public boolean tryCommit(Object winner)
      Commits in one step when no partner needs verifying: a value provably present under the channel lock, or a send into free buffer space.
      Parameters:
      winner - the completion of the branch that won
      Returns:
      false if the claim was already committed elsewhere

    • tryCommitCancel

      public boolean tryCommitCancel()
      Commits to cancellation: once this succeeds, no branch can deliver.
      Returns:
      false if a branch had already won

    • isCommitted

      public boolean isCommitted()
      Whether the claim has reached a terminal state (a reservation in flight is not terminal).

    • allowCancel

      public boolean allowCancel(Object future)
      Gate for cancelling the given parked completion. A still-open claim is committed to the cancel and the future may die; a claim committed to a sibling lets this loser unpark freely; but the committed winner itself is refused — its delivery is imminent or done and must reach the caller.
      Parameters:
      future - the completion being cancelled
      Returns:
      whether the future may be cancelled

    • pendBoth

      public static int pendBoth(SelectClaim a, SelectClaim b, Object[] tokens)
      Reserves two parties' claims, in ascending id order regardless of argument order, reverting the first if the second turns out committed.
      Parameters:
      a - the first party's claim; its token lands in tokens[0]
      b - the second party's claim; its token lands in tokens[1]
      tokens - receives the two reservation tokens on success
      Returns:
      0 with both reservations held, 1 if a is already committed, 2 if b is