Class execution_context encapsulates context switching and manages the associated context' stack (allocation/deallocation).

execution_context allocates the context stack (using its StackAllocator argument) and creates a control structure on top of it. This structure is responsible for managing context' stack. Instances of execution_context, associated with a specific context, share the ownership of the control structure. If the last reference goes out of scope, the control structure is destroyed and the stack gets deallocated via the StackAllocator.

execution_context is copy-constructible, move-constructible, copy-assignable and move-assignable.

execution_context maintains a static (thread-local) pointer, accessed by execution_context::current(), pointing to the active context. On each context switch the pointer is updated. The usage of this global pointer makes the context switch a little bit slower (due access of thread local storage) but has some advantages. It allows to access the control structure of the current active context from arbitrary code paths required in order to support segmented stacks, which require to call certain maintenance functions (like __splitstack_getcontext() etc.) before each context switch (each context switch exchanges the stack).

execution_context expects a function/functor with signature void(void* vp) (vp is the data passed at the first invocation of ecv1::operator()()).

usage of execution_context

int n=35;
boost::context::v1::execution_context sink(boost::context::v1::execution_context::current());
boost::context::v1::execution_context source(
    [n,&sink](void*)mutable{
        int a=0;
        int b=1;
        while(n-->0){
            sink(&a);
            auto next=a+b;
            a=b;
            b=next;
        }
    });
for(int i=0;i<10;++i){
    std::cout<<*(int*)source()<<" ";
}

output:
    0 1 1 2 3 5 8 13 21 34

This simple example demonstrates the basic usage of execution_context. The context sink, returned by execution_context::current(), represents the main-context (function main() running) and is one of the captured parameters in the lambda expression. The lambda that calculates the Fibonacci numbers is executed inside the context represented by source. Calculated Fibonacci numbers are transferred between the two context' via expression sink(&a) (and returned by source()).

The locale variables a, b and next remain their values during each context switch (yield(a)). This is possible because ctx owns a stack (exchanged by context switch).

inverting the control flow

/*
 * grammar:
 *   P ---> E '\0'
 *   E ---> T {('+'|'-') T}
 *   T ---> S {('*'|'/') S}
 *   S ---> digit | '(' E ')'
 */
class Parser{
    // implementation omitted; see examples directory
};

std::istringstream is("1+1");
bool done=false;
std::exception_ptr except;

// create handle to main execution context
auto main_ctx(boost::context::v1::execution_context::current());
// execute parser in new execution context
boost::context::v1::execution_context source(
        [&sink,&is,&done,&except](void*){
        // create parser with callback function
        Parser p(is,
                 [&sink](char ch){
                        // resume main execution context
                        sink(&ch);
                });
            try {
                // start recursive parsing
                p.run();
            } catch (...) {
                // store other exceptions in exception-pointer
                except = std::current_exception();
            }
            // set termination flag
            done=true;
            // resume main execution context
            sink();
        });

// user-code pulls parsed data from parser
// invert control flow
void* vp = source();
if (except) {
    std::rethrow_exception(except);
}
while( ! done) {
    printf("Parsed: %c\n",* static_cast<char*>(vp));
    vp = source();
    if (except) {
        std::rethrow_exception(except);
    }
}

output:
    Parsed: 1
    Parsed: +
    Parsed: 1

In this example a recursive descent parser uses a callback to emit a newly passed symbol. Using execution_context the control flow can be inverted, e.g. the user-code pulls parsed symbols from the parser - instead to get pushed from the parser (via callback).

The data (character) is transferred between the two execution_context.

If the code executed by execution_context emits an exception, the application is terminated. std::exception_ptr can be used to transfer exceptions between different execution contexts.

stack unwinding

Sometimes it is necessary to unwind the stack of an unfinished context to destroy local stack variables so they can release allocated resources (RAII pattern). The user is responsible for this task.

allocating control structures on top of stack

Allocating control structures on top of the stack requires to allocated the stack_context and create the control structure with placement new before execution_context is created.

// stack-allocator used for (de-)allocating stack
fixedsize_stack salloc( 4048);
// allocate stack space
stack_context sctx( salloc.allocate() );
// reserve space for control structure on top of the stack
void * sp = static_cast< char * >( sctx.sp) - sizeof( my_control_structure);
std::size_t size = sctx.size - sizeof( my_control_structure);
// placement new creates control structure on reserved space
my_control_structure * cs = new ( sp) my_control_structure( sp, size, sctx, salloc);
...
// destructing the control structure
cs->~my_control_structure();
...
struct my_control_structure  {
    // execution context
    execution_context ectx;

