Class Waiter<T>

java.lang.Object
cl.netswitch.lib.aio.Waiter<T>
Type Parameters:
T - the type of value delivered to the waiting thread.
public final class Waiter<T> extends Object
Synchronization helper that allows a single thread to wait for a value delivered by another thread.

A thread calls await(long) to block until another thread provides a value through signal(String, Object) with a matching identification. This class is typically used to coordinate request–response interactions between threads, such as in asynchronous I/O or messaging systems.

This class is designed for a single waiting thread at a time. Multiple threads waiting on the same Waiter instance are not supported.

  • Constructor Summary

    Constructors
    Constructor
    Description
    Waiter()
     

  • Method Summary

    Modifier and Type
    Method
    Description
    T
    await(long timeout)
    Waits until this waiter is completed or the specified timeout expires.
    void
    cancel()
    Cancels this waiter and wakes the waiting thread, if any.
    void
    clear()
    Resets this waiter, discarding the current identification and value.
    void
    initialize(String id)
    Initializes this waiter for a new waiting operation.
    boolean
    signal(String id, T value)
    Delivers a value to the waiting thread and marks this waiter completed.
    boolean
    tryClaim()
    Atomically claims the waiter for a new request if not already in use.

    Methods inherited from class Object

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

  • Constructor Details

    • Waiter

      public Waiter()

  • Method Details

    • initialize

      public void initialize(String id)
      Initializes this waiter for a new waiting operation.

      The specified id identifies the request associated with this waiter. Any previously stored value is cleared and the completion state is reset so that a subsequent call to await(long) will block until a matching call to signal(String, Object) occurs.

      Parameters:
      id - the identification associated with the next wait operation.
      Throws:
      NullPointerException - if id is null.

    • await

      public T await(long timeout) throws InterruptedException
      Waits until this waiter is completed or the specified timeout expires.

      If timeout is 0, this method waits indefinitely until completion.

      If the waiter has not been completed, the current thread is suspended until another thread invokes signal(String, Object) with a matching identification, the waiter is cancelled, or the timeout expires.

      This method is responsive to interruption. If the current thread is interrupted while waiting, an InterruptedException is thrown and the interrupted status is cleared.

      Parameters:
      timeout - the max time to wait (millisecs) (0 = wait indefinitely).
      Returns:
      the delivered value or null if timeout or cancelled.
      Throws:
      IllegalArgumentException - if timeout is negative.
      InterruptedException - if current thread interrupted while waiting.

    • signal

      public boolean signal(String id, T value)
      Delivers a value to the waiting thread and marks this waiter completed.

      If the specified id matches the current waiter identification, the value is stored and the waiting thread (if any) is unparked.

      Only the thread currently waiting via await(long) will be unparked. If no thread is waiting, the value is stored and will be returned to the next call to await(long).

      Parameters:
      id - the identification expected by this waiter.
      value - the value to deliver to the waiting thread.
      Returns:
      true if the waiter was successfully signalled; false if the specified id does not match the current waiter identification.
      Throws:
      NullPointerException - if an argument is null.

    • tryClaim

      public boolean tryClaim()
      Atomically claims the waiter for a new request if not already in use.
      Returns:
      true if claim succeeded, false if another request is running.

    • cancel

      public void cancel()
      Cancels this waiter and wakes the waiting thread, if any.

      Once cancelled, await(long) will return null immediately.

    • clear

      public void clear()
      Resets this waiter, discarding the current identification and value.

      This does not affect threads currently blocked in await(long). It is intended to prepare the waiter for a new operation.