Seastar threads

Detailed Description

Seastar threads provide an execution environment where blocking is tolerated; you can issue I/O, and wait for it in the same function, rather then establishing a callback to be called with future<>::then().

Seastar threads are not the same as operating system threads:

• seastar threads are cooperative; they are never preempted except at blocking points (see below)
• seastar threads always run on the same core they were launched on

Like other seastar code, seastar threads may not issue blocking system calls.

A seastar thread blocking point is any function that returns a future. you block by calling future<>::get(); this waits for the future to become available, and in the meanwhile, other seastar threads and seastar non-threaded code may execute.

Example:

seastar::thread th([] {
   sleep(5s).get();  // blocking point
});

An easy way to launch a thread and carry out some computation, and return a result from this execution is by using the seastar::async() function. The result is returned as a future, so that non-threaded code can wait for the thread to terminate and yield a result.

Classes
class	seastar::thread_attributes
	Class that holds attributes controling the behavior of a thread. More...
class	seastar::thread
	thread - stateful thread of execution More...

Functions
template<typename Func , typename... Args>
futurize_t< std::invoke_result_t< Func, Args... > >	seastar::async (thread_attributes attr, Func &&func, Args &&... args) noexcept
template<typename Func , typename... Args>
futurize_t< std::invoke_result_t< Func, Args... > >	seastar::async (Func &&func, Args &&... args) noexcept
template<typename Func >
	seastar::thread::thread (thread_attributes attr, Func func)
	Constructs a thread object that represents a thread of execution. More...
template<typename Func >
	seastar::thread::thread (Func func)
	Constructs a thread object that represents a thread of execution. More...
future	seastar::thread::join ()
	Waits for thread execution to terminate. More...

---

Class Documentation

seastar::thread_attributes

class seastar::thread_attributes

Class Members
optional< scheduling_group >	sched_group
size_t	stack_size

Function Documentation

async() [1/2]

template<typename Func , typename... Args>

futurize_t<std::invoke_result_t<Func, Args...> > seastar::async ( Func &&  func, Args &&...  args  )

inlinenoexcept

Executes a callable in a seastar thread.

Runs a block of code in a threaded context, which allows it to block (using future::get()). The result of the callable is returned as a future.

Parameters

func	a callable to be executed in a thread
args	a parameter pack to be forwarded to func.

Returns

whatever func returns, as a future.

async() [2/2]

template<typename Func , typename... Args>

futurize_t<std::invoke_result_t<Func, Args...> > seastar::async ( thread_attributes  attr, Func &&  func, Args &&...  args  )

inlinenoexcept

Executes a callable in a seastar thread.

Runs a block of code in a threaded context, which allows it to block (using future::get()). The result of the callable is returned as a future.

Parameters

attr	a thread_attributes instance
func	a callable to be executed in a thread
args	a parameter pack to be forwarded to func.

Returns

whatever func returns, as a future.

Example:

future<int> compute_sum(int a, int b) {
    thread_attributes attr = {};
    attr.sched_group = some_scheduling_group_ptr;
    return seastar::async(attr, [a, b] {
        // some blocking code:
        sleep(1s).get();
        return a + b;
    });
}

Examples

closeable_test.cc, and sharded_parameter_demo.cc.

join()

future seastar::thread::join ( )

inline

Waits for thread execution to terminate.

Waits for thread execution to terminate, and marks the thread object as not representing a running thread of execution.

thread() [1/2]

template<typename Func >

seastar::thread::thread ( Func  func )

inline

Constructs a thread object that represents a thread of execution.

Parameters

func	Callable object to execute in thread. The callable is called immediately.

thread() [2/2]

template<typename Func >

seastar::thread::thread ( thread_attributes  attr, Func  func  )

inline

Constructs a thread object that represents a thread of execution.

Parameters

attr	Attributes describing the new thread.
func	Callable object to execute in thread. The callable is called immediately.