Oliver
Kowalke
2014
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)

C++ Library for swiching different user ctx

# Context

# Overview

Boost.Context is a foundational library that provides a sort of cooperative multitasking on a single thread. By providing an abstraction of the current execution state in the current thread, including the stack (with local variables) and stack pointer, all registers and CPU flags, and the instruction pointer, a execution context represents a specific point in the application's execution path. This is useful for building higher-level abstractions, like coroutines, cooperative threads (userland threads) or an equivalent to C# keyword yield in C++.

callcc()/continuation provides the means to suspend the current execution path and to transfer execution control, thereby permitting another context to run on the current thread. This state full transfer mechanism enables a context to suspend execution from within nested functions and, later, to resume from where it was suspended. While the execution path represented by a continuation only runs on a single thread, it can be migrated to another thread at any given time.

A context switch between threads requires system calls (involving the OS kernel), which can cost more than thousand CPU cycles on x86 CPUs. By contrast, transferring control vias callcc()/continuation requires only few CPU cycles because it does not involve system calls as it is done within a single thread.

In order to use the classes and functions described here, you can either include the specific headers specified by the descriptions of each class or function, or include the master library header:

    #include <boost/context/all.hpp>

which includes all the other headers in turn.

All functions and classes are contained in the namespace boost::context.

This library requires C++11!

# Requirements

If Boost.Context uses fcontext_t (the default) as its implementation, it must be built for the particular compiler(s) and CPU architecture(s) being targeted. Using fcontext_t, Boost.Context includes assembly code and, therefore, requires GNU as and GNU preprocessor for supported POSIX systems, MASM for Windows/x86 systems and ARMasm for Windows/arm systems.

MASM64 (ml64.exe) is a part of Microsoft's Windows Driver Kit.

Please note that `address-model=64` must be given to bjam command line on 64bit Windows for 64bit build; otherwise 32bit code will be generated.

For cross-compiling the lib you must specify certain additional properties at bjam command line: `target-os`, `abi`, `binary-format`, `architecture` and `address-model`.

For safe SEH the property 'asmflags=\safeseh' must be specified at bjam command line.

# Context switching with call/cc

call/cc (call with current continuation) is a universal control operator (well-known from the programming language Scheme) that captures the current continuation as a first-class object and pass it as an argument to another continuation.

A continuation (abstract concept of functional programming languages) represents the state of the control flow of a program at a given point in time. Continuations can be suspended and resumed later in order to change the control flow of a program.

Modern micro-processors are registers machines; the content of processor registers represent a continuation of the executed program at a given point in time. Operating systems simulate parallel execution of programs on a single processor by switching between programs (context switch) by preserving and restoring the continuation, e.g. the content of all registers.

callcc()

callcc() is the C++ equivalent to Scheme's call/cc operator. It captures the current continuation (the rest of the computation; code after callcc()) and triggers a context switch. The context switch is achieved by preserving certain registers (including instruction and stack pointer), defined by the calling convention of the ABI, of the current continuation and restoring those registers of the resumed continuation. The control flow of the resumed continuation continues. The current continuation is suspended and passed as argument to the resumed continuation.

callcc() expects a context-function with signature `'continuation(continuation && c)'`. The parameter `c` represents the current continuation from which this continuation was resumed (e.g. that has called callcc()).

On return the context-function of the current continuation has to specify an continuation to which the execution control is transferred after termination of the current continuation.

If an instance with valid state goes out of scope and the context-function has not yet returned, the stack is traversed in order to access the control structure (address stored at the first stack frame) and continuation's stack is deallocated via the StackAllocator.

Segmented stacks are supported by callcc() using ucontext_t.

continuation

continuation represents a continuation; it contains the content of preserved registers and manages the associated stack (allocation/deallocation). continuation is a one-shot continuation - it can be used only once, after calling continuation::resume() or continuation::resume_with() it is invalidated.

continuation is only move-constructible and move-assignable.

As a first-class object continuation can be applied to and returned from a function, assigned to a variable or stored in a container.

A continuation is continued by calling `resume()`/`resume_with()`.

Usage

    namespace ctx=boost::context;
    int a;
    ctx::continuation source=ctx::callcc(
        [&a](ctx::continuation && sink){
            a=0;
            int b=1;
            for(;;){
                sink=sink.resume();
                int next=a+b;
                a=b;
                b=next;
            }
            return std::move(sink);
        });
    for (int j=0;j<10;++j) {
        std::cout << a << " ";
        source=source.resume();
    }

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

This simple example demonstrates the basic usage of call/cc as a generator. The continuation `sink` represents the main-continuation (function `main()`). `sink` is captured (current-continuation) by invoking callcc() and passed as parameter to the lambda.

Because the state is invalidated (one-shot continuation) by each call of continuation::resume(), the new state of the continuation, returned by continuation::resume(), needs to be assigned to `sink` after each call.

The lambda that calculates the Fibonacci numbers is executed inside the continuation represented by `source`. Calculated Fibonacci numbers are transferred between the two continuations via variable `a` (lambda capture reference).

The locale variables `b` and `next` remain their values during each context switch. This is possible due `source` has its own stack and the stack is exchanged by each context switch.

Parameter passing

Data can be transferred between two continuations via global pointers, calling wrappers (like `std::bind`) or lambda captures.

    namespace ctx=boost::context;
    int i=1;
    ctx::continuation c1=callcc([&i](ctx::continuation && c2){
                std::printf("inside c1,i==%d\n",i);
                i+=1;
                return c2.resume();
            });
    std::printf("i==%d\n",i);

    output:
        inside c1,i==1
        i==2

`callcc(<lambda>)` enters the lambda in continuation represented by `c1` with lambda capture reference `i=1`. The expression `c2.resume()` resumes the continuation `c2`. On return of `callcc(<lambda>)`, the variable `i` has the value of `i+1`.

Exception handling

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

Do not jump from inside a catch block and then re-throw the exception in another continuation.

Executing function on top of a continuation

Sometimes it is useful to execute a new function on top of a resumed continuation. For this purpose continuation::resume_with() has to be used. The function passed as argument must accept a rvalue reference to continuation and return `void`.

    namespace ctx=boost::context;
    int data=0;
    ctx::continuation c=ctx::callcc([&data](ctx::continuation && c) {
                        std::cout << "f1: entered first time: " << data << std::endl;
                        data+=1;
                        c=c.resume();
                        std::cout << "f1: entered second time: " << data << std::endl;
                        data+=1;
                        c=c.resume();
                        std::cout << "f1: entered third time: " << data << std::endl;
                        return std::move(c);
                    });
    std::cout << "f1: returned first time: " << data << std::endl;
    data+=1;
    c=c.resume();
    std::cout << "f1: returned second time: " << data << std::endl;
    data+=1;
    c=c.resume_with([&data](ctx::continuation && c){
                        std::cout << "f2: entered: " << data << std::endl;
                        data=-1;
                    });
    std::cout << "f1: returned third time" << std::endl;

    output:
        f1: entered first time: 0
        f1: returned first time: 1
        f1: entered second time: 2
        f1: returned second time: 3
        f2: entered: 4
        f1: entered third time: -1
        f1: returned third time

