Class ThreadGate

Use this class in cases that large numbers of threads can operate concurrently with an additional requirement that all threads be blocked for certain operations.

Inheritance

object

ThreadGate

Implements

Gate

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

Namespace: Tangosol.Util

Assembly: Coherence.dll

Syntax

[Obsolete("Use GateFactory.NewGate to obtain a Gate.")]
public class ThreadGate : Gate

Remarks

The algorithm is based on a gate concept, allowing threads in Enter(long) and out Exit(), but occasionally shutting the gate Close(long) such that other threads cannot enter and exit. However, since threads may "be inside", the gate cannot fully close until they leave Exit(). Once all threads are out, the gate is closed, and can be re-opened Open() or permanently closed Destroy().

Each call to Enter requires a corresponding call to Exit. For example, the following would ensure proper clean-up using a ThreadGate:

gate.Enter();
try
{
    ...
}
finally
{
    gate.Exit();
}

Similarly, each call to Close should be matched with a call to Open, unless the gate is being destroyed:

gate.Close();
try
{
    ...
}
finally
{
    gate.Open();
}

or:

gate.Close();
gate.Destroy();

The Enter/Exit calls can be nested; the same thread can invoke Enter multiple times as long as Exit is invoked a corresponding number of times. The Close/Open calls work in the same manner. Lastly, the thread that closes the gate may continue to Enter/Exit the gate even when it is closed since that thread has exclusive control of the gate.

Constructors

ThreadGate()

Allocates unnamed data slots on threads to store local thread counter values and returns new instance of ThreadGate.

Declaration

public ThreadGate()

Properties

ActiveCount

The number of unmatched completed Enter calls.

Declaration

public virtual int ActiveCount { get; }

Property Value

Type	Description
int	The number of unmatched completed Enter calls.

CloseCount

The number of unmatched completed Close/BarEntry calls.

Declaration

public virtual int CloseCount { get; set; }

Property Value

Type	Description
int	The number of unmatched completed Close/BarEntry calls.

ClosingThread

The thread that is closing the gates.

Declaration

protected virtual Thread ClosingThread { get; set; }

Property Value

Type	Description
Thread	The thread that is closing the gates.

Remarks

When setting the value, the caller must be synchronized on the ThreadGate.

IsActiveThread

Determine if the current thread has entered and not exited the thread gate.

Declaration

public virtual bool IsActiveThread { get; }

Property Value

Type	Description
bool	true if the current thread has entered and not exited the thread gate.

Remarks

This is useful for detecting re-entrancy.

IsClosedByCurrentThread

Determines if the current thread have Closed the gate but not yet Opened the Gate.

Declaration

public virtual bool IsClosedByCurrentThread { get; }

Property Value

Type	Description
bool

IsClosingThread

Determine if the current thread has closed and not opened the the thread gate.

Declaration

public virtual bool IsClosingThread { get; }

Property Value

Type	Description
bool	true if the current thread has closed and not opened the thread gate.

Remarks

This is useful for detecting re-entrancy.

IsEnteredByCurrentThread

Determine if the current thread has entered and not exited the thread gate.

Declaration

public virtual bool IsEnteredByCurrentThread { get; }

Property Value

Type	Description
bool	true if the current thread has entered and not exited the thread gate.

Remarks

This is useful for detecting re-entrancy.

Status

The current thread gate status.

Declaration

public virtual ThreadGateState Status { get; }

Property Value

Type	Description
ThreadGateState	One of the ThreadGateState values.

Version

The total number of times the gate has been fully opened.

Declaration

protected virtual long Version { get; set; }

Property Value

Type	Description
long	The total number of times the gate has been fully opened.

Remarks

When setting the value, the caller must have the gate closed.

Methods

BarEntry(long)

Bar entry of the thread gate by other threads, but do not wait for the gate to close.

Declaration

public bool BarEntry(long millis)

Parameters

Type	Name	Description
long	millis	Maximum number of milliseconds to wait; pass -1 for forever or 0 for no wait.

Returns

Type	Description
bool	true iff entry into the thread gate was successfully barred by the calling thread.

Remarks

When all other threads have exited, the status of the thread gate will be closeable by the thread which barred entry. Each sucessful invocation of this method must ultimately have a corresponding invocation of the Open method (assuming the thread gate is not destroyed) even if the calling thread does not subsequently close the gate.

gate.BarEntry(-1);
try
{
    // processing that does not require the gate to be closed
    // ...
}
finally
{
    gate.Close(-1);
    try
    {
        // processing that does require the gate to be closed
        // ...
    }
    finally
    {
        gate.Open(); // matches gate.Close()
    }
    gate.Open(); // matches gate.BarEntry()
}

