Skip navigation links

com.tangosol.util
Class ThreadGate

java.lang.Object
com.tangosol.util.Base
com.tangosol.util.ThreadGate

All Implemented Interfaces:

Gate

public class ThreadGate

extends Base

implements Gate

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. The algorithm is based on a gate concept, allowing threads in (enter) and out (exit), but occasionally shutting the gate (close) 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, similar to the JVM implementation of the "synchronized" keyword that places a monitorenter op that the beginning of the synchronized portion and protects the synchronized portion with a try..finally construct that ensures the execution of a monitorexit op. 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.

Since:

Coherence 2.2

Author:

cp 2003.05.26; mf 2007.04.27; coh 2010.08.13

Nested Class Summary

static class

ThreadGate.ThreadLocalCounter Specialization of ThreadLocalObject that can be used for efficient thread local long counters.

Field Summary

static int	GATE_CLOSED GATE_CLOSED: A single thread is inside the gates; other threads cannot enter.
static int	GATE_CLOSING GATE_CLOSING: A thread is waiting to be the only thread inside the gates; other threads can only exit.
static int	GATE_DESTROYED GATE_DESTROYED: Life-cycle is complete; the object is no longer usable.
static int	GATE_OPEN GATE_OPEN: Threads may enter and exit the gates.

Constructor Summary

ThreadGate()
Default constructor.

Method Summary

boolean	barEntry(long cMillis) Bar entry to the thread gate by other threads, but do not wait for the gate to close.
boolean	close(long cMillis) Close the gate.
void	destroy() Destroy the thread gate.
protected long	doWait(long cMillis) Wait up to the specified number of milliseconds for notification.
boolean	enter(long cMillis) Enter the gate.
void	exit() Exit the gate.
int	getActiveCount() Return the number of unmatched completed enter calls.
int	getCloseCount() Return the number of unmatched completed close/barEntry calls.
protected java.lang.Thread	getClosingThread() Return the thread that is closing the gates.
int	getStatus() Return the current thread gate status.
protected long	getVersion() Return the total number of times the gate has been fully opened.
boolean	isClosed() Determine if any thread has closed the gate and continues to hold exclusive access.
boolean	isClosedByCurrentThread() Determine if the calling thread has closed the gate and continues to hold exclusive access.
boolean	isEnteredByCurrentThread() Determines if the current thread has entered the gate and not yet exited.
void	open() Re-open the closed gate.
protected void	setCloseCount(int cClose) Specify the number of unmatched completed close/barEntry calls.
protected void	setClosingThread(java.lang.Thread thread) Specify the thread that is closing the gates.
protected void	setVersion(long cVersion) Specify the total number of times the gate has been fully opened.
java.lang.String	toString() Provide a human-readable representation of this ThreadGate.
protected int	updateStatus(int nStatus) Update the current thread gate status, without changing the active count.

Field Detail

GATE_OPEN

public static final int GATE_OPEN

GATE_OPEN: Threads may enter and exit the gates.

See Also:

Constant Field Values

GATE_CLOSING

public static final int GATE_CLOSING

GATE_CLOSING: A thread is waiting to be the only thread inside the gates; other threads can only exit.

See Also:

Constant Field Values

GATE_CLOSED

public static final int GATE_CLOSED

GATE_CLOSED: A single thread is inside the gates; other threads cannot enter.

See Also:

Constant Field Values

GATE_DESTROYED

public static final int GATE_DESTROYED

GATE_DESTROYED: Life-cycle is complete; the object is no longer usable.

See Also:

Constant Field Values

Constructor Detail

ThreadGate

public ThreadGate()

Default constructor.

Method Detail

barEntry

public boolean barEntry(long cMillis)

Bar entry to the thread gate by other threads, but do not wait for the gate to close. When all other threads have exited, the status of the thread gate will be closeable by the thread which barred entry. Threads that have already entered the gate at the time of this method call should be allowed to succeed in additional #enter calls.

Each successful 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()
     }
 

Specified by:

barEntry in interface Gate

Parameters:

cMillis - maximum number of milliseconds to wait; pass -1 for forever or 0 for no wait

Returns:

true iff entry into the thread gate was successfully barred by the calling thread

close

public boolean close(long cMillis)

Close the gate. A thread uses this method to obtain exclusive access to the resource represented by the gate. Each invocation of this method must ultimately have a corresponding invocation of the Gate.open() method.

Specified by:

close in interface Gate

Parameters:

cMillis - maximum number of milliseconds to wait; pass -1 to wait indefinitely or 0 to return immediately

Returns:

true iff entry into the gate was successfully closed by the calling thread and no other threads remain in the gate

destroy

public void destroy()

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

enter

public boolean enter(long cMillis)

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

Specified by:

enter in interface Gate

Parameters:

cMillis - maximum number of milliseconds to wait; pass -1 to wait indefinitely or 0 to return immediately

Returns:

true iff the calling thread successfully entered the gate

exit

public void exit()

Exit the gate. A thread must invoke this method corresponding to each invocation of the Gate.enter(long) method.

Specified by:

exit in interface Gate

open

public void open()

Re-open the closed gate. This method can be called only if the calling thread successfully closed the gate.

Specified by:

open in interface Gate

isClosedByCurrentThread

public boolean isClosedByCurrentThread()

Determine if the calling thread has closed the gate and continues to hold exclusive access.

Specified by:

isClosedByCurrentThread in interface Gate

Returns:

true iff the calling thread holds exclusive access to the gate

isEnteredByCurrentThread

public boolean isEnteredByCurrentThread()

Determines if the current thread has entered the gate and not yet exited.

Specified by:

isEnteredByCurrentThread in interface Gate

Returns:

true if the current thread has entered the gate

isClosed

public boolean isClosed()

Determine if any thread has closed the gate and continues to hold exclusive access.

Specified by:

isClosed in interface Gate

Returns:

true iff there is a thread that holds exclusive access to the gate

doWait

protected long doWait(long cMillis)

Wait up to the specified number of milliseconds for notification. Caller must be synchronized.

Returns:

the remaining wait time in milliseconds

getActiveCount

public int getActiveCount()

Return the number of unmatched completed enter calls.

getVersion

protected long getVersion()

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

setVersion

protected void setVersion(long cVersion)

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

The caller must have the gate closed.

getCloseCount

public int getCloseCount()

Return the number of unmatched completed close/barEntry calls.

setCloseCount

protected void setCloseCount(int cClose)

Specify the number of unmatched completed close/barEntry calls.

The caller must have the gate closed/closing.

getClosingThread

protected java.lang.Thread getClosingThread()

Return the thread that is closing the gates.

setClosingThread

protected void setClosingThread(java.lang.Thread thread)

Specify the thread that is closing the gates.

The caller must be synchronized on the ThreadGate.

getStatus

public int getStatus()

Return the current thread gate status.

updateStatus

protected int updateStatus(int nStatus)

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

The caller must hold synchronization on the ThreadGate.

Parameters:

nStatus - the new status

Returns:

the old status

toString

public java.lang.String toString()

Provide a human-readable representation of this ThreadGate.

Skip navigation links