Re: [boost] [context] ready

Subject: Re: [boost] [context] ready
From: Stewart, Robert (Robert.Stewart_at_[hidden])
Date: 2011-11-14 08:08:17

Keith Jeffery wrote:
> Oliver Kowalke wrote:
>
> > 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.

My corrections to Keith's corrections.

> == Synopsis ==
>
> 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.

Either "thread local storage" or "thread-local storage".

> == Executing Context ==
>
> 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
                                                  ^^^^
by

> additional arguments.

> A function or callable object that requires arguments can have
> them supplied as additional arguments to the context
> constructor.

Additional arguments needed by a function or callable object are supplied as additional arguments to the context constructor.

> The kernel never 'sees' the context switches.

The kernel is not involved in the context switches.

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

The void pointer argument passed to context::resume(), in one context, is returned by context::suspend() in the other context.  The void pointer passed to context::suspend(), in one context, is returned by context::resume() (or context::start(), depending upon which function was called previously) in the other context.  Because context::start() has no void pointer argument, there is no corresponding context::suspend() call.

> == Exceptions in context function==
>
> 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.

Code executed by context must not prevent the propagation of the Boost.Context stack unwinding exception.  Absorbing that exception will cause stack unwinding to fail.  Thus, any code that catches all exceptions must rethrow the pending exception.

(Can you simply name the exception type here rather than being circumspect?  If so, replace "Boost.Context stack unwinding" with the type.)

> == Linking context ==
>
> 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

The last constructor argument is a reference to another context other than not-a-context.

(The original phrasing used "a not-a-context".  I haven't looked.  Can there be more than one kind of a "not-a-context" or is that a sentinel state?  If the latter, what I've written is correct.  If not, then "a not-a-context" is better.)

> 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

s/the execution/execution/

> last invocation of context::resume(). Each call of
> context::suspend() for the chained context instances will
                     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

, for the chained context instances,

> return to context::resume().

> == Unwinding stack ==
>
> Sometimes it is necessary to unwind the stack of an unfinished
> context to destroy local stack variables (RAII pattern). The
                                          ^
so they can release allocated resources

> next to last argument of the context constructor, do_unwind,
> determines if the stack should be automatically unwound in the
> destructor of the context.

s/determines...context/indicates whether the destructor should unwind the stack/

> The unwinding of the stack can be
> triggered by context::unwind_stack() too.

Stack unwinding can also be triggered by calling context::unwind_stack().

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

Stack unwinding assumes the following preconditions:

 * The context is not not-a-context
 * The context is not complete
 * The context is not running
 * The context owns a stack

After unwinding, a context is complete.

_____
Rob Stewart                           robert.stewart_at_[hidden]
Software Engineer                     using std::disclaimer;
Dev Tools & Components
Susquehanna International Group, LLP  http://www.sig.com

________________________________

IMPORTANT: The information contained in this email and/or its attachments is confidential. If you are not the intended recipient, please notify the sender immediately by reply and immediately delete this message and all its attachments. Any review, use, reproduction, disclosure or dissemination of this message or any attachment by an unintended recipient is strictly prohibited. Neither this message nor any attachment is intended as or should be construed as an offer, solicitation or recommendation to buy or sell any security or other financial instrument. Neither the sender, his or her employer nor any of their respective affiliates makes any warranties as to the completeness or accuracy of any of the information contained herein or that this message or any of its attachments is free of viruses.