Oracle Coherence for C++ API
Release 3.6.1.0
E18813-01

- Main Page
- Namespaces
- Classes
- Files

- Alphabetical List
- Class List
- Class Hierarchy
- Class Members

# ThreadGate Class Reference

`#include <coherence/util/ThreadGate.hpp>`

Inherits Object.

List of all members.

## Detailed Description

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 implementation of the COH_SYNCHRONIZED macro that calls Object::lock at the the beginning of the synchronized portion and protects the synchronized portion with a try..catch construct that ensures the execution of a Object::unlock call. For example, the following would ensure proper clean-up using a ThreadGate: 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.

To make usage of these calls easier, the following macros have been defined:

- COH_GATE_ENTER enters and automatically exits the gate
- COH_GATE_CLOSE closes and automatically opens the gate
- COH_GATE_BAR bars entry and automatically opens the gate

     COH_GATE_ENTER (hGate) // read lock acquired
       {
       // read operations go here
       // ...
       // ...
       } // read lock released
     // outside of sync block

     COH_GATE_CLOSE (hGate) // write lock acquired
       {
       // write operations go here
       // ...
       // ...
       } // write lock released
     // outside of sync block

     COH_GATE_BAR (hGate) // additional readers are blocked
       {
       // non-synchronized ops
       COH_GATE_CLOSE (hGate) // write lock acquired
          {
          // ...
          // ...
          } // inner-write lock released
       // gate still locked
       } // gate opened
     // outside of sync block

Author:
  nsa 2008.01.03

## Public Types
enum | Status
| State identifiers.
typedef spec::Handle | Handle
| ThreadGate Handle definition.
typedef spec::View | View
| ThreadGate View definition.
typedef spec::Holder | Holder
| ThreadGate Holder definition.
## Public Member Functions
virtual bool | barEntry (int64_t cMillis=INFINITE)
| Bar entry of the thread gate by other threads, but do not wait for the gate to close.
virtual bool | close (int64_t cMillis=INFINITE)
| Close the thread gate.
virtual void | destroy ()
| Destroy the thread gate.
virtual bool | enter (int64_t cMillis=INFINITE)
| Enter the thread gate.
virtual void | exit ()
| Exit the gate.
virtual 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.
virtual int32_t | getActiveCount () const
| Return the number of entered threads.
virtual bool | isActiveThread () const
| Determine if the current thread has entered and not exited.
virtual int32_t | getCloseCount () const
| Return the number of unmatched completed close/barEntry calls.
virtual Status | getStatus () const
| Return the current thread gate status.
virtual void | toStream (std::ostream &out) const
| Output a human-readable description of this Object to the given stream. coherence::lang::operator<<(std::ostream, Object::View) is defined and will call into the toStream method, to output Objects. If a managed String object is desired, the COH_TO_STRING macro can be used to build up a String from streamable contents.
     Object::View vKey   = ...
     Object::View vValue = ...
     std::cout << vKey << " = " << vValue << std::endl;

     String::Handle hs = COH_TO_STRING(vKey << " = " << vValue);
  Parameters:
  | out | the stream used to output the description
## Static Public Attributes
static const int32_t | MAX_ENTERS
| The maximum number of threads allowed in the gate at one time.
static const int64_t | INFINITE
| The constant representing wait forever.
static const int64_t | IMMEDIATE
| The constant representing not to wait.
## Protected Member Functions
| ThreadGate ()
| Create a new ThreadGate.
virtual void | setCloseCount (int32_t cClose)
| Specify the number of unmatched completed close/barEntry calls.
virtual Thread::View | getClosingThread () const
| Return the thread that is closing the gate.
virtual void | setClosingThread (Thread::View vThread)
| Specify the thread id that is closing the gate.
virtual Status | updateStatus (Status nStatus)
| Update the current thread gate status, without changing the active count.
virtual int64_t | doWait (int64_t cMillis)
| Wait up to the specified number of milliseconds for notification.
## Classes
class | Counter
| Counter is a mutable integer class. More...
class | GateBlock
| The EnterBlock class allows for easy creation of ThreadGate::enter code. More...

## Member Function Documentation

virtual bool barEntry | ( | int64_t | cMillis = `INFINITE` | ) | `[virtual]`

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 thread gate will be closeable by the thread which barred entry. 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.

Parameters:

  | cMillis | maximum number of milliseconds to wait; pass INFINITE for forever or IMMEDIATE for no wait

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

virtual bool close | ( | int64_t | cMillis = `INFINITE` | ) | `[virtual]`

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 INFINITE for forever or IMMEDIATE for no wait

Returns:
  true iff the entry into the thread gate was successfully barred by the calling thread and no other threads remain in the gate.

virtual void destroy | ( |  | ) | `[virtual]`

Destroy the thread gate.

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

virtual bool enter | ( | int64_t | cMillis = `INFINITE` | ) | `[virtual]`

Enter the thread gate.

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

Parameters:

  | cMillis | maximum number of milliseconds to wait; pass INFINITE for forever or IMMEDIATE for no wait

Returns:
  true iff the calling thread successfully entered the gate

virtual void exit | ( |  | ) | `[virtual]`

Exit the gate.

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

virtual void open | ( |  | ) | `[virtual]`

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().

virtual int32_t getActiveCount | ( |  | ) | const `[virtual]`

Return the number of entered threads.

Returns:
  the number of entered threads

virtual bool isActiveThread | ( |  | ) | const `[virtual]`

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.

virtual int32_t getCloseCount | ( |  | ) | const `[virtual]`

Return the number of unmatched completed close/barEntry calls.

Returns:
  the number of unmatched completed close/barEntry calls.

virtual Status getStatus | ( |  | ) | const `[virtual]`

Return the current thread gate status.

Returns:
  the current thread gate status

virtual void setCloseCount | ( | int32_t | cClose | ) | `[protected, virtual]`

Specify the number of unmatched completed close/barEntry calls.

The caller must have the gate closed/closing.

Parameters:

  | cClose | the number of unmatched completed close/barEntry calls.

virtual Thread::View getClosingThread | ( |  | ) | const `[protected, virtual]`

Return the thread that is closing the gate.

Returns:
  the thread that is closing the gate

virtual void setClosingThread | ( | Thread::View | vThread | ) | `[protected, virtual]`

Specify the thread id that is closing the gate.

The caller must be synchronized on the thread gate.

Parameters:

  | vThread | the thread id that is closing the gate.

virtual Status updateStatus | ( | Status | nStatus | ) | `[protected, virtual]`

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

virtual int64_t doWait | ( | int64_t | cMillis | ) | `[protected, virtual]`

Wait up to the specified number of milliseconds for notification.

Caller must be synchronized on this gate.

Parameters:

  | cMillis | the number of milliseconds to wait;; pass INFINITE for forever or IMMEDIATE for no wait

Returns:
  the remaining wait time in milliseconds

The documentation for this class was generated from the following file:

- coherence/util/ThreadGate.hpp

Copyright © 2000, 2010, Oracle and/or its affiliates. All rights reserved.