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