Close(long)

Close the thread gate.

Declaration

public virtual bool Close(long millis)

Parameters

Type	Name	Description
long	millis	Maximum number of milliseconds to wait; pass -1 for forever or 0 for no wait.

Returns

Type	Description
bool	true iff entry into the thread gate was successfully barred by the calling thread and no other threads remain in the gate.

Remarks

A thread uses this method to obtain exclusive access to the resource represented by the thread gate. Each invocation of this method must ultimately have a corresponding invocation of the Open method.

DecrementThreadLocalCount(LocalDataStoreSlot)

Decrement the long value of the LocalDataStoreSlot for the current thread by one.

Declaration

protected virtual long DecrementThreadLocalCount(LocalDataStoreSlot slot)

Parameters

Type	Name	Description
LocalDataStoreSlot	slot	LocalDataStoreSlot object which provides managed thread local storage with dynamic data slots that are unique to a thread and application-domain combination.

Returns

Type	Description
long	The new long value for the current thread or -1 if previous value was null.

Remarks

If the value in the LocalDataStoreSlot is null, -1 is returned.

Destroy()

Destroy the thread gate.

Declaration

public virtual void Destroy()

Remarks

This method can only be invoked if the gate is already closed.

DoWait(long)

Wait up to the specified number of milliseconds for notification.

Declaration

protected virtual long DoWait(long millis)

Parameters

Type	Name	Description
long	millis	Number of milliseconds to wait for.

Returns

Type	Description
long	The remaining wait time in milliseconds.

Remarks

Caller must be synchronized.

Enter(long)

Enter the thread gate.

Declaration

public virtual bool Enter(long millis)

Parameters

Type	Name	Description
long	millis	Maximum number of milliseconds to wait; pass -1 for forever or 0 for no wait.

Returns

Type	Description
bool	true iff the calling thread successfully entered the gate.

Remarks

A thread uses this method to obtain non-exclusive access to the resource represented by the thread gate. Each invocation of this method must ultimately have a corresponding invocation of the Exit method.

Exit()

Exit the gate.

Declaration

public virtual void Exit()

Remarks

A thread must invoke this method corresponding to each invocation of the Enter method.

GetThreadLocalCount(LocalDataStoreSlot)

Obtain the long value stored in the LocalDataStoreSlot.

Declaration

protected virtual long GetThreadLocalCount(LocalDataStoreSlot slot)

Parameters

Type	Name	Description
LocalDataStoreSlot	slot	LocalDataStoreSlot object which provides managed thread local storage with dynamic data slots that are unique to a thread and application-domain combination.

Returns

Type	Description
long	Long value stored in the LocalDataStoreSlot.

IncrementThreadLocalCount(LocalDataStoreSlot)

Increment the long value from the LocalDataStoreSlot for the current thread by one.

Declaration

protected virtual long IncrementThreadLocalCount(LocalDataStoreSlot slot)

Parameters

Type	Name	Description
LocalDataStoreSlot	slot	LocalDataStoreSlot object which provides managed thread local storage with dynamic data slots that are unique to a thread and application-domain combination.

Returns

Type	Description
long	The new long value for the current thread or 1 if previous value was null.

Remarks

If the value in the LocalDataStoreSlot is null, 1 is returned.

Open()

After entry into the ThreadGate is restricted by a call to BarEntry() or Close(), it can be re-opened by calling this method.

Declaration

public virtual void Open()

Remarks

Only the thread that called BarEntry() or Close() can call Open().

Exceptions

Type	Condition
InvalidOperationException	If the gate is not closed or closing or if Open() is not called by the thread that called BarEntry() or Close().

SetThreadLocalCount(LocalDataStoreSlot, long)

Set the long value to be stored in the LocalDataStoreSlot.

Declaration

protected virtual void SetThreadLocalCount(LocalDataStoreSlot slot, long value)

Parameters

Type	Name	Description
LocalDataStoreSlot	slot	LocalDataStoreSlot object which provides managed thread local storage with dynamic data slots that are unique to a thread and application-domain combination.
long	value	Long value to be stored in the LocalDataStoreSlot.

ToString()

Provide a human-readable representation of this ThreadGate.

Declaration

public override string ToString()

Returns

Type	Description
string	A human-readable representation of this ThreadGate.

Overrides

object.ToString()

UpdateStatus(ThreadGateState)

Update the current thread gate status, without changing the active count.

Declaration

protected virtual ThreadGateState UpdateStatus(ThreadGateState status)

Parameters

Type	Name	Description
ThreadGateState	status	The new status.

Returns

Type	Description
ThreadGateState	The old status.

Remarks

The caller must hold synchronization on the ThreadGate.

Implements

Gate