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

ExceptionFactory template 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_semaphore &	operator= (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

count number 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

other the 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

nr	Amount 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

other the 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

nr	Number 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

nr	number 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

as	abort source.
nr	Amount 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

timeout	how long to wait.
nr	Amount 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

nr	Amount 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

timeout	expiration time.
nr	Amount 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:

seastar/core/semaphore.hh

Detailed Description

Public Types

Public Member Functions

Static Public Member Functions

Constructor & Destructor Documentation

◆ basic_semaphore() [1/2]

◆ basic_semaphore() [2/2]

Member Function Documentation

◆ available_units()

◆ broken() [1/2]

◆ broken() [2/2]

◆ consume()

◆ current()

◆ operator=()

◆ signal()

◆ try_wait()

◆ wait() [1/4]

◆ wait() [2/4]

◆ wait() [3/4]

◆ wait() [4/4]