Oracle Coherence for C++ API
Release 3.6.1.0

E18813-01

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 (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:
Copyright © 2000, 2010, Oracle and/or its affiliates. All rights reserved.