Package com.oracle.coherence.common.base

Class Timeout

java.lang.Object
com.oracle.coherence.common.base.Timeout
All Implemented Interfaces:
AutoCloseable
public class Timeout extends Object implements AutoCloseable
Timeout provides a mechanism for allowing a thread to interrupt itself if it doesn't return to a specific call site within a given timeout. Timeout instances are intended to be used with the try-with-resource pattern. Once constructed a Timeout attempts to ensure that the corresponding try-with-resource block completes within the specified timeout and if it does not the thread will self-interrupt. Exiting the timeout block will automatically clear any interrupt present on the thread and in such a case an InterruptedException will be thrown. 
 try (Timeout t = Timeout.after(5, TimeUnit.SECONDS))
     {
     doSomething();
     } // this thread will self-interrupt if it doesn't reach this line within 5 seconds
 catch (InterruptedException e)
     {
     // thread timed out or was otherwise interrupted
     }
In order for this to work any blocking code executed from within the context of the Timeout must use the Blocking static helper methods for blocking. An example of a compatible blocking call would be: 
 void doSomething()
     {
     Object oField = m_oField;
     synchronized (oField)
         {
         Blocking.wait(oField); // rather then oField.wait();
         }
     }
Note that Timeout can only self-interrupt at interruptible points, and does not defend against CPU bound loops for example.
Author:
mf 2015.02.23

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    protected final long
    f_cMillisTimeout
    This Timeout's timeout.
    protected final boolean
    f_fTloCreator
    True iff this Timeout created (and thus must ultimately destroy) the TLO.
    protected final long
    f_lTimeoutOrig
    The original timeout before this instance changed it.
    protected final MutableLong
    f_mlTimeout
    Cached reference to the thread's MutableLong holding it's current timeout.
    protected static final ThreadLocal<MutableLong>
    s_tloTimeout
    A thread-local containing the calling thread's timeout value.

  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
    protected
    Timeout(long cMillis, boolean fForceOverride)
    Specify a new timeout.

  • Method Summary

    Modifier and Type
    Method
    Description
    static Timeout
    after(long cMillis)
    Specify a new timeout.
    static Timeout
    after(long time, TimeUnit unit)
    Specify a new timeout.
    void
    close()
    As part of closing the Timeout resource any former timeout will be restored.
    static boolean
    isSet()
    Return true if calling thread specified a timeout.
    static boolean
    isTimedOut()
    Return true if the calling thread is timed out.
    static Timeout
    override(long cMillis)
    Specify a new timeout, potentially extending an already active timeout.
    static long
    remainingTimeoutMillis()
    Return the number of milliseconds before this thread will timeout.

    Methods inherited from class java.lang.Object

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

  • Field Details

    • f_fTloCreator

      protected final boolean f_fTloCreator
      True iff this Timeout created (and thus must ultimately destroy) the TLO.

    • f_mlTimeout

      protected final MutableLong f_mlTimeout
      Cached reference to the thread's MutableLong holding it's current timeout.

    • f_cMillisTimeout

      protected final long f_cMillisTimeout
      This Timeout's timeout.

    • f_lTimeoutOrig

      protected final long f_lTimeoutOrig
      The original timeout before this instance changed it.

    • s_tloTimeout

      protected static final ThreadLocal<MutableLong> s_tloTimeout
      A thread-local containing the calling thread's timeout value. Value which are greater or equal to zero are used to indicate timeout timestamps. Negative values are relative timeouts which haven't yet been realized into a timestamp. This allows for an optimization where we can avoid obtaining the current time when "setting" the timeout, and defer it until we are about to block.

  • Constructor Details

    • Timeout

      protected Timeout(long cMillis, boolean fForceOverride)
      Specify a new timeout. This constructor variant allows the caller to override a parent timeout. This is rarely needed, and is roughly the equivalent of silently consuming a thread interrupt without rethrowing the InterruptedException.
      Parameters:
      cMillis - the new timeout.
      fForceOverride - true if this timeout is allowed to extend a parent timeout.

  • Method Details

    • close

      public void close() throws InterruptedException
      As part of closing the Timeout resource any former timeout will be restored.
      Specified by:
      close in interface AutoCloseable
      Throws:
      InterruptedException - if the calling thread is interrupted

    • after

      public static Timeout after(long time, TimeUnit unit)
      Specify a new timeout. Note that the calling thread's timeout will only be changed if the specified timeout is less then any existing timeout already active on the thread.
      Parameters:
      time - the new timeout
      unit - the unit the timeout is expressed in
      Returns:
      a Timeout instance to be used within a try-with-resource block

    • after

      public static Timeout after(long cMillis)
      Specify a new timeout. Note that the calling thread's timeout will only be changed if the specified timeout is less then any existing timeout already active on the thread.
      Parameters:
      cMillis - the new timeout
      Returns:
      a Timeout instance to be used within a try-with-resource block

    • override

      public static Timeout override(long cMillis)
      Specify a new timeout, potentially extending an already active timeout.

      This variant allows the caller to extend a parent timeout. This is rarely needed, and is roughly the equivalent of silently consuming a thread interrupt without rethrowing the InterruptedException. Use of this method should be extremely limited.

      Parameters:
      cMillis - the new timeout
      Returns:
      a Timeout instance to be used within a try-with-resource block

    • remainingTimeoutMillis

      public static long remainingTimeoutMillis()
      Return the number of milliseconds before this thread will timeout. Note if the current thread is timed out then invoking this method will also interrupt the thread. This method can be used to externally add Timeout support for other blocking APIs not covered by the existing Timeout helpers.
      Returns:
      the number of remaining milliseconds, 0 if timed out, or Long.MAX_VALUE if disabled.

    • isTimedOut

      public static boolean isTimedOut()
      Return true if the calling thread is timed out. Note if the current thread is timed out then invoking this method will also interrupt the thread. This method can be used to externally add Timeout support for other blocking APIs not covered by the existing Timeout helpers.
      Returns:
      true if the calling thread is timed out

    • isSet

      public static boolean isSet()
      Return true if calling thread specified a timeout.
      Returns:
      true if a timeout is set