Chapter 1. Spawn

Oliver Kowalke

Distributed under the Boost Software License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)

spawn_fiber() creates a new fiber and starts new stackful thread of execution. The spawn_fiber() function is a high-level wrapper over the Boost.Context library. This function enables programs to implement asynchronous logic in a synchronous manner. Suspending/resuming of the spawned fiber is controlled by Boost.Asio.

	Note
	In contrast to Boost.Asio that uses the deprecated Boost.Coroutine library for its boost::asio::spawn() the implementation of Boost.Spawn is based only on Boost.Context.

Usage

void do_echo(boost::spawn::yield_context yield) {
    try {
        char data[128];
        for (;;) {
            std::size_t length = my_socket.async_read_some(boost::asio::buffer(data), yield);
            boost::asio::async_write(my_socket, boost::asio::buffer(data, length), yield);
        }
    } catch (std::exception const& e) {
        // ...
    }
}
// ...
boost::spawn_fiber(my_strand, do_echo);

This simple example demonstrates the basic usage of spawn_fiber(). Function do_echo is executed by a new fiber that has been created by spawn_fiber().

do_echo() gets suspended while asynchronous operations like async_read_some() and async_write() are started and resumed after the asynchronous operation completed. Therefore do_echo() does not require callbacks (the code looks like synchronous).

spawn_fiber()

#include <boost/spawn.hpp>

template< typename Function, typename StackAllocator = boost::context::default_stack >
auto spawn_fiber(Function && fn, StackAllocator && salloc = StackAllocator())

Effects:: This function is used to launch a new execution context on behalf of spawned fiber. Parameter fn is the fiber function and must have signature void(basic_yield_context<Handler>).

template< typename Handler, typename Function, typename StackAllocator = boost::context::default_stack >
auto spawn_fiber(Handler && hndlr, Function && fn, StackAllocator && salloc = StackAllocator())

Effects:: This function is used to launch a new execution context on behalf of spawned fiber, calling the specified handler hndlr when the fiber completes. hndlr provides an execution context (via the the handler invocation hook) for the fiber. The handler must have the signature void(). Parameter fn is the fiber function and must have signature void(basic_yield_context<Handler>).

template< typename Handler, typename Function, typename StackAllocator = boost::context::default_stack >
auto spawn_fiber(boost::spawn::basic_yield_context< Handler > ctx, Function && function, StackAllocator && salloc = StackAllocator())

Effects:: This function is used to launch a new execution context on behalf of spawned spawn. Parameter fn is the fiber function and must have signature void(basic_yield_context<Handler>). ctx identifies the current execution context as a parent of the new fiber. This specifies that the new fiber should inherit the execution context of the parent. For example, if the parent fiber is executing in a particular strand, then the new fiber will execute in the same strand.

template< typename Function, typename Executor, typename StackAllocator = boost::context::default_stack >
auto spawn_fiber(Executor const& ex, Function && function, StackAllocator && salloc = StackAllocator())

Effects:: This function is used to launch a new execution context on behalf of spawned fiber. Parameter fn is the fiber function and must have signature void(basic_yield_context<Handler>). ex identifies the executor that will run the fiber. The new fiber is implicitly given its own strand within this executor.

template< typename Function, typename Executor, typename StackAllocator = boost::context::default_stack >
auto spawn_fiber(boost::spawn::detail::net::strand< Executor > const& ex, Function && function, StackAllocator && salloc = StackAllocator())

Effects:: This function is used to launch a new execution context on behalf of spawned fiber. Parameter fn is the fiber function and must have signature void(basic_yield_context<Handler>). ex identifies the strand that will run the fiber.

template< typename Function, typename ExecutionContext, typename StackAllocator = boost::context::default_stack >
auto spawn_fiber(ExecutionContext & ctx, Function && function, StackAllocator && salloc = StackAllocator())

Effects:: This function is used to launch a new execution context on behalf of spawned fiber. Parameter fn is the fiber function and must have signature void(basic_yield_context<Handler>). ctx identifies the execution context that will run the fiber. The new fiber is implicitly given its own strand within this execution context.

Acknowledgments

I'd like to thank Casey Bodley.