The expression `c.resume_with(...)` executes a lambda on top of continuation `c`, e.g. an additional stack frame is allocated on top of the stack. This lambda assigns `-1` to `data` and returns to the second invocation of `c.resume()`.

Another option is to execute a function on top of the continuation that throws an exception.

    namespace ctx=boost::context;
    struct my_exception : public std::runtime_error {
        ctx::continuation    c;
        my_exception(ctx::continuation && c_,std::string const& what) :
            std::runtime_error{ what },
            c{ std::move( c_) } {
        }
    };

    ctx::continuation c=ctx::callcc([](ctx::continuation && c) {
        for (;;) {
            try {
                std::cout << "entered" << std::endl;
                c=c.resume();
            } catch (my_exception & ex) {
                std::cerr << "my_exception: " << ex.what() << std::endl;
                return std::move(ex.c);
            }
        }
        return std::move(c);
    });
    c = c.resume_with(
           [](ctx::continuation && c){
               throw my_exception(std::move(c),"abc");
           });

    output:
        entered
        my_exception: abc

In this exception `my_exception` is throw from a function invoked on-top of continuation `c` and catched inside the `for`-loop.

Stack unwinding

On construction of continuation a stack is allocated. If the context-function returns the stack will be destructed. If the context-function has not yet returned and the destructor of an valid continuation instance (e.g. continuation::operator bool() returns `true`) is called, the stack will be destructed too.

Code executed by context-function must not prevent the propagation ofs the detail::forced_unwind exception. Absorbing that exception will cause stack unwinding to fail. Thus, any code that catches all exceptions must re-throw any pending detail::forced_unwind exception.

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 continuation is created.

The user is responsible for destructing the control structure at the top of the stack.

    namespace ctx=boost::context;
    // 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  {
        // captured continuation
        ctx::continuation   c;

        template< typename StackAllocator >
        my_control_structure(void * sp,std::size_t size,stack_context sctx,StackAllocator salloc) :
            // create captured continuation
            c{} {
            c=ctx::callcc(std::allocator_arg,preallocated(sp,size,sctx),salloc,entry_func);
        }
        ...
    };

Inverting the control flow

    namespace ctx=boost::context;
    /*
     * grammar:
     *   P ---> E '\0'
     *   E ---> T {('+'|'-') T}
     *   T ---> S {('*'|'/') S}
     *   S ---> digit | '(' E ')'
     */
    class Parser{
       char next;
       std::istream& is;
       std::function<void(char)> cb;

       char pull(){
            return std::char_traits<char>::to_char_type(is.get());
       }

       void scan(){
           do{
               next=pull();
           }
           while(isspace(next));
       }

    public:
       Parser(std::istream& is_,std::function<void(char)> cb_) :
          next(), is(is_), cb(cb_)
        {}

       void run() {
          scan();
          E();
       }

    private:
       void E(){
          T();
          while (next=='+'||next=='-'){
             cb(next);
             scan();
             T();
          }
       }

       void T(){
          S();
          while (next=='*'||next=='/'){
             cb(next);
             scan();
             S();
          }
       }

       void S(){
          if (isdigit(next)){
             cb(next);
             scan();
          }
          else if(next=='('){
             cb(next);
             scan();
             E();
             if (next==')'){
                 cb(next);
                 scan();
             }else{
                 throw std::runtime_error("parsing failed");
             }
          }
          else{
             throw std::runtime_error("parsing failed");
          }
       }
    };

    std::istringstream is("1+1");
    // execute parser in new continuation
    ctx::continuation source;
    // user-code pulls parsed data from parser
    // invert control flow
    char c;
    bool done=false;
    source=ctx::callcc(
            [&is,&c,&done](ctx::continuation && sink){
            // create parser with callback function
            Parser p(is,
                     [&sink,&c](char c_){
                        // resume main continuation
                        c=c_;
                        sink=sink.resume();
                     });
                // start recursive parsing
                p.run();
                // signal termination
                done=true;
                // resume main continuation
                return std::move(sink);
            });
    while(!done){
        printf("Parsed: %c\n",c);
        source=source.resume();
    }

    output:
        Parsed: 1
        Parsed: +
        Parsed: 1

In this example a recursive descent parser uses a callback to emit a newly passed symbol. Using call/cc 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 continuations.

## Implementations: fcontext_t, ucontext_t and WinFiber

fcontext_t

The implementation uses fcontext_t per default. fcontext_t is based on assembler and not available for all platforms. It provides a much better performance than ucontext_t (the context switch takes two magnitudes of order less CPU cycles; see section performance) and WinFiber.

Because the TIB (thread information block on Windows) is not fully described in the MSDN, it might be possible that not all required TIB-parts are swapped. Using WinFiber implementation migh be an alternative.

ucontext_t

As an alternative, ucontext_t can be used by compiling with `BOOST_USE_UCONTEXT` and b2 property `context-impl=ucontext`. ucontext_t might be available on a broader range of POSIX-platforms but has some disadvantages (for instance deprecated since POSIX.1-2003, not C99 conform).

callcc() supports Segmented stacks only with ucontext_t as its implementation.

WinFiber

With `BOOST_USE_WINFIB` and b2 property `context-impl=winfib` Win32-Fibers are used as implementation for callcc().

The first call of callcc() converts the thread into a Windows fiber by invoking `ConvertThreadToFiber()`. If desired, `ConvertFiberToThread()` has to be called by the user explicitly in order to release resources allocated by `ConvertThreadToFiber()` (e.g. after using boost.context).

