Overview | Package | Class | Tree | Index | Help

Oracle® Coherence Java API Reference
v3.5.3
E15583-01
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## com.tangosol.util
Class ThreadGate

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

    public class ThreadGate

extends Base

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

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 of the thread gate by other threads, but do not wait for the gate to close.
`boolean` | `close(long cMillis)` Close the thread 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 thread 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` | `isActiveThread()` Determine if the current thread has entered and not exited.
`void` | `open()` After entry into the ThreadGate is restricted by a call to barEntry() or close(), it can be re-opened by calling this method.
`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 of 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. 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()
           }

  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 thread gate. 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.

  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 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 thread gate. 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.

  Parameters:
    `cMillis` - maximum number of milliseconds to wait; pass -1 for forever or 0 for no wait
  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 enter method.

### open

    public void open()

  After entry into the ThreadGate is restricted by a call to barEntry() or close(), it can be re-opened by calling this method. Only the thread that called barEntry() or close() can call open().

  Throws:
    `java.lang.IllegalStateException` - if the gate is not closed or closing or if open() is not called by the thread that called barEntry() or close()

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

### isActiveThread

    public boolean isActiveThread()

  Determine if the current thread has entered and not exited. This is useful for detecting re-entrancy.

  Returns:
    true if the current thread has entered and not exited
  Since:
    Coherence 3.1

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

Overview | Package | Class | Tree | Index | Help

Oracle® Coherence Java API Reference
v3.5.3
E15583-01
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2000, 2010, Oracle. All rights reserved.