Class ThreadTimeout

ThreadTimeout provides a mechanism for allowing a thread to interrupt itself if it doesn't return to a specific call site within a given timeout. ThreadTimeout instances are intended to be used with a using Statement. Once constructed a ThreadTimeout attempts to ensure that the corresponding using 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 a ThreadInterruptedException will be thrown.

Inheritance

object

ThreadTimeout

Implements

IDisposable

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Namespace: Tangosol.Util

Assembly: Coherence.dll

Syntax

public class ThreadTimeout : IDisposable

Remarks

try { using (ThreadTimeout t = ThreadTimeout.After(5000)) { DoSomething(); } // this thread will self-interrupt if it doesn't reach this line within 5 seconds } catch (ThreadInterruptedException 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; using (BlockingLock l = BlockingLock.Lock(oField)) // rather than lock (oField) { Blocking.Wait(oField); // rather than Monitor.Wait(oField); } }

Note that ThreadTimeout can only self-interrupt at interruptible points, and does not defend against CPU bound loops for example.

Constructors

ThreadTimeout(int, bool)

Specify a new timeout.

Declaration

protected ThreadTimeout(int millis, bool forceOverride)

Parameters

Type	Name	Description
int	millis	The new timeout.
bool	forceOverride	True if this timeout is allowed to extend a parent timeout.

Remarks

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 ThreadInterruptedException.

Fields

f_cMillisTimeout

This ThreadTimeout's timeout.

Declaration

protected readonly long f_cMillisTimeout

Field Value

Type	Description
long

f_lTimeoutOrig

The original timeout before this instance changed it.

Declaration

protected readonly long f_lTimeoutOrig

Field Value

Type	Description
long

f_lhTimeout

Cached reference to the thread's ThreadTimeout.LongHolder holding it's current timeout.

Declaration

protected readonly ThreadTimeout.LongHolder f_lhTimeout

Field Value

Type	Description
ThreadTimeout.LongHolder

f_tloCreator

True iff this Timeout created (and thus must ultimately destroy) the TLO.

Declaration

protected readonly bool f_tloCreator

Field Value

Type	Description
bool

s_tloTimeout

A thread-local containing the calling thread's timeout value. Values 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.

Declaration

protected static ThreadLocal<ThreadTimeout.LongHolder> s_tloTimeout

Field Value

Type	Description
ThreadLocal<ThreadTimeout.LongHolder>

Properties

IsTimedOut

Whether the calling thread is timed out.

Declaration

public static bool IsTimedOut { get; }

Property Value

Type	Description
bool

Remarks

Note if the current thread is timed out then accessing this property will also interrupt the thread. This property can be used to externally add ThreadTimeout support for other blocking APIs not covered by the existing ThreadTimeout helpers.

RemainingTimeoutMillis

The number of remaining milliseconds before this thread will time out, 0 if timed out, or MaxValue if disabled.

Declaration

public static int RemainingTimeoutMillis { get; }

Property Value

Type	Description
int

Remarks

Note if the current thread is timed out then accessing this property will also interrupt the thread. This property can be used to externally add ThreadTimeout support for other blocking APIs not covered by the existing ThreadTimeout helpers.

Methods

After(int)

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.

Declaration

public static ThreadTimeout After(int millis)

Parameters

Type	Name	Description
int	millis	The new timeout in milliseconds.

Returns

Type	Description
ThreadTimeout	A ThreadTimeout instance to be used within a using block.

After(TimeSpan)

Specify a new timeout. Note that the calling thread's timeout will only be changed if the specified timeout is less than any existing timeout already active on the thread.

Declaration

public static ThreadTimeout After(TimeSpan timeSpan)

Parameters

Type	Name	Description
TimeSpan	timeSpan	The new timeout.

Returns

Type	Description
ThreadTimeout	A ThreadTimeout instance to be used within a using block.

Remarks

The sub-millisecond portion of the TimeSpan (if any) will be discarded.

Dispose()

As part of closing the ThreadTimeout resource any former timeout will be restored.

Declaration

public void Dispose()

Exceptions

Type	Condition
ThreadInterruptedException	if the calling thread is interrupted

Override(int)

Specify a new timeout, potentially extending an already active timeout.

Declaration

public static ThreadTimeout Override(int millis)

Parameters

Type	Name	Description
int	millis	The new timeout in milliseconds

Returns

Type	Description
ThreadTimeout	A ThreadTimeout instance to be used within a using block.

Remarks

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 ThreadInterruptedException. Use of this method should be extremely limited.

Implements

IDisposable