    template< typename StackAllocator >
    my_control_structure( void * sp, std::size_t size, stack_context sctx, StackAllocator salloc) :
        // create execution context
        ectx( std::allocator_arg, preallocated( sp, size, sctx), salloc, entry_func) {
    }
    ...
};

exception handling

If the function executed inside a execution_context emits ans exception, the application is terminated by calling std::terminate(). std::exception_ptr can be used to transfer exceptions between different execution contexts.

parameter passing

The void pointer argument passed to execution_context::operator(), in one context, is passed as the last argument of the context-function if the context is started for the first time. In all following invocations of execution_context::operator() the void pointer passed to execution_context::operator(), in one context, is returned by execution_context::operator() in the other context.

class X {
private:
    std::exception_ptr excptr_;
    boost::context::v1::execution_context caller_;
    boost::context::v1::execution_context callee_;

public:
    X() :
        excptr_(),
        caller_( boost::context::v1::execution_context::current() ),
        callee_( [=] (void * vp) {
                    try {
                        int i = * static_cast< int * >( vp);
                        std::string str = boost::lexical_cast<std::string>(i);
                        caller_( & str);
                    } catch (std::bad_cast const&) {
                        excptr_=std::current_exception();
                    }
                 })
    {}

    std::string operator()( int i) {
        void * ret = callee_( & i);
        if(excptr_){
            std::rethrow_exception(excptr_);
        }
        return * static_cast< std::string * >( ret);
    }
};

X x;
std::cout << x( 7) << std::endl;

output:
    7

Class execution_context

class execution_context {
public:
    static execution_context current() noexcept;

    template< typename Fn, typename ... Args >
    execution_context( Fn && fn, Args && ... args);

    template< typename StackAlloc, typename Fn, typename ... Args >
    execution_context( std::allocator_arg_t, StackAlloc salloc, Fn && fn, Args && ... args);

    template< typename StackAlloc, typename Fn, typename ... Args >
    execution_context( std::allocator_arg_t, preallocated palloc, StackAlloc salloc, Fn && fn, Args && ... args);

    execution_context( execution_context const& other) noexcept;
    execution_context( execution_context && other) noexcept;

    execution_context & operator=( execution_context const& other) noexcept;
    execution_context & operator=( execution_context && other) noexcept;

    explicit operator bool() const noexcept;
    bool operator!() const noexcept;

    void * operator()( void * vp = nullptr);

    template< typename Fn >
    void * operator()( exec_ontop_arg_t, Fn && fn, void * vp = nullptr);

    bool operator==( execution_context const& other) const noexcept;

    bool operator!=( execution_context const& other) const noexcept;

    bool operator<( execution_context const& other) const noexcept;

    bool operator>( execution_context const& other) const noexcept;

    bool operator<=( execution_context const& other) const noexcept;

    bool operator>=( execution_context const& other) const noexcept;

    template< typename charT, class traitsT >
    friend std::basic_ostream< charT, traitsT > &
    operator<<( std::basic_ostream< charT, traitsT > & os, execution_context const& other);
};

Static member function current()

static execution_context current() noexcept;

Constructor

template< typename Fn, typename ... Args >
execution_context( Fn && fn, Args && ... args);

template< typename StackAlloc, typename Fn, typename ... Args >
execution_context( std::allocator_arg_t, StackAlloc salloc, Fn && fn, Args && ... args);

template< typename StackAlloc, typename Fn, typename ... Args >
execution_context( std::allocator_arg_t, preallocated palloc, StackAlloc salloc, Fn && fn, Args && ... args);

Copy constructor

execution_context( execution_context const& other) noexcept;

Move constructor

execution_context( execution_context && other) noexcept;

Copy assignment operator

execution_context & operator=( execution_context const& other) noexcept;

Move assignment operator

execution_context & operator=( execution_context && other) noexcept;

Member function operator bool()

explicit operator bool() const noexcept;

Member function operator!()

bool operator!() const noexcept;

Member function operator()()

void * operator()( void * vp = nullptr) noexcept;

Member function operator(exec_ontop_arg_t)()

template< typename Fn >
void * operator()( exec_ontop_arg_t, Fn && fn, void * vp = nullptr);

Member function operator==()

bool operator==( execution_context const& other) const noexcept;

Member function operator!=()

bool operator!=( execution_context const& other) const noexcept;

Member function operator<()

bool operator<( execution_context const& other) const noexcept;

Member function operator>()

bool operator>( execution_context const& other) const noexcept;

Member function operator<=()

bool operator<=( execution_context const& other) const noexcept;

Member function operator>=()

bool operator>=( execution_context const& other) const noexcept;

Non-member function operator<<()

template< typename charT, class traitsT >
std::basic_ostream< charT, traitsT > &
operator<<( std::basic_ostream< charT, traitsT > & os, execution_context const& other);