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/aborted. It has to provide three functions: ExceptionFactory::timeout() - that returns a semaphore_timed_out exception by default, ExceptionFactory::broken() - that returns a broken_semaphore exception by default, and ExceptionFactory::aborted() - that returns a semaphore_aborted exception by default.

#include <seastar/core/semaphore.hh>

Inheritance diagram for seastar::basic_semaphore< ExceptionFactory, Clock >:

Public Types

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

Public Member Functions

 basic_semaphore (size_t count) noexcept(std::is_nothrow_default_constructible_v< exception_factory >)
 
 basic_semaphore (size_t count, exception_factory &&factory) noexcept(std::is_nothrow_move_constructible_v< exception_factory >)
 
 basic_semaphore (basic_semaphore &&other) noexcept(std::is_nothrow_move_constructible_v< exception_factory >)
 
basic_semaphoreoperator= (basic_semaphore &&other) noexcept(std::is_nothrow_move_assignable_v< exception_factory >)
 
future wait (size_t nr=1) noexcept
 
future wait (time_point timeout, size_t nr=1) noexcept
 
future wait (abort_source &as, size_t nr=1) noexcept
 
future wait (duration timeout, size_t nr=1) noexcept
 
void signal (size_t nr=1) noexcept
 
void consume (size_t nr=1) noexcept
 Consume the specific number of units without blocking. More...
 
bool try_wait (size_t nr=1) noexcept
 
size_t current () const noexcept
 
ssize_t available_units () const noexcept
 
size_t waiters () const noexcept
 Returns the current number of waiters.
 
void broken () noexcept
 
template<typename Exception >
void broken (const Exception &ex) noexcept
 
void broken (std::exception_ptr ex) noexcept
 
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 () noexcept
 Returns the maximum number of units the semaphore counter can hold.
 

Constructor & Destructor Documentation

◆ basic_semaphore() [1/2]

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

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.

◆ basic_semaphore() [2/2]

template<typename ExceptionFactory , typename Clock = typename timer<>::clock>
seastar::basic_semaphore< ExceptionFactory, Clock >::basic_semaphore ( basic_semaphore< ExceptionFactory, Clock > &&  other)
inlinenoexcept

Move-constructs a semaphore object from a moved-from semaphore object, inheriting the number of units from the moved-from semaphore. The moved-from semaphore must be unused.

Parameters
otherthe moved-from semaphore object.

Member Function Documentation

◆ available_units()

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

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 ( )
inlinenoexcept

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)
inlinenoexcept

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)
inlinenoexcept

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
inlinenoexcept

Returns the number of units available in the counter.

Does not take into account any waiters.

◆ operator=()

template<typename ExceptionFactory , typename Clock = typename timer<>::clock>
basic_semaphore & seastar::basic_semaphore< ExceptionFactory, Clock >::operator= ( basic_semaphore< ExceptionFactory, Clock > &&  other)
inlinenoexcept

Move-assigns a semaphore object from a moved-from semaphore object, inheriting the number of units from the moved-from semaphore. The number of units of the assigned semaphore is overwritten by the the moved-from number of units. Both the moved-to and moved-from semaphores must be unused.

Parameters
otherthe moved-from semaphore object.

◆ signal()

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

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)
inlinenoexcept

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/4]

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

Waits until at least a specific number of units are available in the counter, and reduces the counter by that amount of units. The request can be aborted using an abort_source.

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

◆ wait() [2/4]

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

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 a broken_semaphore exception.

◆ wait() [3/4]

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

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() [4/4]

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

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 a broken_semaphore exception.

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