Seastar
High performance C++ framework for concurrent servers
Classes | Public Types | Public Member Functions | Static Public Member Functions | List of all members
seastar::basic_semaphore< ExceptionFactory, Clock > Class Template Reference

Detailed Description

template<typename ExceptionFactory, typename Clock = typename timer<>::clock>
class seastar::basic_semaphore< ExceptionFactory, Clock >

Counted resource guard.

This is a standard computer science semaphore, adapted for futures. You can deposit units into a counter, or take them away. Taking units from the counter may wait if not enough units are available.

To support exceptional conditions, a broken() method is provided, which causes all current waiters to stop waiting, with an exceptional future returned. This allows causing all fibers that are blocked on a semaphore to continue. This is similar to POSIX's pthread_cancel(), with wait() acting as a cancellation point.

Template Parameters
ExceptionFactorytemplate parameter allows modifying a semaphore to throw customized exceptions on timeout/broken(). It has to provide two static functions ExceptionFactory::timeout() and ExceptionFactory::broken() which return corresponding exception object.

#include <semaphore.hh>

Public Types

using duration = typename timer< Clock >::duration
 
using clock = typename timer< Clock >::clock
 
using time_point = typename timer< Clock >::time_point
 

Public Member Functions

 basic_semaphore (size_t count)
 
future wait (size_t nr=1)
 
future wait (time_point timeout, size_t nr=1)
 
future wait (duration timeout, size_t nr=1)
 
void signal (size_t nr=1)
 
void consume (size_t nr=1)
 Consume the specific number of units without blocking. More...
 
bool try_wait (size_t nr=1)
 
size_t current () const
 
ssize_t available_units () const
 
size_t waiters () const
 Returns the current number of waiters.
 
void broken ()
 
template<typename Exception >
void broken (const Exception &ex)
 
void broken (std::exception_ptr ex)
 
void ensure_space_for_waiters (size_t n)
 Reserve memory for waiters so that wait() will not throw.
 

Static Public Member Functions

static constexpr size_t max_counter ()
 Returns the maximum number of units the semaphore counter can hold.
 

Constructor & Destructor Documentation

◆ basic_semaphore()

template<typename ExceptionFactory, typename Clock = typename timer<>::clock>
seastar::basic_semaphore< ExceptionFactory, Clock >::basic_semaphore ( size_t  count)
inline

Constructs a semaphore object with a specific number of units in its internal counter. E.g., starting it at 1 is suitable for use as an unlocked mutex.

Parameters
countnumber of initial units present in the counter.

Member Function Documentation

◆ available_units()

template<typename ExceptionFactory, typename Clock = typename timer<>::clock>
ssize_t seastar::basic_semaphore< ExceptionFactory, Clock >::available_units ( ) const
inline

Returns the number of available units.

Takes into account units consumed using consume() and therefore may return a negative value.

◆ broken() [1/2]

template<typename ExceptionFactory, typename Clock = typename timer<>::clock>
void seastar::basic_semaphore< ExceptionFactory, Clock >::broken ( )
inline

Signal to waiters that an error occurred. wait() will see an exceptional future<> containing a broken_semaphore exception. The future is made available immediately.

◆ broken() [2/2]

template<typename ExceptionFactory, typename Clock = typename timer<>::clock>
template<typename Exception >
void seastar::basic_semaphore< ExceptionFactory, Clock >::broken ( const Exception &  ex)
inline

Signal to waiters that an error occurred. wait() will see an exceptional future<> containing the provided exception parameter. The future is made available immediately.

◆ consume()

template<typename ExceptionFactory, typename Clock = typename timer<>::clock>
void seastar::basic_semaphore< ExceptionFactory, Clock >::consume ( size_t  nr = 1)
inline

Consume the specific number of units without blocking.

Consume the specific number of units now, regardless of how many units are available in the counter, and reduces the counter by that amount of units. This operation may cause the counter to go negative.

Parameters
nrAmount of units to consume (default 1).

◆ current()

template<typename ExceptionFactory, typename Clock = typename timer<>::clock>
size_t seastar::basic_semaphore< ExceptionFactory, Clock >::current ( ) const
inline

Returns the number of units available in the counter.

Does not take into account any waiters.

◆ signal()

template<typename ExceptionFactory, typename Clock = typename timer<>::clock>
void seastar::basic_semaphore< ExceptionFactory, Clock >::signal ( size_t  nr = 1)
inline

Deposits a specified number of units into the counter.

The counter is incremented by the specified number of units. If the new counter value is sufficient to satisfy the request of one or more waiters, their futures (in FIFO order) become ready, and the value of the counter is reduced according to the amount requested.

Parameters
nrNumber of units to deposit (default 1).

◆ try_wait()

template<typename ExceptionFactory, typename Clock = typename timer<>::clock>
bool seastar::basic_semaphore< ExceptionFactory, Clock >::try_wait ( size_t  nr = 1)
inline

Attempts to reduce the counter value by a specified number of units.

If sufficient units are available in the counter, and if no other fiber is waiting, then the counter is reduced. Otherwise, nothing happens. This is useful for "opportunistic" waits where useful work can happen if the counter happens to be ready, but when it is not worthwhile to wait.

Parameters
nrnumber of units to reduce the counter by (default 1).
Returns
true if the counter had sufficient units, and was decremented.

◆ wait() [1/3]

template<typename ExceptionFactory, typename Clock = typename timer<>::clock>
future seastar::basic_semaphore< ExceptionFactory, Clock >::wait ( size_t  nr = 1)
inline

Waits until at least a specific number of units are available in the counter, and reduces the counter by that amount of units.

Note
Waits are serviced in FIFO order, though if several are awakened at once, they may be reordered by the scheduler.
Parameters
nrAmount of units to wait for (default 1).
Returns
a future that becomes ready when sufficient units are available to satisfy the request. If the semaphore was broken(), may contain an exception.

◆ wait() [2/3]

template<typename ExceptionFactory, typename Clock = typename timer<>::clock>
future seastar::basic_semaphore< ExceptionFactory, Clock >::wait ( time_point  timeout,
size_t  nr = 1 
)
inline

Waits until at least a specific number of units are available in the counter, and reduces the counter by that amount of units. If the request cannot be satisfied in time, the request is aborted.

Note
Waits are serviced in FIFO order, though if several are awakened at once, they may be reordered by the scheduler.
Parameters
timeoutexpiration time.
nrAmount of units to wait for (default 1).
Returns
a future that becomes ready when sufficient units are available to satisfy the request. On timeout, the future contains a semaphore_timed_out exception. If the semaphore was broken(), may contain an exception.

◆ wait() [3/3]

template<typename ExceptionFactory, typename Clock = typename timer<>::clock>
future seastar::basic_semaphore< ExceptionFactory, Clock >::wait ( duration  timeout,
size_t  nr = 1 
)
inline

Waits until at least a specific number of units are available in the counter, and reduces the counter by that amount of units. If the request cannot be satisfied in time, the request is aborted.

Note
Waits are serviced in FIFO order, though if several are awakened at once, they may be reordered by the scheduler.
Parameters
timeouthow long to wait.
nrAmount of units to wait for (default 1).
Returns
a future that becomes ready when sufficient units are available to satisfy the request. On timeout, the future contains a semaphore_timed_out exception. If the semaphore was broken(), may contain an exception.

The documentation for this class was generated from the following file: