Fibers

Detailed Description

Fibers of execution.

Seastar continuations are normally short, but often chained to one another, so that one continuation does a bit of work and then schedules another continuation for later. Such chains can be long, and often even involve loopings - see for example repeat. We call such chains "fibers" of execution.

These fibers are not threads - each is just a string of continuations - but they share some common requirements with traditional threads. For example, we want to avoid one fiber getting starved while a second fiber continuously runs its continuations one after another. As another example, fibers may want to communicate - e.g., one fiber produces data that a second fiber consumes, and we wish to ensure that both fibers get a chance to run, and that if one stops prematurely, the other doesn't hang forever.

Consult the following table to see which APIs are useful for fiber tasks:

Task	APIs
Repeat a blocking task indefinitely	keep_doing()
Repeat a blocking task, then exit	repeat(), do_until()
Provide mutual exclusion between two tasks	semaphore, shared_mutex
Pass a stream of data between two fibers	seastar::pipe
Safely shut down a resource	seastar::gate
Hold on to an object while a fiber is running	do_with()

Classes
class	seastar::abort_on_expiry< Clock >
class	seastar::abort_requested_exception
class	seastar::abort_source
class	seastar::broken_condition_variable
class	seastar::condition_variable_timed_out
class	seastar::condition_variable
	Conditional variable. More...
class	seastar::gate_closed_exception
class	seastar::gate
class	seastar::broken_pipe_exception
class	seastar::unread_overflow_exception
class	seastar::pipe< T >
	A fixed-size pipe for communicating between two fibers. More...
class	seastar::pipe_reader< T >
	Read side of a seastar::pipe. More...
class	seastar::pipe_writer< T >
	Write side of a seastar::pipe. More...
class	seastar::basic_rwlock< Clock >
class	seastar::broken_semaphore
class	seastar::semaphore_timed_out
class	seastar::semaphore_aborted
struct	seastar::semaphore_default_exception_factory
class	seastar::named_semaphore_timed_out
class	seastar::broken_named_semaphore
class	seastar::named_semaphore_aborted
struct	seastar::named_semaphore_exception_factory
class	seastar::basic_semaphore< ExceptionFactory, Clock >
	Counted resource guard. More...
class	seastar::semaphore_units< ExceptionFactory, Clock >
class	seastar::shared_mutex
	Shared/exclusive mutual exclusion. More...

Typedefs
using	seastar::rwlock = basic_rwlock<>
using	seastar::semaphore = basic_semaphore< semaphore_default_exception_factory >
using	seastar::named_semaphore = basic_semaphore< named_semaphore_exception_factory >

Functions
template<typename ExceptionFactory , typename Clock = typename timer<>::clock>
semaphore_units< ExceptionFactory, Clock >	seastar::consume_units (basic_semaphore< ExceptionFactory, Clock > &sem, size_t units) noexcept
	Consume units from semaphore temporarily. More...
template<typename Func >
std::enable_if_t<!std::is_nothrow_move_constructible_v< Func >, futurize_t< std::result_of_t< Func()> > >	seastar::with_shared (shared_mutex &sm, Func &&func) noexcept
template<typename Func >
std::enable_if_t<!std::is_nothrow_move_constructible_v< Func >, futurize_t< std::result_of_t< Func()> > >	seastar::with_lock (shared_mutex &sm, Func &&func) noexcept
template<typename Func >
auto	with_gate (gate &g, Func &&func)
template<typename Func >
auto	try_with_gate (gate &g, Func &&func) noexcept
void	seastar::basic_semaphore< ExceptionFactory, Clock >::broken (std::exception_ptr ex) noexcept
template<typename Func >
std::enable_if_t< std::is_nothrow_move_constructible_v< Func >, futurize_t< std::result_of_t< Func()> > >	with_shared (shared_mutex &sm, Func &&func) noexcept
template<typename Func >
std::enable_if_t< std::is_nothrow_move_constructible_v< Func >, futurize_t< std::result_of_t< Func()> > >	with_lock (shared_mutex &sm, Func &&func) noexcept

Typedef Documentation

semaphore

using seastar::semaphore = typedef basic_semaphore<semaphore_default_exception_factory>

default basic_semaphore specialization that throws semaphore specific exceptions on error conditions.

Function Documentation

broken()

template<typename ExceptionFactory , typename Clock >

void seastar::basic_semaphore< ExceptionFactory, Clock >::broken ( std::exception_ptr  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_units()

template<typename ExceptionFactory , typename Clock = typename timer<>::clock>

semaphore_units<ExceptionFactory, Clock> seastar::consume_units ( basic_semaphore< ExceptionFactory, Clock > &  sem, size_t  units  )

noexcept

Consume units from semaphore temporarily.

Consume units from the semaphore and returns them when the semaphore_units object goes out of scope. This provides a safe way to temporarily take units from a semaphore and ensure that they are eventually returned under all circumstances (exceptions, premature scope exits, etc).

Unlike get_units(), this calls the non-blocking consume() API.

Unlike with_semaphore(), the scope of unit holding is not limited to the scope of a single async lambda.

Parameters

sem	The semaphore to take units from
units	Number of units to consume

try_with_gate()

template<typename Func >

auto try_with_gate ( gate &  g, Func &&  func  )

related

Executes the function func if the gate g can be entered and later on, properly left.

Parameters

func	function to be executed
g	the gate. Caller must make sure that it outlives this function.

If the gate is already closed, an exception future holding gate_closed_exception is returned, otherwise

Returns

whatever func returns.

with_gate()

template<typename Func >

auto with_gate ( gate &  g, Func &&  func  )

related

Executes the function func making sure the gate g is properly entered and later on, properly left.

Parameters

func	function to be executed
g	the gate. Caller must make sure that it outlives this function.

Returns

whatever func returns

with_lock()

template<typename Func >

std::enable_if_t< std::is_nothrow_move_constructible_v< Func >, futurize_t< std::result_of_t< Func()> > > with_lock ( shared_mutex &  sm, Func &&  func  )

related

Executes a function while holding exclusive access to a resource.

Executes a function while holding exclusive access to a resource. When the function returns, the mutex is automatically unlocked.

Parameters

sm	a shared_mutex guarding access to the shared resource
func	callable object to invoke while the mutex is held for shared access

Returns

whatever func returns, as a future

with_shared()

template<typename Func >

std::enable_if_t< std::is_nothrow_move_constructible_v< Func >, futurize_t< std::result_of_t< Func()> > > with_shared ( shared_mutex &  sm, Func &&  func  )

related

Executes a function while holding shared access to a resource.

Executes a function while holding shared access to a resource. When the function returns, the mutex is automatically unlocked.

Parameters

sm	a shared_mutex guarding access to the shared resource
func	callable object to invoke while the mutex is held for shared access

Returns

whatever func returns, as a future