Component bslmt_sluice [Package bslmt]

Provide a "sluice" class. More...

Namespaces
namespace	bslmt

---

Detailed Description

Outline

• Purpose
• Classes
• Description
  • Supported Clock-Types
  • Usage

Purpose:

Provide a "sluice" class.

Classes:

bslmt::Sluice

thread-aware sluice class

See also:

Component 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:

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:

  class MyCondition {
      // This class implements a condition variable based on 'bslmt::Sluice'.

      // 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();
      }
  };