Seastar
High performance C++ framework for concurrent servers
All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Modules Pages
Classes | Typedefs | Functions
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<std::invocable Func>
requires (!std::is_nothrow_move_constructible_v<Func>)
futurize_t< std::invoke_result_t< Func > > seastar::with_shared (shared_mutex &sm, Func &&func) noexcept
 
template<std::invocable Func>
requires (!std::is_nothrow_move_constructible_v<Func>)
futurize_t< std::invoke_result_t< Func > > seastar::with_lock (shared_mutex &sm, Func &&func) noexcept
 
template<internal::FutureBasicSharedLockable T>
future< std::shared_lock< T > > seastar::get_shared_lock (T &t)
 Construct a RAII-based shared lock corresponding to a given object. More...
 
template<internal::FutureBasicLockable T>
future< std::unique_lock< T > > seastar::get_unique_lock (T &t)
 Construct a RAII-based unique lock corresponding to a given object. More...
 
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<std::invocable Func>
futurize_t< std::invoke_result_t< Func > > with_shared (shared_mutex &sm, Func &&func) noexcept
 
template<std::invocable Func>
futurize_t< std::invoke_result_t< Func > > with_lock (shared_mutex &sm, Func &&func) noexcept
 

Typedef Documentation

◆ semaphore

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
semThe semaphore to take units from
unitsNumber of units to consume

◆ get_shared_lock()

template<internal::FutureBasicSharedLockable T>
future< std::shared_lock< T > > seastar::get_shared_lock ( T &  t)

Construct a RAII-based shared lock corresponding to a given object.

Since constructors cannot be exectued asynchronously, use this function to shared lock the passed object and construct an std::shared_lock that will unlock it when the lock is being destroyed.

The caller is responsible for keeping the passed object alive at least until the returned lock is destroyed.

◆ get_unique_lock()

template<internal::FutureBasicLockable T>
future< std::unique_lock< T > > seastar::get_unique_lock ( T &  t)

Construct a RAII-based unique lock corresponding to a given object.

Since constructors cannot be exectued asynchronously, use this function to lock the passed object and construct an std::unique_lock that will unlock it when the lock is being destroyed.

The caller is responsible for keeping the passed object alive at least until the returned lock is destroyed.

◆ 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
funcfunction to be executed
gthe 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
funcfunction to be executed
gthe gate. Caller must make sure that it outlives this function.
Returns
whatever func returns
Examples
closeable_test.cc.

◆ with_lock()

template<std::invocable Func>
futurize_t< std::invoke_result_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
sma shared_mutex guarding access to the shared resource
funccallable object to invoke while the mutex is held for shared access
Returns
whatever func returns, as a future

◆ with_shared()

template<std::invocable Func>
futurize_t< std::invoke_result_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
sma shared_mutex guarding access to the shared resource
funccallable object to invoke while the mutex is held for shared access
Returns
whatever func returns, as a future