Boost C++ Libraries

...one of the most highly regarded and expertly designed C++ library projects in the world. Herb Sutter and Andrei Alexandrescu, C++ Coding Standards

This is the documentation for a snapshot of the develop branch, built from commit c5994560ca.
PrevUpHomeNext

Class semaphore

boost::sync::semaphore

Synopsis

// In header: <boost/sync/semaphore.hpp>


class semaphore {
public:
  // construct/copy/destruct
  explicit semaphore(unsigned int = 0);
  semaphore(semaphore const &) = delete;
  semaphore & operator=(semaphore const &) = delete;
  ~semaphore();

  // public member functions
  void post();
  void wait();
  bool try_wait();
  template<typename Time> bool timed_wait(const Time &);
  template<typename Duration> bool wait_for(const Duration &);
  template<typename TimePoint> bool wait_until(const TimePoint &);
};

Description

semaphore public construct/copy/destruct

  1. explicit semaphore(unsigned int initial_count = 0);

    Constructs a semaphore object.

    Throws: if an error occurs.

    Parameters:

    initial_count

    The initial value of the semaphore. There may be an implementation-defined upper limit for the counter value, but it is safe to assume that values up to INT_MAX are supported.

  2. semaphore(semaphore const &) = delete;
  3. semaphore & operator=(semaphore const &) = delete;
  4. ~semaphore();

    Destroys the object

    Requires:

    No thread is waiting on the semaphore

semaphore public member functions

  1. void post();

    Increments the semaphore counter. If one or multiple threads are blocked waiting for the semaphore, then one of these threads returns successfully from its wait function. It is unspecified which thread is released from the wait function.

    Memory Ordering: release

    [Note] Note

    The implementation may have an upper limit for the semaphore counter, upon exceeding which the behavior is unspecified. It is safe to assume that values up to INT_MAX are supported.

    Throws: if an error occurs.

  2. void wait();

    If the semaphore counter is greater than zero, decrements the counter and returns. If the semaphore value is not greater than zero, then the calling thread blocks until it can decrement the counter.

    Memory Ordering: acquire

    Throws: if an error occurs.

  3. bool try_wait();

    If the semaphore counter is greater than zero, decrements the counter and returns true. If the semaphore value is not greater than zero, returns false.

    Memory Ordering: acquire, if successful, relaxed otherwise

    Throws: if an error occurs.

  4. template<typename Time> bool timed_wait(const Time & timeout);

    If the semaphore counter is greater than zero, decrements the counter and returns true. If the semaphore value is not greater than zero, then the calling thread blocks until it can decrement the counter or the specified timeout expires.

    Memory Ordering: acquire, if successful, relaxed otherwise

    Throws: if an error occurs.

    [Note] Note

    In order to use this method, a supplementary header must be included from boost/sync/support to enable support for particular time units.

    Parameters:

    timeout

    The timeout for the operation to complete. The timeout can be specified either as an absolute time point or as a duration. In the latter case the time is measured according to the system clock.

    Returns:

    If the timeout expires, the function returns false. If the semaphore counter is decremented, the function returns true.

  5. template<typename Duration> bool wait_for(const Duration & duration);

    If the semaphore counter is greater than zero, decrements the counter and returns true. If the semaphore value is not greater than zero, then the calling thread blocks until it can decrement the counter or the specified timeout expires.

    Memory Ordering: acquire, if successful, relaxed otherwise

    Throws: if an error occurs.

    [Note] Note

    In order to use this method, a supplementary header must be included from boost/sync/support to enable support for particular time units.

    Parameters:

    duration

    The timeout for the operation to complete. The timeout should be a duration, which is measured according to the system clock.

    Returns:

    If the timeout expires, the function returns false. If the semaphore counter is decremented, the function returns true.

  6. template<typename TimePoint> bool wait_until(const TimePoint & timeout);

    If the semaphore counter is greater than zero, decrements the counter and returns true. If the semaphore value is not greater than zero, then the calling thread blocks until it can decrement the counter or the specified timeout expires.

    Memory Ordering: acquire, if successful, relaxed otherwise

    Throws: if an error occurs.

    [Note] Note

    In order to use this method, a supplementary header must be included from boost/sync/support to enable support for particular time units.

    Parameters:

    timeout

    The timeout for the operation to complete. The timeout should be an absolute time point.

    Returns:

    If the timeout expires, the function returns false. If the semaphore counter is decremented, the function returns true.


PrevUpHomeNext