Package org.jtrim2.concurrent

Class WaitableSignal

java.lang.Object
org.jtrim2.concurrent.WaitableSignal
public final class WaitableSignal extends Object
Defines thread-safe signal for which threads can wait. That is, initially all WaitableSignal is in the non-signaled state but after invoking the signal() method, it will permanently enter the signaled state. Other threads can wait for this signal by calling the waitSignal or the tryWaitSignal method.

Note that this class is similar to a java.util.concurrent.CountDownLatch with one as the initial "count" but this implementation is simpler and relies on OperationCanceledException rather than on thread interrupts.

Thread safety

The methods of this class are safe to use by multiple threads concurrently.

Synchronization transparency

The methods of this interface are not synchronization transparent.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final WaitableSignal
    SIGNALING_SIGNAL
    A WaitableSignal which is already in the signaling state.

  • Constructor Summary

    Constructors
    Constructor
    Description
    WaitableSignal()
    Creates a new WaitableSignal in the non-signaled state.

  • Method Summary

    Modifier and Type
    Method
    Description
    boolean
    isSignaled()
    Returns true if signal() has been already called on this WaitableSignal object.
    void
    signal()
    Sets the state of this WaitableSignal to the signaled state and allows the waitSignal or the tryWaitSignal method to return immediately.
    boolean
    tryWaitSignal(CancellationToken cancelToken, long timeout, TimeUnit timeUnit)
    Waits until another thread invokes the signal() method or until the specified CancellationToken signals a cancellation request or until the specified timeout elapses.
    void
    waitSignal(CancellationToken cancelToken)
    Waits until another thread invokes the signal() method or until the specified CancellationToken signals a cancellation request.

    Methods inherited from class java.lang.Object

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

  • Field Details

    • SIGNALING_SIGNAL

      public static final WaitableSignal SIGNALING_SIGNAL
      A WaitableSignal which is already in the signaling state. That is, calling any of its wait method is effectively a no-op.

  • Constructor Details

    • WaitableSignal

      public WaitableSignal()
      Creates a new WaitableSignal in the non-signaled state.

  • Method Details

    • signal

      public void signal()
      Sets the state of this WaitableSignal to the signaled state and allows the waitSignal or the tryWaitSignal method to return immediately.

      This method is idempotent. That is, calling this method multiple times has no further effect.

    • isSignaled

      public boolean isSignaled()
      Returns true if signal() has been already called on this WaitableSignal object.

      If this method returns true, subsequent waitSignal or tryWaitSignal method calls will immediately return without waiting (or throwing an exception).

      Returns:
      true if signal() has been already called on this WaitableSignal object, false otherwise

    • waitSignal

      public void waitSignal(CancellationToken cancelToken)
      Waits until another thread invokes the signal() method or until the specified CancellationToken signals a cancellation request.

      Note that if the signal() method has been called prior to this waitSignal method call, this method will always return immediately without throwing an exception (even if the CancellationToken signals a cancellation request).

      Parameters:
      cancelToken - the CancellationToken which is to be checked for cancellation request. A cancellation request will cause this method to throw an OperationCanceledException exception. This argument cannot be null.
      Throws:
      NullPointerException - thrown if the specified CancellationToken is null
      OperationCanceledException - thrown if the specified CancellationToken signals a cancellation request before signal() has been called.

    • tryWaitSignal

      public boolean tryWaitSignal(CancellationToken cancelToken, long timeout, TimeUnit timeUnit)
      Waits until another thread invokes the signal() method or until the specified CancellationToken signals a cancellation request or until the specified timeout elapses.

      Note that if the signal() method has been called prior to this tryWaitSignal method call, this method will always return with true immediately without throwing an exception (even if the CancellationToken signals a cancellation request).

      Parameters:
      cancelToken - the CancellationToken which is to be checked for cancellation request. A cancellation request will cause this method to throw an OperationCanceledException exception. This argument cannot be null.
      timeout - the maximum time to wait for the signal in the given time unit before returning. If the timeout elapses, this method will return with false. This argument must be greater than or equal to zero.
      timeUnit - the time unit of the timeout argument. This argument cannot be null
      Returns:
      true if this method has detected that the signal() method has been called, false if the specified timeout elapsed first.
      Throws:
      NullPointerException - thrown if the specified CancellationToken or TimeUnit is null
      OperationCanceledException - thrown if the specified CancellationToken signals a cancellation request before signal() has been called.