bslmt_sluice

Detailed Description

Outline

• Purpose
• Classes
• Description
  • Supported Clock-Types
  • Usage
    • Example 1: Basic Usage

Purpose

Provide a "sluice" class.

Classes

• bslmt::Sluice: thread-aware sluice class

See also

bslmt_conditionimpl_win32

Description

This component provides a "sluice" class, bslmt::Sluice. A sluice is useful for controlling the release of threads from a common synchronization point. One or more threads may "enter" a bslmt::Sluice object (via the enter method), and then wait to be released (via either the wait or timedWait method). Either one waiting thread (via the signalOne method), or all waiting threads (via the signalAll method), may be signaled for release. In either case, bslmt::Sluice provides a guarantee against starvation; newly-entering threads will not indefinitely prevent threads that previously entered from being signaled.

Supported Clock-Types

bsls::SystemClockType supplies the enumeration indicating the system clock on which timeouts supplied to other methods should be based. If the clock type indicated at construction is bsls::SystemClockType::e_REALTIME, the absTime argument passed to the timedWait method should be expressed as an absolute offset since 00:00:00 UTC, January 1, 1970 (which matches the epoch used in bsls::SystemTime::now(bsls::SystemClockType::e_REALTIME). If the clock type indicated at construction is bsls::SystemClockType::e_MONOTONIC, the absTime argument passed to the timedWait method should be expressed as an absolute offset since the epoch of this clock (which matches the epoch used in bsls::SystemTime::now(bsls::SystemClockType::e_MONOTONIC).

Usage

This section illustrates intended use of this component.

Example 1: Basic Usage

bslmt::Sluice is intended to be used to implement other synchronization mechanisms. In particular, the functionality provided by bslmt::Sluice is useful for implementing a condition variable:

/// This class implements a condition variable based on `bslmt::Sluice`.
class MyCondition {
 
    // DATA
    bslmt::Sluice d_waitSluice;  // sluice object
 
  public:
    // MANIPULATORS
    void wait(bslmt::Mutex *mutex)
    {
        const void *token = d_waitSluice.enter();
        mutex->unlock();
        d_waitSluice.wait(token);
        mutex->lock();
    }
 
    void signal()
    {
        d_waitSluice.signalOne();
    }
 
    void broadcast()
    {
        d_waitSluice.signalAll();
    }
};