Re: [boost] [context] ready

Subject: Re: [boost] [context] ready
From: Keith Jeffery (Keith.Jeffery_at_[hidden])
Date: 2011-11-11 17:59:21

-----Original Message-----
From: boost-bounces_at_[hidden] [mailto:boost-bounces_at_[hidden]] On Behalf Of Oliver Kowalke
Sent: Sunday, November 06, 2011 4:20 AM
To: boost_at_[hidden]
Subject: [boost] [context] ready

Hi,

https://github.com/olk/boost.context.git contains the new version of boost.context (docu at
http://ok73.ok.funpic.de/boost/libs/context/doc/html/index.html)
Any comments are welcome - in the meantime I'm awaiting Giovanni's OK for the mini-review.

regards,
Oliver

_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost

Here are some documentation changes:

== Overview ==

thousends -> thousands

== Synopsis ==

In order to implement rvalue references Boost.Move is used.
Boost.Move is used to emulate rvalue references.

If contexts are migrated between threads the code called by a context must not use thread-local-storage.
If contexts are migrated between threads, the code called by a context must not use thread-local-storage.

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

== Executing Context ==

A new context is created from a callable object (known as the context-function), the stack size and two arguments determine stack unwinding and context termination.
A new context is created from a callable object (known as the context-function). The stack size, stack unwinding behavior, and context termination behavior are determined with additional arguments.

If desired a function or callable object that requires arguments can be supplied by passing additional arguments to the context constructor.
A function or callable object that requires arguments can have them supplied as additional arguments to the context constructor.

Calling context::resume() from inside the same context undefined behaviour will happen.
Calling context::resume() from inside the same context will result in undefined behaviour.

The kernel does never 'see' the context switches.
The kernel never 'sees' the context switches.

Boost.Context allows to transfer data between contexts. context::resume() and context::suspend() accept a void pointer as argument and return a void pointer. The void pointer passed as argument to on of both functions is returned by its counterpart function. That means: the void pointer passed to context::resume() is returned by context::suspend() which was called in the other context (to which context::resume() transfers the execution cotnrol back). context::suspend() does the same, the void pointer arg is returned by context::resume() and context::start(), depending on which function was called before. context::start() has no void pointer argument because of it enters the context thus there is not return to context::suspend().

Boost.Context allows the transfer of data between contexts. Calls to context::resume() and context::suspend() both accept and return a void pointer. The void pointer passed as an argument to either function is returned by its counterpart function. I.e., the void pointer passed to context::resume() is returned by context::suspend() in the other context, and the void pointer passed to context::suspend() is returned by context::resume() or context::start(), depending on which function was called before. context::start() has no void pointer argument because it enters the start of the function, and there is no call to context::suspend() to return the value.

== Exceptions in context function==

The code executed by context may not use catch ellipses and swallow the exception used for unwinding the stack otherwise stack unwinding doesn't work.
The code executed by context may not use catch ellipses and swallow the exception used for unwinding the stack. Doing so will cause stack unwinding to fail.

== Linking context ==

Boost.Context provides the ability to link context instances. In the constructor of context the last argument is a reference to a context (which must not be a not-a-context). If a context becomes complete and a successor was defined then the context-function of the successor will be invoked. It is possible to create a chain of contexts and depending on the do_return argument in the constructor of the last context in the chain the application terminates or the execution control is transfered back to the last invokation of context::resume(). Each call of context::suspend() for the chained context instances will return to context::resume().

Boost.Context provides the ability to link context instances. In the constructor of context, the last argument is a reference to another context (which must not be a not-a-context). If a context becomes complete and a successor was defined, then the context-function of the successor will be invoked. In this way, it is possible to create a chain of contexts. Depending on the do_return argument in the constructor of the last context in the chain, the application terminates or the execution control is transferred back to the last invocation of context::resume(). Each call of context::suspend() for the chained context instances will return to context::resume().

== Unwinding stack ==

Sometimes it is necessary to unwind the stack of an unfinished context because of local variables on the stack which allocated resourcesi (RAII pattern). The next to last argumenti do_unwind of contexts constructor deterimes if the stack should be automaticaly unwound in the destructor of the context or not. The unwinding of the stack can be triggered by context::unwind_stack() too. Preconditions for stack unwinding are the the instance of context is not a not-a-context, the context is not complete, does own a stack and is not running. After unwinding the context is complete (postcondition).

Sometimes it is necessary to unwind the stack of an unfinished context to destroy local stack variables (RAII pattern). The next to last argument of the context constructor, do_unwind, determines if the stack should be automatically unwound in the destructor of the context. The unwinding of the stack can be triggered by context::unwind_stack() too. Preconditions for stack unwinding are as follows: the instance of context is not a not-a-context, the context is not complete, the context does own a stack and is not running. After unwinding the context is complete (postcondition).