+++ /dev/null
-[/
- Copyright Oliver Kowalke 2014.
- 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
-]
-
-[#ecv2]
-[section:ecv2 Class execution_context (version 2)]
-
-[note This class is enabled per default.]
-
-Class __econtext__ encapsulates context switching and manages the associated
-context' stack (allocation/deallocation).
-
-__econtext__ allocates the context stack (using its [link stack
-__stack_allocator__] 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 __econtext__). In contrast to __ecv1__ the
-ownership of the control structure is not shared (no member variable to control
-structure in __econtext__). __econtext__ keeps internally a state that is moved
-by a call of __ec_op__ (`*this` will be invalidated), e.g. after a calling
-__ec_op__, `*this` can not be used for an additional context switch.
-
-__econtext__ is only move-constructible and move-assignable.
-
-The moved state is assigned to a new instance of __econtext__. 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 __ec_op__ that has
-been called in the resumed context.
-In contrast to __ecv1__, the context switch is faster because no global pointer
-etc. is involved.
-
-[important Segmented stacks are not supported by __econtext__ (v2).]
-
-On return the context-function of the current context has to specify an
-__econtext__ 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 __stack_allocator__. The stack walking makes the destruction
-of __econtext__ slow and should be prevented if possible.
-
-__econtext__ expects a __context_fn__ 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
-__ec_op__ on `*this`) and `args` are the data passed to __ec_op__. The return
-value represents the execution_context that has to be resumed, after termiantion
-of this context.
-
-Benefits of __ecv2__ over __ecv1__ are: faster context switch, type-safety of
-passed/returned arguments.
-
-
-[heading usage of __econtext__]
-
- 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 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 __econtext__ 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 __ec_op__, the new
-state of the __econtext__, returned by __ec_op__, 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.
-
-
-[heading 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 __ec_op__, in one context, is passed as the last
-arguments of the __context_fn__ if the context is started for the first time.
-In all following invocations of __ec_op__ the arguments passed to __ec_op__, in
-one context, is returned by __ec_op__ 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);
- return ctx2(j+1);
- });
- 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);
- return ctx2(i+j,i-j);
- });
- 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 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.
-
-
-[heading exception handling]
-If the function executed inside a __econtext__ emits ans exception, the
-application is terminated by calling ['std::terminate()]. ['std::exception_ptr]
-can be used to transfer exceptions between different execution contexts.
-
-[important Do not jump from inside a catch block and then re-throw the exception
-in another execution context.]
-
-[#ecv2_ontop]
-[heading 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 __ec_op__ 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 ctx;
- }
-
- std::tuple<boost::context::execution_context<int>,int> f2(boost::context::execution_context<int> ctx,int data) {
- std::cout << "f2: entered: " << data << std::endl;
- return std::make_tuple(std::move(ctx),-1);
- }
-
- int data = 0;
- ctx::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.
-
- struct interrupt {
- boost::context::execution_context< void > ctx;
-
- interrupt( boost::context::execution_context< void > && ctx_) :
- ctx( std::forward< boost::context::execution_context< void > >( ctx_) ) {
- }
- };
-
- boost::context::execution_context<void> f1(boost::context::execution_context<void> ctx) {
- try {
- for (;;) {
- std::cout << "f1()" << std::endl;
- ctx = ctx();
- }
- } catch (interrupt & e) {
- std::cout << "f1(): interrupted" << std::endl;
- ctx = std::move( e.ctx);
- }
- return ctx;
- }
-
- boost::context::execution_context<void> f2(boost::context::execution_context<void> ctx) {
- throw interrupt(std::move(ctx));
- return ctx;
- }
-
- boost::context::execution_context< void > ctx(f1);
- ctx = ctx();
- ctx = ctx();
- ctx = ctx(boost::context::exec_ontop_arg,f2);
-
- output:
- f1()
- f1()
- f1(): interrupted
-
-In this example `f2()` is used to interrupt the `for`-loop in `f1()`.
-
-
-[heading stack unwinding]
-On construction of __econtext__ a stack is allocated.
-If the __context_fn__ returns the stack will be destructed.
-If the __context_fn__ has not yet returned and the destructor of an valid
-__econtext__ instance (e.g. ['execution_context::operator bool()] returns
-`true`) is called, the stack will be destructed too.
-
-[important Code executed by __context_fn__ must not prevent the propagation of the
-__forced_unwind__ exception. Absorbing that exception will cause stack
-unwinding to fail. Thus, any code that catches all exceptions must re-throw any
-pending __forced_unwind__ exception.]
-
-
-[#ecv2_prealloc]
-[heading 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
-__econtext__ is created.
-[note 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) {
- }
- ...
- };
-
-
-[heading 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 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 __econtext__ 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 __econtext__.
-
-If the code executed by __econtext__ 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.
-
-
-[heading Class `execution_context`]
-
- struct exec_ontop_arg_t {};
- const exec_ontop_arg_t exec_ontop_arg{};
-
- 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_heading ecv2..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);
-
-[variablelist
-[[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 [link ecv2_prealloc (for instance additional control structures)] on
-top of the stack.]]
-]
-[destructor_heading ecv2..destructor destructor]
-
- ~execution_context();
-
-[variablelist
-[[Effects:] [Destructs the associated stack if `*this` is a valid context,
-e.g. ['execution_context::operator bool()] returns `true`.]]
-[[Throws:] [Nothing.]]
-]
-
-[move_constructor_heading ecv2..move constructor]
-
- execution_context( execution_context && other) noexcept;
-
-[variablelist
-[[Effects:] [Moves underlying capture record to `*this`.]]
-[[Throws:] [Nothing.]]
-]
-
-[move_assignment_heading ecv2..move assignment]
-
- execution_context & operator=( execution_context && other) noexcept;
-
-[variablelist
-[[Effects:] [Moves the state of `other` to `*this` using move semantics.]]
-[[Throws:] [Nothing.]]
-]
-
-[operator_heading ecv2..operator_bool..operator bool]
-
- explicit operator bool() const noexcept;
-
-[variablelist
-[[Returns:] [`true` if `*this` points to a capture record.]]
-[[Throws:] [Nothing.]]
-]
-
-[operator_heading ecv2..operator_not..operator!]
-
- bool operator!() const noexcept;
-
-[variablelist
-[[Returns:] [`true` if `*this` does not point to a capture record.]]
-[[Throws:] [Nothing.]]
-]
-
-[operator_heading ecv2..operator_call..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 >
-
-[variablelist
-[[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.]]
-]
-
-[operator_heading ecv2..operator_call_ontop..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 >
-
-[variablelist
-[[Effects:] [Same as __ec_op__. 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 execution_context and
-arguments ([link ecv2_ontop 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.]]
-]
-
-[operator_heading ecv2..operator_equal..operator==]
-
- bool operator==( execution_context const& other) const noexcept;
-
-[variablelist
-[[Returns:] [`true` if `*this` and `other` represent the same execution context,
-`false` otherwise.]]
-[[Throws:] [Nothing.]]
-]
-
-[operator_heading ecv2..operator_notequal..operator!=]
-
- bool operator!=( execution_context const& other) const noexcept;
-
-[variablelist
-[[Returns:] [[`! (other == * this)]]]
-[[Throws:] [Nothing.]]
-]
-
-[operator_heading ecv2..operator_less..operator<]
-
- bool operator<( execution_context const& other) const noexcept;
-
-[variablelist
-[[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.]]
-]
-
-[operator_heading ecv2..operator_greater..operator>]
-
- bool operator>( execution_context const& other) const noexcept;
-
-[variablelist
-[[Returns:] [`other < * this`]]
-[[Throws:] [Nothing.]]
-]
-
-[operator_heading ecv2..operator_lesseq..operator<=]
-
- bool operator<=( execution_context const& other) const noexcept;
-
-[variablelist
-[[Returns:] [`! (other < * this)`]]
-[[Throws:] [Nothing.]]
-]
-
-[operator_heading ecv2..operator_greatereq..operator>=]
-
- bool operator>=( execution_context const& other) const noexcept;
-
-[variablelist
-[[Returns:] [`! (* this < other)`]]
-[[Throws:] [Nothing.]]
-]
-
-[hding ecv2_..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);
-
-[variablelist
-[[Efects:] [Writes the representation of `other` to stream `os`.]]
-[[Returns:] [`os`]]
-]
-
-
-[endsect]
projects / ceph.git / blobdiff