Re: [boost] [context] ready

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

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

The following are some documentation comments.  I may offer more later.

A Motivation section would be useful on the initial page.  Why would anyone want to use the library?  What is a motivational use case that leads to using it and illustrates its capabilities?

__________
Overview

There are many issues with this section.  Rather than list them exhaustively, allow me to offer a rewrite:

"Boost.Context is a foundational library that provides a sort of cooperative multitasking on a single thread.  (Contrast that with the preemptive multitasking of multithreaded programming.)  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 _context_ instance represents a specific point in the application's execution path.  This is useful for building higher-level abstractions, like coroutines and fibers.

"A _context_ 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 stateful 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 _context_ 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 thousands of CPU cycles on x86 CPUs.  By contrast, transferring control among them requires only a few hundred CPU cycles because it does not involve system calls as it is done within a single thread."

__________
Context

The "Class context" link is out of place.  It links to the synopsis, despite the name of the next section on context.html.

_____
Synopsis

This is not a synopsis, which should be the context class definition.  It would appear that everything in this section would be better moved to the Context section at the top.

In reading the Overview, I understood that a context can be migrated to a new thread as being passive.  That is, that the kernel can change which thread executes the context.  That seems reasonable.  However, the warning in this section suggests that migration from one thread to another is not done passively, since the warning begins, "If contexts are migrated between threads".  Perhaps you mean that if contexts are used in a multithreaded application, they can be migrated among threads and, therefore, cannot reference thread local storage.

_____
Executing context

The section name should be "Executing a context".

In my correction to Keith Jeffery's correction of the second sentence in the first paragraph, I didn't think to note that it should be "by additional constructor arguments."

2nd para: "The context constructor uses a stack-allocator to allocate an associated stack, and the destructor uses the same stack-allocator to deallocate the stack.  The default stack-allocator is stack_allocator, but a custom stack-allocator can be passed to the constructor."

4th para: "The context-function, as well as its arguments, if any, are copied into the context's state.  If a reference is required, use boost::ref."

5th para: Merge this with the fourth paragraph.  s/be changed/change in the future/

6th para: "Calling context::start() transfers invokes the context-function in a newly created context complete with registers, flags, and stack and instruction pointers.  When control should be returned to the original calling context, call context::suspend().  The current context information (registers, flags, and stack and instruction pointers) is saved and the original context information is restored.  Calling context::resume() resumes execution in the second context.  Note that context::start() must be called first and only once."

The example code following the 6th paragraph is munged.  Look at the three lines following the first use of std::cout.

Warning: s/will result in/results in/

_____
Exceptions in context function

The section name should be, "Exceptions in context-functions".

1st para: "If the context-function emits an exception, std::terminate() is called."

_____
Terminating context

1st para, 1st sent: "The last context constructor argument is an enumerated type which determines what should happen when the context is complete (that is, when the context-function returns).  The available values are return_to_caller and no_return_to_caller."

1st para, 2nd sent: This should be a separate paragraph in order to introduce the example code.  It should then be reworded a bit (not to mention s/invokation/invocation/): "When the last constructor argument is return_to_caller, execution control is transferred back to the last invocation of context::start() or context::resume() when the context is complete, as shown in this example:".

2nd para: "When the last constructor argument is no_return_to_caller, the application terminates with an exit status of zero when the context is complete, as shown in the following example:".  BTW, I should think "exit" would be a better name for no_return_to_caller.

_____
Linking context

This section name should be, "Chaining contexts".  While they are being linked, it sounds better to say they are being chained together, because that implies the sequential execution nature of the relationship.

Referring to the last constructor argument in this section and in the Terminating context section is confusing.  I realize that there are overloads, and both references can be correct, but you need to reference these arguments differently.  For example, you can refer to the "flat_return_t argument" and the "context argument".

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