Each instance of fcontext_t represents a context (CPU registers and stack space). Together with its related functions jump_fcontext() and make_fcontext() it provides a execution control transfer mechanism similar interface like ucontext_t. fcontext_t and its functions are located in boost::ctx and the functions are declared as extern "C".

	Warning
	If fcontext_t is used in a multithreaded application, it can migrated between threads, but must not reference thread-local storage.

	Note
	If fiber-local storage is used on Windows, the user is responsible for calling ::FlsAlloc(), ::FlsFree().

	Important
	The low level API is the part to port to new platforms.

Executing a context

A new context supposed to execute a context-function (returning void and accepting intptr_t as argument) must be initialized by function make_fcontext().

// context-function
void f( intptr);

// creates and manages a protected stack (with guard page)
ctx::stack_allocator alloc;
fc.fc_stack.base = alloc.allocate(ctx::minimum_stacksize());
fc.fc_stack.limit =
    static_cast< char * >( fc.fc_stack.base) - ctx::minimum_stacksize();

// context fc uses f() as context function
make_fcontext( & fc, f);

fcontext_t requires a pointer to the top of the stack (fc_base) as well as a pointer to the lower bound of the stack (fc_limit).

Calling jump_fcontext() invokes the context-function in a newly created context complete with registers, flags, stack and instruction pointers. When control should be returned to the original calling context, call jump_fcontext(). The current context information (registers, flags, and stack and instruction pointers) is saved and the original context information is restored. Calling jump_fcontext() again resumes execution in the second context after saving the new state of the original context.

namespace ctx = boost::ctx;

ctx::fcontext_t fcm, fc1, fc2;

void f1( intptr_t)
{
        std::cout << "f1: entered" << std::endl;
        std::cout << "f1: call jump_fcontext( & fc1, & fc2, 0)" << std::endl;
        ctx::jump_fcontext( & fc1, & fc2, 0);
        std::cout << "f1: return" << std::endl;
        ctx::jump_fcontext( & fc1, & fcm, 0);
}

void f2( intptr_t)
{
        std::cout << "f2: entered" << std::endl;
        std::cout << "f2: call jump_fcontext( & fc2, & fc1, 0)" << std::endl;
        ctx::jump_fcontext( & fc2, & fc1, 0);
        BOOST_ASSERT( false && ! "f2: never returns");
}

int main( int argc, char * argv[])
{
        ctx::stack_allocator alloc1, alloc2;

        fc1.fc_stack.base = alloc1.allocate(ctx::minimum_stacksize());
        fc1.fc_stack.limit =
            static_cast< char * >( fc1.fc_stack.base) - ctx::minimum_stacksize();
        ctx::make_fcontext( & fc1, f1);

        fc2.fc_stack.base = alloc2.allocate(ctx::minimum_stacksize());
        fc2.fc_stack.limit =
            static_cast< char * >( fc2.fc_stack.base) - ctx::minimum_stacksize();
        ctx::make_fcontext( & fc2, f2);

        std::cout << "main: call jump_fcontext( & fcm, & fc1, 0)" << std::endl;
        ctx::jump_fcontext( & fcm, & fc1, 0);

        std::cout << "main: done" << std::endl;

        return EXIT_SUCCESS;
}

output:
    main: call jump_fcontext( & fcm, & fc1, 0)
    f1: entered
    f1: call jump_fcontext( & fc1, & fc2, 0)
    f2: entered
    f2: call jump_fcontext( & fc2, & fc1, 0)
    f1: return
    main: done

First call of jump_fcontext() enters the context-function f1() by starting context fc1 (context fcm saves the registers of main()). For jumping between context's fc1 and fc2 jump_fcontext() is called. Because context fcm is chained to fc1, main() is entered (returning from jump_fcontext()) after context fc1 becomes complete (return from f1()).

	Warning
	Calling jump_fcontext() to the same context from inside the same context results in undefined behaviour.

	Note
	In contrast to threads, which are preemtive, fcontext_t switches are cooperative (programmer controls when switch will happen). The kernel is not involved in the context switches.

Transfer of data

The third argument passed to jump_fcontext(), in one context, is passed as the first argument of the context-function if the context is started for the first time. In all following invocations of jump_fcontext() the intptr_t passed to jump_fcontext(), in one context, is returned by jump_fcontext() in the other context.

namespace ctx = boost::ctx;

ctx::fcontext_t fc1, fcm;

typedef std::pair< int, int >   pair_t;

void f1( intptr_t param)
{
    pair_t * p = ( pair_t *) param;

    p = ( pair_t *) ctx::jump_fcontext( & fc1, & fcm, ( intptr_t) ( p->first + p->second) );

    ctx::jump_fcontext( & fc1, & fcm, ( intptr_t) ( p->first + p->second) );
}

int main( int argc, char * argv[])
{
    ctx::stack_allocator alloc;

    fc1.fc_stack.base = alloc.allocate(ctx::minimum_stacksize());
    fc1.fc_stack.limit =
        static_cast< char * >( fc1.fc_stack.base) - ctx::minimum_stacksize();
    fc1.fc_link = & fcm;
    pair_t p( std::make_pair( 2, 7) );
    ctx::make_fcontext( & fc1, f1);

    int res = ( int) ctx::jump_fcontext( & fcm, & fc1, ( intptr_t) & p);
    std::cout << p.first << " + " << p.second << " == " << res << std::endl;

    p = std::make_pair( 5, 6);
    res = ( int) ctx::jump_fcontext( & fcm, & fc1, ( intptr_t) & p);
    std::cout << p.first << " + " << p.second << " == " << res << std::endl;

    std::cout << "main: done" << std::endl;

    return EXIT_SUCCESS;
}

output:
    2 + 7 == 9
    5 + 6 == 11
    main: done

Exceptions in context-function

If the context-function emits an exception, the application will terminate.

Preserving floating point registers

Preserving the floating point registers increases the cycle count for a context switch (see performance tests). The foruth argument of jump_fcontext() controls if fpu registers should be preserved by the context jump.

	Important
	The use of the fpu controling argument of jump_fcontext() must be consistent in the application. Otherwise the behaviour is undefined.

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.