Hi, I found a mistake in the documentation. In the "Terminating context<http://ok73.ok.funpic.de/boost/libs/context/doc/html/context/context.html#context.context.terminating_context>" exemples, there is no "do_return" passed to the constructer but a "no_return_to_caller" in both exemples. 2011/11/6 Oliver Kowalke <oliver.kowalke@gmx.de>

Hi,

https://github.com/olk/boost.**context.git<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<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<http://lists.boost.org/mailman/listinfo.cgi/boost>

Hi there, I noticed this project and got really excited. Hopefully it won't meet the same fate as the coroutine library. Some comments: Pros: 1.) Impressive performance. Did you write some assembly for each platform to avoid having to swap out the signal masks and floating point context? 2.) Stack guard. This would be a huge win for me. Safety is always good. 3.) C++0x idioms. I'm glad to see movable being used. Cons: 1.) Void * argument passing. Perhaps there's some limitation that requires this. If so, then I'd be curious to read about it in the Rationale section. Even then, some syntactical sugar to hide the static cast may not be bad. 2.) Function pointers only? It looks like the library only accepts function pointers, not bound functions, functors, or lambdas. I suspect this is related to the fact that makecontext() accepts raw function pointers. Nevertheless, I've come to expect the ability to pass an arbitrary "callable" argument to boost libraries. If this is unreasonable, then I'd be curious to learn why in the Rationale section. Great work! Again, I'm really excited about the potential here, Taylor -----Original Message----- From: boost-bounces@lists.boost.org [mailto:boost-bounces@lists.boost.org] On Behalf Of Oliver Kowalke Sent: Sunday, November 06, 2011 5:20 AM To: boost@lists.boost.org 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

-----Original Message----- From: boost-bounces@lists.boost.org [mailto:boost-bounces@lists.boost.org] On Behalf Of Oliver Kowalke Sent: Sunday, November 06, 2011 4:20 AM To: boost@lists.boost.org 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).

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@sig.com 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.