Seastar
High performance C++ framework for concurrent servers
|
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() |
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 |
using seastar::semaphore = typedef basic_semaphore<semaphore_default_exception_factory> |
default basic_semaphore specialization that throws semaphore specific exceptions on error conditions.
|
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.
|
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.
sem | The semaphore to take units from |
units | Number of units to consume |
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.
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.
|
related |
Executes the function func
if the gate g
can be entered and later on, properly left.
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
func
returns.
|
related |
Executes the function func
making sure the gate g
is properly entered and later on, properly left.
func | function to be executed |
g | the gate. Caller must make sure that it outlives this function. |
func
returns
|
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.
sm | a shared_mutex guarding access to the shared resource |
func | callable object to invoke while the mutex is held for shared access |
func
returns, as a future
|
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.
sm | a shared_mutex guarding access to the shared resource |
func | callable object to invoke while the mutex is held for shared access |
func
returns, as a future