## Class `continuation`

    #include <boost/context/continuation.hpp>

    class continuation {
    public:
        continuation() noexcept = default;

        ~continuation();

        continuation(continuation && other) noexcept;

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

        continuation(continuation const& other) noexcept = delete;
        continuation & operator=(continuation const& other) noexcept = delete;

        continuation resume();

        template<typename Fn>
        continuation resume_with(Fn && fn);

        explicit operator bool() const noexcept;

        bool operator!() const noexcept;

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

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

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

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

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

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

        template<typename charT,class traitsT>
        friend std::basic_ostream<charT,traitsT> &
        operator<<(std::basic_ostream<charT,traitsT> & os,continuation const& other) {

        void swap(continuation & other) noexcept;
    };

Constructor

    continuation() noexcept;

###

Effects:

  Creates a invalid continuation.

Throws:

  Nothing.

Destructor

    ~continuation();

###

Effects:

  Destructs the associated stack if `*this` is a valid continuation, e.g. continuation::operator bool() returns `true`.

Throws:

  Nothing.

Move constructor

    continuation(continuation && other) noexcept;

###

Effects:

  Moves underlying capture continuation to `*this`.

Throws:

  Nothing.

Move assignment operator

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

###

Effects:

  Moves the state of `other` to `*this` using move semantics.

Throws:

  Nothing.

Member function `operator()`()

    continuation resume();

    template<typename Fn>
    continuation resume_with(Fn && fn);

###

Effects:

  Captures current continuation and resumes `*this`. The function `resume_with`, is used to execute function `fn` in continuation `*this` (e.g. the stack frame of `fn` is allocated on stack of `*this`).

Returns:

  The continuation representing the continuation that has been suspended.

Note:

  Function `fn` needs to return void.

Note:

  The returned continuation indicates if the suspended continuation has terminated (return from context-function) via `bool operator()`.

Member function `operator bool`()

    explicit operator bool() const noexcept;

###

Returns:

  `true` if `*this` points to a captured continuation.

Throws:

  Nothing.

Member function `operator!`()

    bool operator!() const noexcept;

###

Returns:

  `true` if `*this` does not point to a captured continuation.

Throws:

  Nothing.

Member function `operator==`()

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

###

Returns:

  `true` if `*this` and `other` represent the same continuation, `false` otherwise.

Throws:

  Nothing.

Member function `operator!=`()

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

###

Returns:

  `! (other == * this)`

Throws:

  Nothing.

Member function `operator<`()

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

###

Returns:

  `true` if `*this != other` is true and the implementation-defined total order of `continuation` values places `*this` before `other`, false otherwise.

Throws:

  Nothing.

Member function `operator>`()

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

###

Returns:

  `other < * this`

Throws:

  Nothing.

Member function `operator<=`()

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

###

Returns:

  `! (other < * this)`

Throws:

  Nothing.

Member function `operator>=`()

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

###

Returns:

  `! (* this < other)`

Throws:

  Nothing.

Non-member function `operator<<()`

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

###

Effects:

  Writes the representation of `other` to stream `os`.

Returns:

  `os`

Call with current continuation

    #include <boost/context/continuation.hpp>

    template<typename Fn>
    continuation callcc(Fn && fn);

    template<typename StackAlloc,typename Fn>
    continuation callcc(std::allocator_arg_t,StackAlloc salloc,Fn && fn);

    template<typename StackAlloc,typename Fn>
    continuation callcc(std::allocator_arg_t,preallocated palloc,StackAlloc salloc,Fn && fn);

###

Effects:

  Captures current continuation and creates a new continuation prepared to execute `fn`. `fixedsize_stack` is used as default stack allocator (stack size == fixedsize_stack::traits::default_size()). The function with argument type `preallocated`, is used to create a user defined data (for instance additional control structures) on top of the stack.

Returns:

  The continuation representing the contexcontinuation that has been suspended.

Note:

  The returned continuation indicates if the suspended continuation has terminated (return from context-function) via `bool operator()`.

# Class execution_context (version 2)

execution_context is deprecated.

Include `execution_context.hpp` and pass `BOOST_EXECUTION_CONTEXT=2` and property `context-switch=ec` to b2 command-line in order to use execution_context (v2).

Segmented stacks (segmented-stacks=on), e.g. on demand growing stacks, are not supported by execution_context (v2).

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. The address of the control structure is stored in the first frame of context' stack (e.g. it can not directly accessed from within execution_context). In contrast to execution_context (v1) the ownership of the control structure is not shared (no member variable to control structure in execution_context). execution_context keeps internally a state that is moved by a call of execution_context::operator() (`*this` will be invalidated), e.g. after a calling execution_context::operator(), `*this` can not be used for an additional context switch.

execution_context is only move-constructible and move-assignable.

The moved state is assigned to a new instance of execution_context. This object becomes the first argument of the context-function, if the context was resumed the first time, or the first element in a tuple returned by execution_context::operator() that has been called in the resumed context. In contrast to execution_context (v1), the context switch is faster because no global pointer etc. is involved.

Segmented stacks are not supported by execution_context (v2).

On return the context-function of the current context has to specify an execution_context to which the execution control is transferred after termination of the current context.

If an instance with valid state goes out of scope and the context-function has not yet returned, the stack is traversed in order to access the control structure (address stored at the first stack frame) and context' stack is deallocated via the StackAllocator. The stack walking makes the destruction of execution_context slow and should be prevented if possible.

execution_context expects a context-function with signature `execution_context(execution_context ctx, Args ... args)`. The parameter `ctx` represents the context from which this context was resumed (e.g. that has called execution_context::operator() on `*this`) and `args` are the data passed to execution_context::operator(). The return value represents the execution_context that has to be resumed, after termiantion of this context.

Benefits of execution_context (v2) over execution_context (v1) are: faster context switch, type-safety of passed/returned arguments.

usage of execution_context

    int n=35;
    ctx::execution_context<int> source(
        [n](ctx::execution_context<int> && sink,int) mutable {
            int a=0;
            int b=1;
            while(n-->0){
                auto result=sink(a);
                sink=std::move(std::get<0>(result));
                auto next=a+b;
                a=b;
                b=next;
            }
            return std::move(sink);
        });
    for(int i=0;i<10;++i){
        auto result=source(i);
        source=std::move(std::get<0>(result));
        std::cout<<std::get<1>(result)<<" ";
    }

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

This simple example demonstrates the basic usage of execution_context as a generator. The context `sink` represents the main-context (function main() running). `sink` is generated by the framework (first element of lambda's parameter list). Because the state is invalidated (== changed) by each call of execution_context::operator(), the new state of the execution_context, returned by execution_context::operator(), needs to be assigned to `sink` after each call.

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()). Note that this example represents a generator thus the value transferred into the lambda via source() is not used. Using boost::optional<> as transferred type, might also appropriate to express this fact.

The locale variables `a`, `b` and `next` remain their values during each context switch (yield(a)). This is possible due `source` has its own stack and the stack is exchanged by each context switch.

parameter passing

With `execution_context<void>` no data will be transferred, only the context switch is executed.

    boost::context::execution_context<void> ctx1([](boost::context::execution_context<void> && ctx2){
                std::printf("inside ctx1\n");
                return ctx2();
            });
    ctx1();

    output:
        inside ctx1

`ctx1()` resumes `ctx1`, e.g. the lambda passed at the constructor of `ctx1` is entered. Argument `ctx2` represents the context that has been suspended with the invocation of `ctx1()`. When the lambda returns `ctx2`, context `ctx1` will be terminated while the context represented by `ctx2` is resumed, hence the control of execution returns from `ctx1()`.

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

    boost::context::execution_context<int> ctx1([](boost::context::execution_context<int> && ctx2,int j){
                std::printf("inside ctx1,j==%d\n",j);
                std::tie(ctx2,j)=ctx2(j+1);
                return std::move(ctx2);
            });
    int i=1;
    std::tie(ctx1,i)=ctx1(i);
    std::printf("i==%d\n",i);

    output:
        inside ctx1,j==1
        i==2

`ctx1(i)` enters the lambda in context `ctx1` with argument `j=1`. The expression `ctx2(j+1)` resumes the context represented by `ctx2` and transfers back an integer of `j+1`. On return of `ctx1(i)`, the variable `i` contains the value of `j+1`.

If more than one argument has to be transferred, the signature of the context-function is simply extended.

    boost::context::execution_context<int,int> ctx1([](boost::context::execution_context<int,int> && ctx2,int i,int j){
                std::printf("inside ctx1,i==%d,j==%d\n",i,j);
                std::tie(ctx2,i,j)=ctx2(i+j,i-j);
                return std::move(ctx2);
            });
    int i=2,j=1;
    std::tie(ctx1,i,j)=ctx1(i,j);
    std::printf("i==%d,j==%d\n",i,j);

    output:
        inside ctx1,i==2,j==1
        i==3,j==1

For use-cases, that require to transfer data of different type in each direction, boost::variant<> could be used.

    class X{
    private:
        std::exception_ptr excptr_;
        boost::context::execution_context<boost::variant<int,std::string>> ctx_;

    public:
        X():
            excptr_(),
            ctx_([=](boost::context::execution_context<boost::variant<int,std::string>> && ctx,boost::variant<int,std::string> data){
                    try {
                        for (;;) {
                            int i=boost::get<int>(data);
                            data=boost::lexical_cast<std::string>(i);
                            auto result=ctx(data);
                            ctx=std::move(std::get<0>(result));
                            data=std::get<1>(result);
                    } catch (std::bad_cast const&) {
                        excptr_=std::current_exception();
                    }
                    return std::move(ctx);
                 })
        {}

        std::string operator()(int i){
            boost::variant<int,std::string> data=i;
            auto result=ctx_(data);
            ctx_=std::move(std::get<0>(result));
            data=std::get<1>(result);
            if(excptr_){
                std::rethrow_exception(excptr_);
            }
            return boost::get<std::string>(data);
        }
    };

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

    output:
    7

In the case of unidirectional transfer of data, boost::optional<> or a pointer are appropriate.

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.

Do not jump from inside a catch block and then re-throw the exception in another execution context.

Executing function on top of a context

Sometimes it is useful to execute a new function on top of a resumed context. For this purpose execution_context::operator() with first argument `exec_ontop_arg` has to be used. The function passed as argument must return a tuple of execution_context and arguments.

    boost::context::execution_context<int> f1(boost::context::execution_context<int> && ctx,int data) {
        std::cout << "f1: entered first time: " << data << std::endl;
        std::tie(ctx,data)=ctx(data+1);
        std::cout << "f1: entered second time: " << data << std::endl;
        std::tie(ctx,data)=ctx(data+1);
        std::cout << "f1: entered third time: " << data << std::endl;
        return std::move(ctx);
    }

    int f2(int data) {
        std::cout << "f2: entered: " << data << std::endl;
        return -1;
    }

    int data=0;
    boost::context::execution_context< int > ctx(f1);
    std::tie(ctx,data)=ctx(data+1);
    std::cout << "f1: returned first time: " << data << std::endl;
    std::tie(ctx,data)=ctx(data+1);
    std::cout << "f1: returned second time: " << data << std::endl;
    std::tie(ctx,data)=ctx(ctx::exec_ontop_arg,f2,data+1);

    output:
        f1: entered first time: 1
        f1: returned first time: 2
        f1: entered second time: 3
        f1: returned second time: 4
        f2: entered: 5
        f1: entered third time: -1

The expression `ctx(ctx::exec_ontop_arg,f2,data+1)` executes `f2()` on top of context `ctx`, e.g. an additional stack frame is allocated on top of the context stack (in front of `f1()`). `f2()` returns argument `-1` that will returned by the second invocation of `ctx(data+1)` in `f1()`. [/ Another option is to execute a function on top of the context that throws an exception. The thrown exception is catched and re-thrown as nested exception of ontop_error from execution_context::operator(). ontop_error gives access to the context that has resumed the current context.

    struct my_exception : public std::runtime_error {
        my_exception( std::string const& what) :
            std::runtime_error{ what } {
        }
    };

    boost::context::execution_context<void> ctx([](boost::context::execution_context<void> && ctx) {
        for (;;) {
            try {
                    std::cout << "entered" << std::endl;
                    ctx = ctx();
                }
            } catch ( boost::context::ontop_error const& e) {
                try {
                    std::rethrow_if_nested( e);
                } catch ( my_exception const& ex) {
                    std::cerr << "my_exception: " << ex.what() << std::endl;
                }
                return e.get_context< void >();
            }
        }
        return std::move( ctx);
    });
    ctx = ctx();
    ctx = ctx();
    ctx = ctx( boost::context::exec_ontop_arg,[](){ throw my_exception{ "abc" }; });

    output:
        entered
        entered
        my_exception: abc

In this exception `my_exception` is throw from a function invoked ontop of context `ctx` and catched inside the `for`-loop.

stack unwinding

On construction of execution_context a stack is allocated. If the context-function returns the stack will be destructed. If the context-function has not yet returned and the destructor of an valid execution_context instance (e.g. execution_context::operator bool() returns `true`) is called, the stack will be destructed too.

Code executed by context-function must not prevent the propagation of the detail::forced_unwind exception. Absorbing that exception will cause stack unwinding to fail. Thus, any code that catches all exceptions must re-throw any pending detail::forced_unwind exception.

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.

The user is responsible for destructing the control structure at the top of the stack.

    // 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  {
        // captured context
        execution_context cctx;

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

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;

    // execute parser in new execution context
    boost::context::execution_context<char> source(
            [&is,&done,&except](ctx::execution_context<char> && sink,char){
            // create parser with callback function
            Parser p( is,
                      [&sink](char ch){
                            // resume main execution context
                            auto result=sink(ch);
                            sink=std::move(std::get<0>(result));
                    });
                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
                return std::move(sink);
            });

    // user-code pulls parsed data from parser
    // invert control flow
    auto result=source('\0');
    source=std::move(std::get<0>(result));
    char c=std::get<1>(result);
    if (except) {
        std::rethrow_exception(except);
    }
    while(!done) {
        printf("Parsed: %c\n",c);
        std::tie(source,c)=source('\0');
        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.

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.

Class `execution_context`

    struct exec_ontop_arg_t {};
    const exec_ontop_arg_t exec_ontop_arg{};

    class ontop_error {
    public:
        template< typename ... Args >
        execution_context< Args ... > get_context() const noexcept;
    }

    template< typename ... Args >
    class execution_context {
    public:
        template< typename Fn, typename ... Params >
        execution_context( Fn && fn, Params && ... params);

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

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

        template< typename Fn, typename ... Params >
        execution_context( std::allocator_arg_t, segemented_stack, Fn && fn, Params && ... params) = delete;

        template< typename Fn, typename ... Params >
        execution_context( std::allocator_arg_t, preallocated palloc, segmented, Fn && fn, Params && ... params)= delete;

        ~execution_context();

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

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

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

        std::tuple< execution_context, Args ... > operator()( Args ... args);

        template< typename Fn >
        std::tuple< execution_context, Args ... > operator()( exec_ontop_arg_t, Fn && fn, Args ... args);

        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);
    };

Constructor

    template< typename Fn, typename ... Params >
    execution_context( Fn && fn, Params && ... params);

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

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

##

Effects:

  Creates a new execution context and prepares the context to execute `fn`. `fixedsize_stack` is used as default stack allocator (stack size == fixedsize_stack::traits::default_size()). The constructor with argument type `preallocated`, is used to create a user defined data (for instance additional control structures) on top of the stack.

Destructor

    ~execution_context();

##

Effects:

  Destructs the associated stack if `*this` is a valid context, e.g. execution_context::operator bool() returns `true`.

Throws:

  Nothing.

Move constructor

    execution_context( execution_context && other) noexcept;

##

Effects:

  Moves underlying capture record to `*this`.

Throws:

  Nothing.

Move assignment operator

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

##

Effects:

  Moves the state of `other` to `*this` using move semantics.

Throws:

  Nothing.

Member function `operator bool`()

    explicit operator bool() const noexcept;

##

Returns:

  `true` if `*this` points to a capture record.

Throws:

  Nothing.

Member function `operator!`()

    bool operator!() const noexcept;

##

Returns:

  `true` if `*this` does not point to a capture record.

Throws:

  Nothing.

Member function `operator()`()

    std::tuple< execution_context< Args ... >, Args ... > operator()( Args ... args); // member of generic execution_context template

    execution_context< void > operator()(); // member of execution_context< void >

##

Effects:

  Stores internally the current context data (stack pointer, instruction pointer, and CPU registers) of the current active context and restores the context data from `*this`, which implies jumping to `*this`'s context. The arguments, `... args`, are passed to the current context to be returned by the most recent call to `execution_context::operator()` in the same thread.

Returns:

  The tuple of execution_context and returned arguments passed to the most recent call to `execution_context::operator()`, if any and a execution_context representing the context that has been suspended.

Note:

  The returned execution_context indicates if the suspended context has terminated (return from context-function) via `bool operator()`. If the returned execution_context has terminated no data are transferred in the returned tuple.

Member function `operator()`()

    template< typename Fn >
    std::tuple< execution_context< Args ... >, Args ... > operator()( exec_ontop_arg_t, Fn && fn, Args ... args); // member of generic execution_context

    template< typename Fn >
    execution_context< void > operator()( exec_ontop_arg_t, Fn && fn); // member of execution_context< void >

##

Effects:

  Same as execution_context::operator(). Additionally, function `fn` is executed in the context of `*this` (e.g. the stack frame of `fn` is allocated on stack of `*this`).

Returns:

  The tuple of execution_context and returned arguments passed to the most recent call to `execution_context::operator()`, if any and a execution_context representing the context that has been suspended .

Note:

  The tuple of execution_context and returned arguments from `fn` are passed as arguments to the context-function of resumed context (if the context is entered the first time) or those arguments are returned from `execution_context::operator()` within the resumed context.

Note:

  Function `fn` needs to return a tuple of arguments (see description).

Note:

  The context calling this function must not be destroyed before the arguments, that will be returned from `fn`, are preserved at least in the stack frame of the resumed context.

Note:

  The returned execution_context indicates if the suspended context has terminated (return from context-function) via `bool operator()`. If the returned execution_context has terminated no data are transferred in the returned tuple.

Member function `operator==`()

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

##

Returns:

  `true` if `*this` and `other` represent the same execution context, `false` otherwise.

Throws:

  Nothing.

Member function `operator!=`()

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

##

Returns:

  `! (other == * this)`

Throws:

  Nothing.

Member function `operator<`()

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

##

Returns:

  `true` if `*this != other` is true and the implementation-defined total order of `execution_context` values places `*this` before `other`, false otherwise.

Throws:

  Nothing.

Member function `operator>`()

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

##

Returns:

  `other < * this`

Throws:

  Nothing.

Member function `operator<=`()

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

##

Returns:

  `! (other < * this)`

Throws:

  Nothing.

Member function `operator>=`()

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

##

Returns:

  `! (* this < other)`

Throws:

  Nothing.

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

##

Efects:

  Writes the representation of `other` to stream `os`.

Returns:

  `os`

# Class execution_context (version 1)

execution_context is deprecated.

Include `execution_context.hpp` and pass `BOOST_EXECUTION_CONTEXT=1` and property `context-switch=ec` to b2 command-line in order to use execution_context (v1).

Segmented stacks (segmented-stacks=on), e.g. on demand growing stacks, can be used with execution_context (v1).

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::execution_context sink(boost::context::execution_context::current());
    boost::context::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::execution_context::current());
    // execute parser in new execution context
    boost::context::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.

The user is responsible for destructing the control structure at the top of the stack.

    // 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.

Do not jump from inside a catch block and then re-throw the exception in another execution context.

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::execution_context caller_;
        boost::context::execution_context callee_;

    public:
        X() :
            excptr_(),
            caller_( boost::context::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;

##

Returns:

  Returns an instance of excution_context pointing to the active execution context.

Throws:

  Nothing.

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

##

Effects:

  Creates a new execution context and prepares the context to execute `fn`. `fixedsize_stack` is used as default stack allocator (stack size == fixedsize_stack::traits::default_size()). The constructor with argument type `preallocated`, is used to create a user defined data (for instance additional control structures) on top of the stack.

Copy constructor

    execution_context( execution_context const& other) noexcept;

##

Effects:

  Copies `other`, e.g. underlying control structure is shared with `*this`.

Throws:

  Nothing.

Move constructor

    execution_context( execution_context && other) noexcept;

##

Effects:

  Moves underlying control structure to `*this`.

Throws:

  Nothing.

Copy assignment operator

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

##

Effects:

  Copies the state of `other` to `*this`, control structure is shared.

Throws:

  Nothing.

Move assignment operator

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

##

Effects:

  Moves the control structure of `other` to `*this` using move semantics.

Throws:

  Nothing.

Member function `operator bool`()

    explicit operator bool() const noexcept;

##

Returns:

  `true` if `*this` points to a control structure.

Throws:

  Nothing.

Member function `operator!`()

    bool operator!() const noexcept;

##

Returns:

  `true` if `*this` does not point to a control structure.

Throws:

  Nothing.

Member function `operator()`()

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

##

Effects:

  Stores internally the current context data (stack pointer, instruction pointer, and CPU registers) of the current active context and restores the context data from `*this`, which implies jumping to `*this`'s context. The void pointer argument, `vp`, is passed to the current context to be returned by the most recent call to `execution_context::operator()` in the same thread. `fn` is executed with arguments `args` on top of the stack of `this`.

Note:

  The behaviour is undefined if `operator()()` is called while execution_context::current() returns `*this` (e.g. resuming an already running context). If the top-level context function returns, `std::exit()` is called.

Returns:

  The void pointer argument passed to the most recent call to execution_context::operator(), if any.

Member function `operator(exec_ontop_arg_t)`()

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

##

Effects:

  Same as execution_context::operator(). Additionally, function `fn` is executed with arguments `vp` in the context of `*this` (e.g. the stack frame of `fn` is allocated on stack of `*this`).

Returns:

  The void pointer argument passed to the most recent call to execution_context::operator(), if any.

Member function `operator==`()

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

##

Returns:

  `true` if `*this` and `other` represent the same execution context, `false` otherwise.

Throws:

  Nothing.

Member function `operator!=`()

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

##

Returns:

  `! (other == * this)`

Throws:

  Nothing.

Member function `operator<`()

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

##

Returns:

  `true` if `*this != other` is true and the implementation-defined total order of `execution_context` values places `*this` before `other`, false otherwise.

Throws:

  Nothing.

Member function `operator>`()

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

##

Returns:

  `other < * this`

Throws:

  Nothing.

Member function `operator<=`()

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

##

Returns:

  `! (other < * this)`

Throws:

  Nothing.

Member function `operator>=`()

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

##

Returns:

  `! (* this < other)`

Throws:

  Nothing.

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

##

Efects:

  Writes the representation of `other` to stream `os`.

Returns:

  `os`

# Stack allocation

The memory used by the stack is allocated/deallocated via a StackAllocator which is required to model a stack-allocator concept.

stack-allocator concept

A StackAllocator must satisfy the stack-allocator concept requirements shown in the following table, in which `a` is an object of a StackAllocator type, `sctx` is a `stack_context`, and `size` is a `std::size_t`:

expression | return type | notes
--- | --- | ---
`a(size)` |  | creates a stack allocator
`a.allocate()` | `stack_context` | creates a stack
`a.deallocate( sctx)` | `void` | deallocates the stack created by `a.allocate()`

The implementation of `allocate()` might include logic to protect against exceeding the context's available stack size rather than leaving it as undefined behaviour.

Calling `deallocate()` with a `stack_context` not set by `allocate()` results in undefined behaviour.

The stack is not required to be aligned; alignment takes place inside execution_context.

Depending on the architecture `allocate()` stores an address from the top of the stack (growing downwards) or the bottom of the stack (growing upwards).

## Class protected_fixedsize

Boost.Context provides the class protected_fixedsize_stack which models the stack-allocator concept. It appends a guard page at the end of each stack to protect against exceeding the stack. If the guard page is accessed (read or write operation) a segmentation fault/access violation is generated by the operating system.

Using protected_fixedsize_stack is expensive. That is, launching a new coroutine with a new stack is expensive; the allocated stack is just as efficient to use as any other stack.

The appended `guard page` is not mapped to physical memory, only virtual addresses are used.

    #include <boost/context/protected_fixedsize.hpp>

    template< typename traitsT >
    struct basic_protected_fixedsize {
        typedef traitT  traits_type;

        basic_protected_fixesize(std::size_t size = traits_type::default_size());

        stack_context allocate();

        void deallocate( stack_context &);
    }

    typedef basic_protected_fixedsize< stack_traits > protected_fixedsize

`stack_context allocate()`

###

Preconditions:

  `traits_type::minimum:size() <= size` and `! traits_type::is_unbounded() && ( traits_type::maximum:size() >= size)`.

Effects:

  Allocates memory of at least `size` Bytes and stores a pointer to the stack and its actual size in `sctx`. Depending on the architecture (the stack grows downwards/upwards) the stored address is the highest/lowest address of the stack.

`void deallocate( stack_context & sctx)`

###

Preconditions:

  `sctx.sp` is valid, `traits_type::minimum:size() <= sctx.size` and `! traits_type::is_unbounded() && ( traits_type::maximum:size() >= sctx.size)`.

Effects:

  Deallocates the stack space.

## Class pooled_fixedsize_stack

Boost.Context provides the class pooled_fixedsize_stack which models the stack-allocator concept. In contrast to protected_fixedsize_stack it does not append a guard page at the end of each stack. The memory is managed internally by `boost::pool<>`.

    #include <boost/context/pooled_fixedsize_stack.hpp>

    template< typename traitsT >
    struct basic_pooled_fixedsize_stack {
        typedef traitT  traits_type;

        basic_pooled_fixedsize_stack(std::size_t stack_size = traits_type::default_size(), std::size_t next_size = 32, std::size_t max_size = 0);

        stack_context allocate();

        void deallocate( stack_context &);
    }

    typedef basic_pooled_fixedsize_stack< stack_traits > pooled_fixedsize_stack;

`basic_pooled_fixedsize_stack(std::size_t stack_size, std::size_t next_size, std::size_t max_size)`

###

Preconditions:

  `! traits_type::is_unbounded() && ( traits_type::maximum:size() >= stack_size)` and `0 < nest_size`.

Effects:

  Allocates memory of at least `stack_size` Bytes and stores a pointer to the stack and its actual size in `sctx`. Depending on the architecture (the stack grows downwards/upwards) the stored address is the highest/lowest address of the stack. Argument `next_size` determines the number of stacks to request from the system the first time that `*this` needs to allocate system memory. The third argument `max_size` controls how many memory might be allocated for stacks - a value of zero means no uper limit.

`stack_context allocate()`

###

Preconditions:

  `! traits_type::is_unbounded() && ( traits_type::maximum:size() >= stack_size)`.

Effects:

  Allocates memory of at least `stack_size` Bytes and stores a pointer to the stack and its actual size in `sctx`. Depending on the architecture (the stack grows downwards/upwards) the stored address is the highest/lowest address of the stack.

`void deallocate( stack_context & sctx)`

###

Preconditions:

  `sctx.sp` is valid, `! traits_type::is_unbounded() && ( traits_type::maximum:size() >= sctx.size)`.

Effects:

  Deallocates the stack space.

## Class fixedsize_stack

Boost.Context provides the class fixedsize_stack which models the stack-allocator concept. In contrast to protected_fixedsize_stack it does not append a guard page at the end of each stack. The memory is simply managed by `std::malloc()` and `std::free()`.

    #include <boost/context/fixedsize_stack.hpp>

    template< typename traitsT >
    struct basic_fixedsize_stack {
        typedef traitT  traits_type;

        basic_fixesize_stack(std::size_t size = traits_type::default_size());

        stack_context allocate();

        void deallocate( stack_context &);
    }

    typedef basic_fixedsize_stack< stack_traits > fixedsize_stack;

`stack_context allocate()`

###

Preconditions:

  `traits_type::minimum:size() <= size` and `! traits_type::is_unbounded() && ( traits_type::maximum:size() >= size)`.

Effects:

  Allocates memory of at least `size` Bytes and stores a pointer to the stack and its actual size in `sctx`. Depending on the architecture (the stack grows downwards/upwards) the stored address is the highest/lowest address of the stack.

`void deallocate( stack_context & sctx)`

###

Preconditions:

  `sctx.sp` is valid, `traits_type::minimum:size() <= sctx.size` and `! traits_type::is_unbounded() && ( traits_type::maximum:size() >= sctx.size)`.

Effects:

  Deallocates the stack space.

## Class segmented_stack

Boost.Context supports usage of a segmented_stack, e. g. the size of the stack grows on demand. The coroutine is created with a minimal stack size and will be increased as required. Class segmented_stack models the stack-allocator concept. In contrast to protected_fixedsize_stack and fixedsize_stack it creates a stack which grows on demand.

Segmented stacks are currently only supported by gcc from version 4.7 clang from version 3.4 onwards. In order to use a segmented_stack Boost.Context must be built with property `segmented-stacks`, e.g. toolset=gcc segmented-stacks=on and applying `BOOST_USE_SEGMENTED_STACKS` at b2/bjam command line.

Segmented stacks can only be used with callcc() (using ucontext_t) and execution_context (v1)

.

    #include <boost/context/segmented_stack.hpp>

    template< typename traitsT >
    struct basic_segmented_stack {
        typedef traitT  traits_type;

        basic_segmented_stack(std::size_t size = traits_type::default_size());

        stack_context allocate();

        void deallocate( stack_context &);
    }

    typedef basic_segmented_stack< stack_traits > segmented_stack;

`stack_context allocate()`

###

Preconditions:

  `traits_type::minimum:size() <= size` and `! traits_type::is_unbounded() && ( traits_type::maximum:size() >= size)`.

Effects:

  Allocates memory of at least `size` Bytes and stores a pointer to the stack and its actual size in `sctx`. Depending on the architecture (the stack grows downwards/upwards) the stored address is the highest/lowest address of the stack.

`void deallocate( stack_context & sctx)`

###

Preconditions:

  `sctx.sp` is valid, `traits_type::minimum:size() <= sctx.size` and `! traits_type::is_unbounded() && ( traits_type::maximum:size() >= sctx.size)`.

Effects:

  Deallocates the stack space.

If the library is compiled for segmented stacks, segmented_stack is the only available stack allocator.

## Class stack_traits

stack_traits models a stack-traits providing a way to access certain properites defined by the enironment. Stack allocators use stack-traits to allocate stacks.

    #include <boost/context/stack_traits.hpp>

    struct stack_traits {
        static bool is_unbounded() noexcept;

        static std::size_t page_size() noexcept;

        static std::size_t default_size() noexcept;

        static std::size_t minimum_size() noexcept;

        static std::size_t maximum_size() noexcept;
    }

`static bool is_unbounded()`

###

Returns:

  Returns `true` if the environment defines no limit for the size of a stack.

Throws:

  Nothing.

`static std::size_t page_size()`

###

Returns:

  Returns the page size in bytes.

Throws:

  Nothing.

`static std::size_t default_size()`

###

Returns:

  Returns a default stack size, which may be platform specific. If the stack is unbounded then the present implementation returns the maximum of `64 kB` and `minimum_size()`.

Throws:

  Nothing.

`static std::size_t minimum_size()`

###

Returns:

  Returns the minimum size in bytes of stack defined by the environment (Win32 4kB/Win64 8kB, defined by rlimit on POSIX).

Throws:

  Nothing.

`static std::size_t maximum_size()`

###

Preconditions:

  `is_unbounded()` returns `false`.

Returns:

  Returns the maximum size in bytes of stack defined by the environment.

Throws:

  Nothing.

## Class stack_context

Boost.Context provides the class stack_context which will contain the stack pointer and the size of the stack. In case of a segmented_stack, stack_context contains some extra control structures.

    struct stack_context {
        void    *   sp;
        std::size_t size;

        // might contain additional control structures
        // for segmented stacks
    }

`void * sp`

###

Value:

  Pointer to the beginning of the stack.

`std::size_t size`

###

Value:

  Actual size of the stack.

## Support for valgrind

Running programs that switch stacks under valgrind causes problems. Property (b2 command-line) `valgrind=on` let valgrind treat the memory regions as stack space which suppresses the errors. Users must define `BOOST_USE_VALGRIND` before including any Boost.Context headers when linking against Boost binaries compiled with `valgrind=on`.

# Struct `preallocated`

    struct preallocated {
        void        *   sp;
        std::size_t     size;
        stack_context   sctx;

        preallocated( void * sp, std:size_t size, stack_allocator sctx) noexcept;
    };

Constructor

    preallocated( void * sp, std:size_t size, stack_allocator sctx) noexcept;

##

Effects:

  Creates an object of preallocated.

# Performance

Performance measurements were taken using `std::chrono::highresolution_clock`, with overhead corrections. The code was compiled with gcc-6.3.1, using build options: variant = release, optimization = speed. Tests were executed on dual Intel XEON E5 2620v4 2.2GHz, 16C/32T, 64GB RAM, running Linux (x86_64).

## Performance of context switch

callcc()/continuation (fcontext_t) | callcc()/continuation (ucontext_t) | callcc()/continuation (Windows-Fiber)
--- | --- | ---
9 ns / 19 CPU cycles | 547 ns / 1130 CPU cycles | 49 ns / 98 CPU cycles

# Architectures

Boost.Context, using fcontext_t, supports following architectures:

## Supported architectures (<ABI|binary format>)

Architecture | LINUX (UNIX) | Windows | MacOS X | iOS
--- | --- | --- | --- | ---
arm (aarch32) | AAPCS|ELF | AAPCS|PE | - | AAPCS|MACH-O
arm (aarch64) | AAPCS|ELF | - | - | AAPCS|MACH-O
i386 | SYSV|ELF | MS|PE | SYSV|MACH-O | -
mips1 | O32|ELF | - | - | -
ppc32 | SYSV|ELF,XCOFF | - | SYSV|MACH-O | -
ppc64 | SYSV|ELF,XCOFF | - | SYSV|MACH-O | -
sparc | - | - | - | -
x86_64 | SYSV,X32|ELF | MS|PE | SYSV|MACH-O | -

If the architecture is not supported but the platform provides ucontext_t, Boost.Context should be compiled with `BOOST_USE_UCONTEXT` and b2 property `context-impl=ucontext`.

## Cross compiling

Cross compiling the library requires to specify the build properties <architecture>, <address-model>, <binary-format> and <abi> at b2 command line.

# Rationale

No inline-assembler

Some newer compiler (for instance MSVC 10 for x86_64 and itanium) do not support inline assembler. MSDN article 'Inline Assembler' . Inlined assembler generates code bloating which is not welcome on embedded systems.

fcontext_t

Boost.Context provides the low level API fcontext_t which is implemented in assembler to provide context swapping operations. fcontext_t is the part to port to new platforms.

Context switches do not preserve the signal mask on UNIX systems.

fcontext_t is an opaque pointer.

## Other APIs

setjmp()/longjmp()

C99 defines `setjmp()`/`longjmp()` to provide non-local jumps but it does not require that longjmp() preserves the current stack frame. Therefore, jumping into a function which was exited via a call to longjmp() is undefined ISO/IEC 9899:1999, 2005, 7.13.2.1:2 .

ucontext_t

Since POSIX.1-2004 `ucontext_t` is deprecated and was removed in POSIX.1-2008! The function signature of `makecontext()` is:

    void makecontext(ucontext_t *ucp, void (*func)(), int argc, ...);

The third argument of `makecontext()` specifies the number of integer arguments that follow which will require function pointer cast if `func` will accept those arguments which is undefined in C99 ISO/IEC 9899:1999, 2005, J.2 .

The arguments in the var-arg list are required to be integers, passing pointers in var-arg list is not guaranteed to work, especially it will fail for architectures where pointers are larger than integers.

`ucontext_t` preserves signal mask between context switches which involves system calls consuming a lot of CPU cycles (ucontext_t is slower; a context switch takes two magnitutes of order more CPU cycles more than fcontext_t).

Windows fibers

A drawback of Windows Fiber API is that `CreateFiber()` does not accept a pointer to user allocated stack space preventing the reuse of stacks for other context instances. Because the Windows Fiber API requires to call `ConvertThreadToFiber()` if `SwitchFiber()` is called for a thread which has not been converted to a fiber. For the same reason `ConvertFiberToThread()` must be called after return from `SwitchFiber()` if the thread was forced to be converted to a fiber before (which is inefficient).

    if ( ! is_a_fiber() )
    {
        ConvertThreadToFiber( 0);
        SwitchToFiber( ctx);
        ConvertFiberToThread();
    }

If the condition `_WIN32_WINNT >= _WIN32_WINNT_VISTA` is met function `IsThreadAFiber()` is provided in order to detect if the current thread was already converted. Unfortunately Windows XP + SP 2/3 defines `_WIN32_WINNT >= _WIN32_WINNT_VISTA` without providing `IsThreadAFiber()`.

## x86 and floating-point env

i386

"The FpCsr and the MxCsr register must be saved and restored before any call or return by any procedure that needs to modify them ..." 'Calling Conventions', Agner Fog .

x86_64
Windows

MxCsr - "A callee that modifies any of the non-volatile fields within MxCsr must restore them before returning to its caller. Furthermore, a caller that has modified any of these fields must restore them to their standard values before invoking a callee ..." MSDN article 'MxCsr' .

FpCsr - "A callee that modifies any of the fields within FpCsr must restore them before returning to its caller. Furthermore, a caller that has modified any of these fields must restore them to their standard values before invoking a callee ..." MSDN article 'FpCsr' .

"The MMX and floating-point stack registers (MM0-MM7/ST0-ST7) are preserved across context switches. There is no explicit calling convention for these registers." MSDN article 'Legacy Floating-Point Support' .

"The 64-bit Microsoft compiler does not use ST(0)-ST(7)/MM0-MM7". 'Calling Conventions', Agner Fog .

"XMM6-XMM15 must be preserved" MSDN article 'Register Usage'

SysV

"The control bits of the MxCsr register are callee-saved (preserved across calls), while the status bits are caller-saved (not preserved). The x87 status word register is caller-saved, whereas the x87 control word (FpCsr) is callee-saved." SysV ABI AMD64 Architecture Processor Supplement Draft Version 0.99.4, 3.2.1 .

# Reference

ARM

- AAPCS ABI: Procedure Call Standard for the ARM Architecture

- AAPCS/LINUX: ARM GNU/Linux Application Binary Interface Supplement

MIPS

- O32 ABI: SYSTEM V APPLICATION BINARY INTERFACE, MIPS RISC Processor Supplement

PowerPC32

- SYSV ABI: SYSTEM V APPLICATION BINARY INTERFACE PowerPC Processor Supplement

PowerPC64

- SYSV ABI: PowerPC User Instruction Set Architecture, Book I

X86-32

- SYSV ABI: SYSTEM V APPLICATION BINARY INTERFACE, Intel386TM Architecture Processor Supplement

- MS PE: Calling Conventions

X86-64

- SYSV ABI: System V Application Binary Interface, AMD64 Architecture Processor Supplement

- MS PE: x64 Software Conventions

# Acknowledgments

I'd like to thank Adreas Fett, Artyom Beilis, Daniel Larimer, David Deakins, Evgeny Shapovalov, Fernando Pelliccioni, Giovanni Piero Deretta, Gordon Woodhull, Helge Bahmann, Holger Grund, Jeffrey Lee Hellrung (Jr.), Keith Jeffery, Martin Husemann, Phil Endecott, Robert Stewart, Sergey Cheban, Steven Watanabe, Vicente J. Botet Escriba, Wayne Piekarski.