Interface WaitQueue.Signal

  • All Known Implementing Classes:
    WaitQueue.AbstractSignal
    Enclosing class:
    WaitQueue

    public static interface WaitQueue.Signal
    A Signal is a one-time-use mechanism for a thread to wait for notification that some condition state has transitioned that it may be interested in (and hence should check if it is). It is potentially transient, i.e. the state can change in the meantime, it only indicates that it should be checked, not necessarily anything about what the expected state should be. Signal implementations should never wake up spuriously, they are always woken up by a signal() or signalAll(). This abstract definition of Signal does not need to be tied to a WaitQueue. Whilst RegisteredSignal is the main building block of Signals, this abstract definition allows us to compose Signals in useful ways. The Signal is 'owned' by the thread that registered itself with WaitQueue(s) to obtain the underlying RegisteredSignal(s); only the owning thread should use a Signal.
    • Method Summary

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      void await()
      Wait until signalled, or throw an InterruptedException if interrupted before this happens.
      void awaitUninterruptibly()
      Wait, without throwing InterruptedException, until signalled.
      boolean awaitUntil​(long nanos)
      Wait until signalled, or the provided time is reached, or the thread is interrupted.
      boolean awaitUntilUninterruptibly​(long nanos)
      Wait until signalled, or the provided time is reached, or the thread is interrupted.
      void cancel()
      Should only be called by the owning thread.
      boolean checkAndClear()
      atomically: cancels the Signal if !isSet(), or returns true if isSignalled()
      boolean isCancelled()  
      boolean isSet()  
      boolean isSignalled()  
    • Method Detail

      • isSignalled

        boolean isSignalled()
        Returns:
        true if signalled; once true, must be discarded by the owning thread.
      • isCancelled

        boolean isCancelled()
        Returns:
        true if cancelled; once cancelled, must be discarded by the owning thread.
      • isSet

        boolean isSet()
        Returns:
        isSignalled() || isCancelled(). Once true, the state is fixed and the Signal should be discarded by the owning thread.
      • checkAndClear

        boolean checkAndClear()
        atomically: cancels the Signal if !isSet(), or returns true if isSignalled()
        Returns:
        true if isSignalled()
      • cancel

        void cancel()
        Should only be called by the owning thread. Indicates the signal can be retired, and if signalled propagates the signal to another waiting thread
      • awaitUninterruptibly

        void awaitUninterruptibly()
        Wait, without throwing InterruptedException, until signalled. On exit isSignalled() must be true. If the thread is interrupted in the meantime, the interrupted flag will be set.
      • await

        void await()
            throws java.lang.InterruptedException
        Wait until signalled, or throw an InterruptedException if interrupted before this happens. On normal exit isSignalled() must be true; however if InterruptedException is thrown isCancelled() will be true.
        Throws:
        java.lang.InterruptedException
      • awaitUntil

        boolean awaitUntil​(long nanos)
                    throws java.lang.InterruptedException
        Wait until signalled, or the provided time is reached, or the thread is interrupted. If signalled, isSignalled() will be true on exit, and the method will return true; if timedout, the method will return false and isCancelled() will be true; if interrupted an InterruptedException will be thrown and isCancelled() will be true.
        Parameters:
        nanos - System.nanoTime() to wait until
        Returns:
        true if signalled, false if timed out
        Throws:
        java.lang.InterruptedException
      • awaitUntilUninterruptibly

        boolean awaitUntilUninterruptibly​(long nanos)
        Wait until signalled, or the provided time is reached, or the thread is interrupted. If signalled, isSignalled() will be true on exit, and the method will return true; if timedout, the method will return false and isCancelled() will be true
        Parameters:
        nanos - System.nanoTime() to wait until
        Returns:
        true if signalled, false if timed out