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 aquired
      {
      // ...
      // ...
      } // 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
 Determiune 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 manged 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.
virtual Counter::Handle getCounter () const
 Return the thread local counter object.

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]

Determiune 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 threadgate.

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

virtual Counter::Handle getCounter (  )  const [protected, virtual]

Return the thread local counter object.

Returns:
the thread local counter object


The documentation for this class was generated from the following file: Copyright (c) 2000-2008 Oracle. All rights reserved.