Package: org.apache.groovy.runtime.async

## [Java] Class SelectClaim

- 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

- - ### Methods Summary

    Methods
    Type Params | Return Type | Name and description
    --- | --- | ---
    `` | `public boolean` | `allowCancel(Object future)` Gate for cancelling the given parked completion.
    `` | `public void` | `commit(Object token, Object winner)` Commits a reservation made with pend; cannot fail while the token is held.
    `` | `public boolean` | `isCommitted()` Whether the claim has reached a terminal state (a reservation in flight is not terminal).
    `` | `public Object` | `pend()` Reserves this claim, waiting out any other party's reservation.
    `` | `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.
    `` | `public void` | `revert(Object token)` Reverts a reservation made with pend, reopening the claim.
    `` | `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.
    `` | `public boolean` | `tryCommitCancel()` Commits to cancellation: once this succeeds, no branch can deliver.

  - ### Inherited Methods Summary

    Inherited Methods
    Methods inherited from class | Name
    --- | ---
    `class Object` | `equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Method Detail

    - #### 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

    - #### 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

    - #### public boolean isCommitted()

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

    - #### public Object pend()

      Reserves this claim, waiting out any other party's reservation.

      Returns:
        the token to commit or revert with, or `null` if the claim is already committed

    - #### 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

    - #### public void revert(Object token)

      Reverts a reservation made with pend, reopening the claim.

      Parameters:
        `token` - the reservation token

    - #### 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

    - #### public boolean tryCommitCancel()

      Commits to cancellation: once this succeeds, no branch can deliver.

      Returns:
        `false` if a branch had already won