Seastar
High performance C++ framework for concurrent servers
Classes | Typedefs | Functions
Fibers

Fibers of execution. More...

Classes

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::rwlock
 
class  seastar::broken_semaphore
 
class  seastar::semaphore_timed_out
 
struct  seastar::semaphore_default_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::semaphore = basic_semaphore< semaphore_default_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)
 Consume units from semaphore temporarily. More...
 
template<typename Func >
auto with_gate (gate &g, Func &&func)
 
void seastar::basic_semaphore< ExceptionFactory, Clock >::broken (std::exception_ptr ex)
 
template<typename Func >
futurize_t< std::result_of_t< Func()> > with_shared (shared_mutex &sm, Func &&func)
 
template<typename Func >
futurize_t< std::result_of_t< Func()> > with_lock (shared_mutex &sm, Func &&func)
 

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, seastar::with_gate()
Hold on to an object while a fiber is running do_with()

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

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 
)

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

◆ 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

◆ with_lock()

template<typename 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
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<typename 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
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