January 2012 - Boost - lists.preview.boost.org

Re: [boost] [Boost.Move] [Boost.Container] Compiling with older versions of Boost and Performance
by Thomas Jordan 08 Jan '12

08 Jan '12

> Message: 3 > Date: Sat, 07 Jan 2012 15:58:20 +0100 > From: "Vicente J. Botet Escriba" <vicente.botet(a)wanadoo.fr> <snip> > Le 07/01/12 12:10, Thomas Jordan a ?crit : >> Hi, >> I am interested in experimenting with v1.48 Boost.Move and >> Boost.Container. However, I am otherwise constrained to using Boost >> libraries v1.33.1 with >> a Sun C++ v5.10 compiler. I couldn't seem any 'Boost library >> dependencies' listed in the Move/Container documentation, but a quick >> look through the header files suggests >> that it is mainly MPL and Type Traits. So... >> First question: would it be feasible for me to combine the headers for >> these two libraries with the v1.33.1 libraries and get it to work (albeit >> maybe with a little customisation), or would it be a big job/non-starter? >> Second question - I don't see any performance analysis published for >> Boost.Move. I know that move semantics is about more than improved >> performance, but am interested in that side of things, especially as the >> above compiler appears suboptimal in terms of copy elision and RVO. I am >> wondering for example whether are there any (compiler-specific) factors >> which could mitigate against the performance benefits of doing a move vs >> a copy of a vector, using these libraries, for example. >> > > Hi, > > unfortunately Boost.Move and Boost.Container are not working up to now > on Sun c++ even on trunk (1.49). See > http://www.boost.org/development/tests/trunk/developer/container.html. > > Best, > Vicente Thanks for pointing me to that. In general is there anything more detailed than pass/fail available to look at? Is the assumption that something with so many fails it not fixable one the library side, and is not worth investigating? Regards, T.

2 1

[docs][crc] Did I do new documentation correctly?
by Daryle Walker 08 Jan '12

08 Jan '12

I completely redid the documentation for Boost.CRC in changeset [76335]. It uses Doxygen and Quickbook. I guessed on how to do it by copying files from Boost.Move. But I only did stuff within the BOOST_ROOT/libs/crc/* directory. I didn't make changes to other directories, especially the BOOST_ROOT/doc/* directory. Is stuff in that directory supposed to be automatically built? Other concerns: 1. The quickbook/doxygen system doesn't seem to handle "\todo" constructs correctly. 2. Is there a way to #define various common macros, like BOOST_STATIC_CONSTANT, so they get expanded correctly in Doxygen? Is there a "Doxyfile," or can the needed Doxygen parameters be tweaked in the Jamfile.v2? 3. I guessed that the next release will be "1.49.0", is that right? 4. Content-wise, did I miss anything? Daryle W.

3 4

compile time parser generator
by Martin Bidlingmaier 08 Jan '12

08 Jan '12

Hello, with c++11's constexpr it got possible to parse strings in c++ at compile time. I've written a parser generator to create an AST for a given EBNF syntax at compile time, which can be traversed at both run time and compile time (actually, parsing can take place at run time, too, but it's probably rather slow). At the moment, the only compiler I know of that implements enough of c++11 features is gcc (version >= 4.6). Is refining my implementation worth the effort, has such a library a chance to make it into boost? Is maybe somebody already working on this? Sincerely, Martin Bidlingmaier -- NEU: FreePhone - 0ct/min Handyspartarif mit Geld-zurück-Garantie! Jetzt informieren: http://www.gmx.net/de/go/freephone

7 10

no match for ‘operator=’ error with circular_buffer iterator when addressing buffer by reference?
by Bernd Prager 08 Jan '12

08 Jan '12

I am trying do use a circular_buffer iterator and run into problems when I try to write a copy constructor for my class. g++ (GCC) 4.5.3 generates following error: Test.cpp: In copy constructor ‘Test::Test(const Test&)’: Test.cpp:23:18: error: no match for ‘operator=’ in ‘it2 = boost::circular_buffer<T, Alloc>::begin() const [with T = int, Alloc = std::allocator<int>, boost::circular_buffer<T, Alloc>::const_iterator = boost::cb_details::iterator<boost::circular_buffer<int>, boost::cb_details::const_traits<std::allocator<int> > >]()’ /usr/local/include/boost/circular_buffer/details.hpp:253:15: note: candidate is: boost::cb_details::iterator<Buff, Traits>& boost::cb_details::iterator<Buff, Traits>::operator=(const boost::cb_details::iterator<Buff, Traits>&) [with Buff = boost::circular_buffer<int>, Traits = boost::cb_details::nonconst_traits<std::allocator<int> >, boost::cb_details::iterator<Buff, Traits> = boost::cb_details::iterator<boost::circular_buffer<int>, boost::cb_details::nonconst_traits<std::allocator<int> > >] What do I miss. Can anybody help? Thank you, -- Bernd #include <boost/circular_buffer.hpp> class Test { public: Test(); Test(const Test&); private: boost::circular_buffer<int> b; }; Test::Test() { b.resize(10); } Test::Test(const Test &t) { b.resize(10); size_t s1 = b.size(); size_t s2 = t.b.size(); boost::circular_buffer<int>::iterator it1 = b.begin(); boost::circular_buffer<int>::iterator it2 = t.b.begin(); } int main() { Test *t = new Test(); return 0; }

2 2

Re: [boost] [Boost.smart_ptr] Thread Safety
by Thomas Jordan 08 Jan '12

08 Jan '12

Message: 7 Date: Sat, 07 Jan 2012 16:49:07 -0500 From: Dave Abrahams <dave(a)boostpro.com> To: boost(a)lists.boost.org Subject: Re: [boost] [Boost.smart_ptr] Thread Safety Message-ID: <m24nw7p4j0.fsf(a)pluto.luannocracy.com> Content-Type: text/plain >on Sat Jan 07 2012, "Thomas Jordan" <thomasjordan-AT-btinternet.com> wrote: >> Hi, >> Is shared_array completely thread-safe, including >> destruction/reference counting? From the code in >> /boost/detail/sp_counted_base_pt.hpp it looks like it probably is but >> according to >> >> http://www.boost.org/doc/libs/1_33_1/libs/smart_ptr/shared_ptr.htm#ThreadSa… >I can't reach that (very ancient) page right now, but... The documentation for this is example is the same in the latest v1.48 release. >> // thread A >> p3 = p2; // reads p2, writes p3 >> >> // thread B >> // p2 goes out of scope: undefined, the destructor is considered a "write >> access" >> >> shared_ptr isn't completely thread-safe for simultaneous read and >> write/destruct access? The same would presumbly apply to shared_array? >> Maybe I've missed something, are there compile-time configuration >> options to determine level of safety? >shared_ptr<T> is almost exactly as threadsafe as T* is. In this case, >thread A has a reference to an object on B's stack. That object is >called p2. If thread A tries to use that object's value while the >object is being destroyed, yeah, that's a race condition. >The way to avoid this situation is for thread B to pass p2 to thread A >by value, thus creating p2a, which thread A can read without concern. >Now there's no race condition. Note: this change does /not/ cause the T >object held by p2 to be copied. Thanks, I think my confusion arose from my inferring that the P2 in thread A in this example was shorthand for P2a, i.e., a copy of the actual P2 in thread B. Makes sense as per your interpretation. Regards, T.

1 0

[Boost.Poly] Runtime Concepts
by Thomas Jordan 08 Jan '12

08 Jan '12

Hi, Forgive me if this post strays into territory beyond Boost, but I was looking at the Adobe library http://stlab.adobe.com/group__poly__related.html and some of the research papers by Sean Parent et al. describing it, which I guess many people on this list will be familiar with. Is there any reason why this library/something akin has not been put into Boost? Is it simply that it will always live in Adobe Source Libraries and there is no point duplicating in Boost? Second question - the research papers on this seemed to peter out around 2009, is there any further work going on, or has this approach been taken as far as deemed interesting, or even been informally deprecated in favour of something else? Regards, T.

4 3

[Boost.smart_ptr] Thread Safety
by Thomas Jordan 07 Jan '12

07 Jan '12

Sorry, please ignore my previous post - finger trouble. The question is as follows: ------ Hi, Is shared_array completely thread-safe, including destruction/reference counting? From the code in /boost/detail/sp_counted_base_pt.hpp it looks like it probably is but according to http://www.boost.org/doc/libs/1_33_1/libs/smart_ptr/shared_ptr.htm#ThreadSa… // thread A p3 = p2; // reads p2, writes p3 // thread B // p2 goes out of scope: undefined, the destructor is considered a "write access" shared_ptr isn't completely thread-safe for simultaneous read and write/destruct access? The same would presumbly apply to shared_array? Maybe I've missed something, are there compile-time configuration options to determine level of safety? Regards, T.

2 1

[Boost.Move] [Boost.Container] Compiling with older version of Boost and performance
by Thomas Jordan 07 Jan '12

07 Jan '12

Hi, I am interested in experimenting with v1.48 Boost.Move and Boost.Container. However, I am otherwise constrained to using Boost libraries v1.33.1 with a Sun C++ v5.10 compiler. I couldn't seem any 'Boost library dependencies' listed in the Move/Container documentation, but a quick look through the header files suggests that it is mainly MPL and Type Traits. So... First question: would it be feasible for me to combine the headers for these two libraries with the v1.33.1 libraries and get it to work (albeit maybe with a little customisation), or would it be a big job/non-starter? Second question - I don't see any performance analysis published for Boost.Move. I know that move semantics is about more than improved performance, but am interested in that side of things, especially as the above compiler appears suboptimal in terms of copy elision and RVO. I am wondering for example whether are there any (compiler-specific) factors which could mitigate against the performance benefits of doing a move vs a copy of a vector, using these libraries, for example. Regards, T.

2 1

[Boost.smart_ptr] Thread Safety
by Thomas Jordan 07 Jan '12

07 Jan '12

Hi, Is shared_array completely thread-safe. including destruction/reference counting? http://www.boost.org/doc/libs/1_33_1/libs/smart_ptr/shared_ptr.htm#ThreadSa… // thread A p3 = p2; // reads p2, writes p3 // thread B // p2 goes out of scope: undefined, the destructor is considered a "write access" /bb/source/boost/boost_1_33_1/boost/detail/sp_counted_base_pt.hpp

1 0

On the lack of manpower: (Apache stdcxx)
by Jim Bell 06 Jan '12

06 Jan '12

Though this isn't news, I just came across it and it speaks to our common problem. (And it's of interest to boost users in general.) Note that ARM and Sun are even invested in stdcxx to some extent. From Apache's C++ Standard Library project <http://stdcxx.apache.org/status/2011-02.txt>: Stdcxx continues to be dormant. All but [1] committer have moved on to other projects. The only remaining committer (the VP of the project) is too busy with his day job to make even small changes, or to put out the long-awaited patch release, stdcxx 4.2.2. A number of users and organizations have been using the project and expressed interest in contributing to it. Several submitted patches, others have offered help with the project build and test infrastructure. Unfortunately, since no committer is available to review patches and guide the contributors through the ASF process to enable them to gain commit privileges there seems to be little hope of reviving stdcxx. A possible solution that would allow contributions to resume is to grant commit privileges to the handful of contributors who have already submitted some patches or expressed serious interest in contributing going forward. Another alternative is to move stdcxx to a repository outside of ASF such as SPI (http://www.spi-inc.org/) where interested developers could start committing changes on their own right away, without going through the "training" process. This seems to the preferred solution among at least some of the interested users. Are there any other options? Future plans: Unless the issue with contributions can be resolved in the next quarter I suggest to retire the project.

5 6

[Boost.Lambda] Some new features are suggested: return, iterating yield, & local var
by Huang Huan 06 Jan '12

06 Jan '12

Hi boosters, I'm intrested in Lambda, so I have worked out some new features, and suggest boost lib add them. What can I do next? NEW features: 1. return. why lambda lib do not include this? 2. generate iterator/iteration by lambda using yield return/yield break. 3. local/global var declare and using. 1. return e.g. boost::function<char(int)> f = ( if_ ( _1 >= 0 ) [ return_('a') ], return_('b') ); p.s. return should be supported. 2. iterator/iteration generation by lambda using yield return/yield break const char* p; // we shuld use the local var inside lambda instead of this var p. refer to section 3 iteration<char> it = ( for_(var(p) = _1, *var(p), var(p)++) [ if_(*var(p) != ' ') [ yield_return(*var(p)) ] if_(*var(p) == ';') [ yield_break() ] ] ) ("I love this game; no use"); p.s. The packing iteration interface is very like the yield keyword in C# IEnumeable 3.local/global var declare and using e.g. char a; var_name x, y, z; global_var<int>(y); // put this line inside lambda is ok, just before use it ( ( local_var<int>(x), // local var declare // global_var<int>(y), var(a) = 'a', var<int>(x) = _2, // using local var x ), ( local_var<char>(z), var(a), var<int>(x) = _1, // error! x is not local var here. var<int>(y), // ok for global even if another lambda var<char>(z) = 'b', ) ) p.s. Now, in my work. It's hard to simplify var<T>(x) to var(x). It's a hard template working.

5 14

Re: [boost] [log] Status (was: Is there any interest in a Group of library like to Application System!)
by Andrey Semashev 06 Jan '12

06 Jan '12

On Wednesday, January 04, 2012 09:08:16 Renato Tegon Forti wrote: > Hi Andrey, > > Thanks for your response! What is status of your lib? Do you need any help? The library is moving slowly to v2 release. Right now I'm wrapping up bounded async frontends, I intend to finish them by the weekend. Other things left to be done before the release are: - Port filters and formatters to Phoenix v3. As a part of it, improve error messages in exceptions and make filters and formatters not throw by default. - Introduce "default" sink concept to mitigate problems with trivial and advanced logging coexistence. Trivial logging will no longer initialize the library under the hood. - Implement a common attribute registration mechanism to simplify library extension. This should solve problems with settings file parser not recognizing user-defined attribute types. - Update the documentation. There are many other things to be done but they are not showstoppers for the release. Yes, help would be much appreciated, most notably in the porting to Phoenix v3 part. If anyone is willing to help, please contact me privately or through this list.

3 9

[Graph] Concept check VertexMutablePropertyGraph
by Jens Müller 05 Jan '12

05 Jan '12

Hi, http://www.boost.org/doc/libs/1_48_0/libs/graph/doc/MutablePropertyGraph.ht… (I cannot find docs for VertexMutablePropertyGraph or EdgeMutablePropertyGraph) says that the types boost::graph_traits<G>::vertex_property_type and boost::graph_traits<G>::edge_property_type must exist. However, the concept checks (in boost/graph/graph_concepts.hpp) check for vertex_property_type<G>::type and edge_property_type<G>::type, respectively. Several questions: 1. Should there be separate docs for VertexMutablePropertyGraph and EdgeMutablePropertyGraph? 2. Should there be an actual concept check implementation for MutablePropertyGraph combining the two? 3. Should the concept check look for boost::graph_traits<G>::vertex_property_type instead of ertex_property_type<G>::type? [and the same for edge] 4. For the LEDA adapter, i.e., external adaptation, do I have to specialize vertex_property_type<G> and edge_property_type<G>? Best, Jens

2 3

[graph] VertexListGraph and InputIterator, and LEDA graph
by Jens Müller 05 Jan '12

05 Jan '12

Hi all, I'm currently fixing up leda_graph.hpp so it passes the tests, or indeed, fixing the tests ... A leda::GRAPH<int,int> (=Graph) has to fulfill VertexListGraphConcept. This means that boost::graph_traits<G>::vertex_iterator has to be a MultiPassInputIterator, i.e., also a InputIterator. I cannot read from http://www.sgi.com/tech/stl/InputIterator.html that it must be possible that you can compute the difference between two iterators. But apparently the concept check (which fails) requires a difference type, which must be a signed integer. Is this a bug in the concept check? The vertex_iterator type is defined in leda_graph.hpp using iterator_facade: class vertex_iterator : public iterator_facade<vertex_iterator, leda::node, bidirectional_traversal_tag, const leda::node&, const leda::node*> { public: vertex_iterator(leda::node node = 0, const leda::GRAPH<vtype, etype>* g = 0) : base(node), g(g) {} private: const leda::node& dereference() const { return base; } bool equal(const vertex_iterator& other) const { return base == other.base; } void increment() { base = g->succ_node(base); } void decrement() { base = g->pred_node(base); } leda::node base; const leda::GRAPH<vtype, etype>* g; friend class iterator_core_access; }; Is maybe iterator_facade insufficient? For me, bidirectional_traversal_tag does not indicate that random access is possible ... -- Jens

2 4

[chrono] Possible bug in boost::chrono::process_real_cpu_clock::now() under Windows 32bits
by ivan.lelann＠free.fr 05 Jan '12

05 Jan '12

Hi, As of 1.48 Boost.Chrono contains code below for boost::chrono::process_real_cpu_clock::now() (boost\chrono\detail\inlined\win\process_cpu_clocks.hpp) clock_t c = ::clock(); /* ... */ return time_point( duration(c*(1000000000l/CLOCKS_PER_SEC)) ); duration::rep is int64/nanoseconds, clock_t is long. This is VS2008, Win XP 32bits. I think "c" should be cast to duration::rep before being multiplied. I randomly get negative time_point and this seems to be fixed by replacing "c" with "((duration::rep) (c))" in duration constructor : duration( ((duration::rep) (c)) *(1000000000l/CLOCKS_PER_SEC)) Can someone confirm my view and that the fix is correct ? Regards, Ivan

3 3

Is there any interest in a library for Application System? (Request for comments)
by Renato Tegon Forti 05 Jan '12

05 Jan '12

Some detail (Brainstorm): This library will provide a simple way to create an application that can be: . A Server Application A server application usually starts when system boot, and then remain running as background process, don't matter who is currently logged. In Windows this will a "Windows Service" and in UNIX a "UNIX Daemon", and we can create a "Neutral Application" that is not a daemon and service, but uses "service interface" that will provide methods like an "init", "interrogate", "restart" and so on. Some type of "system global mutex" will be implemented in this flavor, then if user want, he can determine that only one instance of service will run in a system in same time. A web server, data base server and so on area examples. . A Usual Application A usual application is a normal application, that don't need all of features provided by "server application" usually is started by a user and run by a determined period. A command, mail client, MPI master/Slave and so on area examples. . Base Class Both classes will be derivated of environment class that will provide common thinks and proprieties like an "app path", "app name", "app work dir" and so on. For sample: A user that want create a server, extend your class of "server class" and then override methods that want to get needed behavior. // windows service, or daemon class myapp : public boost::application::server{}; // neutral server class myapp : public boost::application::server<neutral>{}; // usual application class myapp : public boost::application::app{}; Note that: 1) Application can be configured using Boost.Program_options 2) I want use Boost.Log to provide log functionality when available. 3) I want create a "service model" then I want use Boost.Extension to provide dynamically late bind extension (Pluf-in System). What Boosters think? This is useful or is fool lib? Boosters think that "this kind of lib" is very specific, and violate: "The library must be generally useful and not restricted to a narrow problem domain." or this kind of system is relevant to boost. Please let me know the correct way to follows! Please make suggestions! What more else? Thanks

2 2

Copyright and authorship notices
by Jens Müller 05 Jan '12

05 Jan '12

Hi all, what is the policy of adding a Copyright notice and entries to the author list when patching existing files? I found http://www.boost.org/development/requirements.html#Ownership, but it is not completely helpful. -- Jens

3 5

[thread] Boost.Thread defines boost::move which conflicts with Boost.Move
by Hartmut Kaiser 05 Jan '12

05 Jan '12

VC10, SVN trunk: #include <boost/move/move.hpp> #include <boost/thread.hpp> int main() { return 0; } Results in: .../boost/thread/detail/move.hpp(28) : error C2995: 'remove_reference<T>::type &&boost::move(T &&)' : function template has already been defined .../boost/move/move.hpp(466) : see declaration of 'boost::move' IMHO, Boost.Thread needs to be changed to rely on Boost.Move for move semantics instead of defining its own implementation for boost::move(). Regards Hartmut --------------- http://boost-spirit.com http://stellar.cct.lsu.edu

4 13

Font used in the current Boost logo
by Mateusz Łoskot 04 Jan '12

04 Jan '12

Hi, I have tried to find what font is used in the Boost logo but without any luck. There seem to be no logo in vector format included in the trunk. The SVG file from the logo variants is not helpful: http://dbp-consulting.com/boostvariantslogo.html Does anyone know where to find the font or vector version of the logo? Best regards, -- Mateusz Loskot, http://mateusz.loskot.net

2 1

[geometry] GGL mailing list moved
by Mateusz Loskot 04 Jan '12

04 Jan '12

Hi, To Whom It May Concern... The Boost.Geometry library mailing list has moved from ggl at lists.osgeo.org server to geometry at lists.boost.org server. All existing subscribers and archives have been moved to the new server. The new list is available at: http://lists.boost.org/mailman/listinfo.cgi/geometry as well as listed on the main page: http://lists.boost.org/ It is also mirrored at Nabble: http://boost-geometry.203548.n3.nabble.com/ (Mirror at gmane.org may be added in future.) The old list at lists.osgeo.org will be wiped out soon. If anyone experiences any problems with the new geometry at lists.boost.org, please contact me directly. I'd like to thank OSGeo Foundation for hosting the first mailing list and the Boost mailman admins for help with the new one. Best regards, -- Mateusz Loskot, http://mateusz.loskot.net

1 0

Re: [boost] [Container] deque emplace() requirements
by Ion Gaztañaga 04 Jan '12

04 Jan '12

El 04/01/2012 12:50, Szymon Gatner escribió: > 2011/12/13 Ion Gaztañaga<igaztanaga(a)gmail.com>: >> >> You are right, it's a bug. I'll try to fix it when I get some time. >> > > Got a chance to take a look at this? I think it's fixed in trunk, you'll need to update Boost.Intrusive as well. Best, Ion

1 0

Is there any interest in a Group of library like to Application System!
by Renato Tegon Forti 04 Jan '12

04 Jan '12

I am proposing before a Log library in model of Log4cxx, but my plan is provide a full application system that will have: * Log System (Log4cxx Model) * Application System (Windows Service, Unix Daemon and Usual Application) -> Process Management (I don't know?) * Plugin System (service model): dynamically late bind extension. This will provide modular functionality that can be loaded in applications. For sample a service that can be loaded in application container, or a skin loaded in Client (MP3) Application. To illustrate: A developer that need create a server application will do: 1) Extend for "boost::application::server" and in this it use boost::log. (here if app is a Win32 then it have a Windows Service, or a daemon in unix) 2) To create service (modular application) he extend of "boost::service" to create a service and plug this service in runtime on "boost::application::server". Note that: Application can be configured using Boost.Program_options for sample. We can use Boost.Log to log, or (I don't know) we can buid Log4 model on top of Boost.Log? What Boosters think? Boosters think that "this kind of lib" is very specific, and violate: "The library must be generally useful and not restricted to a narrow problem domain." or this kind of system is relevant to boost. Please let me know the correct way to follows! Anyone that want participate is welcome! Ps: Ps: We already have some discussion in "Log Lib" topic! Thanks

3 3

Log Lib?
by Renato Tegon Forti 04 Jan '12

04 Jan '12

Is there any interest in a library to "Log" in model of Log4cxx? Thanks

2 1

Log Lib!
by Renato Tegon Forti 03 Jan '12

03 Jan '12

Is there any interest in a library to "Log" in model of Log4cxx? Thanks

6 10

[context review] Quick Review
by Stewart, Robert 03 Jan '12

03 Jan '12

Here's my quick review of the proposed Boost.Context library. I'm not familiar with the kernel-level machinations involved to save and restore the execution state managed by the context class, so I cannot comment on such implementation details and whether they satisfy the acceptance criteria. Consequently, I didn't bother to look at the implementation. The examples are good, but the discussion or comments are somewhat lacking. For example, the Enumerator example is based upon an enumerator class type which is not commented and has very little introductory text. There's a link to C# documentation on the yield keyword, but no association of enumerator's yield_return() to C#'s "yield return" statement or yield_break() to "yield break". Those associations can be inferred easily enough, but are better stated explicitly. The enumerator example is further confused by indicating that a call to yield_return() in the power derivate returns a value to the while loop in main(). What's missing is that yield_return() calls context::suspend() on enumerator's context data member which returns control to enumerator<T>::get(), which is called by main()'s while loop. The entire enumerator example should be introduced by discussing the power class first, without implementation details: class power { public: power(int _base, int _exponent); bool get(int & _value); }; Then, the example can show main(), since the above interface is sufficient. That done, the example can turn the reader's attention to how to implement power by referring to the C# yield documentation example and then relating it to Boost.Context. That will lead to the enumerator class. (Making enumerator a class template complicates matters more than necessary, BTW.) Finally, you should show expected output. I'd like to see a performance comparison of using Boost.Context versus Chris Kohlhoff's coroutines. Can his coroutines be replaced with yours without loss of efficiency? Would it require a different stack allocator to match the performance of his coroutines? (Developing the example in that direction would be useful to illustrate writing a custom stack allocator.) I don't find anything related to the Movable Stack concept suggested in the acceptance criteria. The documentation of the StackAllocator is lacking, but I've suggested a rewrite below. With that rewrite, I think it satisfies the Stack concept required for acceptance. There are no performance figures for Windows. Shouldn't there be? I think I recall that the build system doesn't support the necessary information, by default, to permit building an ABI compatible version of the library. If that's not the case, then the "How to build and install" section needs more work. Either way, the Build acceptance criteria has not quite been met yet. The _suggested_ callback-based linking was not adopted in lieu of fc_link. There should be some rationale or a FAQ for that. I've called for still more work on the documentation, but as it stands, with the concept changes I've suggested, I'm satisfied that Oliver has met the documentation acceptance criteria. _____________________________________________ Documentation comments follow. _______________ Overview This section is useful and clear, except for the second sentence of the third paragraph. It doesn't connect to the library in question as it ought and is worded a little unclearly. I'd suggest the following instead: "By contrast, transferring control within a single thread, as _context_ does, requires only a few hundred CPU cycles since it involves no system calls." You might also add something like, "which makes them useful in more contexts, particularly when implementing higher level execution control systems", to that sentence. What's missing is a Motivation section or more information in the Overview to better explain why someone would want to use Boost.Context versus other options (whatever they may be). _______________ How to build and install There should be an introductory paragraph, something like the following: "Boost.Context must be built for the particular compiler(s) and CPU architecture(s) being targeted. Each combination requires specific build command arguments as documented below." The bullets at the top of the page are only needed until the library is accepted, so be sure to remove them upon acceptance. "On POSIX and Windows systems, GNU AS and MASM are respectively required for the assembler implementation of Boost.Context" is awkward. I suggest the following instead: "Boost.Context includes assembly code and, therefore, requires GNU AS for supported POSIX systems, and MASM for Windows systems." The Note is a little awkward and includes a spelling error. I suggest the following instead: "The architecture, instruction set, and address model are optional Boost.Build properties that must be given on the bjam command line, as shown in the table below." _______________ Executing a context 3rd para: s/a function or callable object/a _context-function_/ 5th para: this should be merged with para 4 and "and might be changed" should be inside the parentheses or I don't understand how it "might be changed". 6th para, 4th sent: Add the following to the end: ", after saving the new state of the original context" 6th para, last sent: Is there anything that ensures start() is called first and only once? Example: - The control transfer comments in fn() could be a little clearer: // transfer execution control back to main() ... // execution control transferred back from main() - The first "main() calls context ctx" would be better as "main() starts context ctx" - The comment, "// ctx.suspend() was called", in the while loop is only accurate until the for loop, in fn(), terminates, right? - Expected output is not shown _______________ Transfer of data Example: - Missing comments discussing the pointers on the receiving end. For example, in fn(), I'd expect the following: void * vp = ctx.suspend(&i); // vp is &x from main()'s call to ctx.resume(&x) int j = *static_cast<int *>(vp); // j == 10 because x == 10 in main() - Expected output is not shown _______________ Exceptions in context-function s/emits/emits/ Is forced_unwind a documented exception type? That is, can it be caught explicitly? If so, the reference to "forced_unwind" should be a link to its documentation and the following might be documented as legitimate: try { // code that might throw } catch (forced_unwind) { throw; } catch (...) { // possibly not rethrow pending exception } _______________ Terminating context Shouldn't this section name be something more like, "Handling execution context termination"? 2nd example: remove the "Done" line. The "never reached" comment can then be applied to "return EXIT_SUCCESS". _______________ Chaining contexts The first two sentences should be merged something like the following: "Boost.Context provides the ability to chain context instances by passing a reference to another context, other than _not-a-context,_ as the last constructor argument." You note that the application terminates or control is transferred back to the last invocation of context::resume(). Might not the transfer also be to context::start() (if suspend()/resume() are never called)? Important: I think you mean, "context::start() must not be called on a context that is a link in the chain begun by another context. That is, call context::start() only on the first context in a chain." _______________ Unwinding stack Name this section "Stack unwinding" 2nd para, 1st bullet: Should "not-a-context" be italicized? Speaking of italics, "context" is sometimes italicized and blue and other times plain. Example: Expected output is not shown Important: s/exception!/exceptions!/ _______________ context.html Variously through this page: s/an context/a context/ or s/an context/an instance/ s/unwinds the stack before destructing it/unwinds the stack first/ s/if precondition is not fulfilled/if a precondition is not satisfied/ s/nxt is linked/nxt becomes a subsequent link in a chain/ s/the execution control/execution control/ s/The execution control/Execution control/ s/Destroyes/Destroys/ Is the move assignment operator safe against self-move assignment? start(): s/with wich/with which/ s/When the function returns/Upon return/ (to avoid confusion about whether start() or fn() has returned) resume(): s/back resuming/back, resuming/ s/ (means suspend()/, which means that suspend() returns/ (note the formatting of "returns" should be normal, not code) "[[Returns:]" is malformed Effects could be rewritten, something like the following, to be clearer: "None, if *this was not suspended by a previous call to suspend(). Otherwise, execution control is transferred back to the caller of suspend(), thereby resuming *this. The argument, vp, will be returned by the previous call to suspend()." suspend(): I think Effects is incomplete. There are spelling errors. How about the following? "Transfers execution control to the caller of the most recent call to start() or resume(). The argument, vp, will be returned by start() or resume()." unwind_stack(): Effects: suggestion: "Destroys all objects allocated on the stack, owned by *this, in the reverse order of their allocation." Non-member function swap(): Effects: suggestion: "As if l.swap(r)." _______________ Stack allocation 1st para: - "stack allocator" should probably be italicized rather than rendered as code. - Concept names are usually rendered with camelcase. Thus, s/stack-allocator/StackAllocator/. 2nd para: This should be the start of a "StackAllocator Concept" section: "StackAllocator Concept "A stack allocator must satisfy the StackAllocator concept requirements shown in the following table, in which a is an object of a StackAllocator type, p is a void *, and s is a std::size_t: " " Expression | Return type | Notes " ----------------------------------------------- " a.allocate(s) | void * | Returns a pointer to s bytes allocated from the stack " ----------------------------------------------- " a.deallocate(p, s) | void | Deallocates s bytes of memory beginning at p, a pointer previously returned by alloc.allocate()" The current documentation of allocate() and deallocate() are no longer needed. Important: This should be rephrased in terms of the concept to something like the following: "The implementation of allocate() might include logic to protect against exceeding the context's available stack size rather than leaving it as undefined behavior." You might add a note that the result of calling deallocate() with a pointer not returned by allocate() results in undefined behavior. _______________ Helper functions 1st para: s/an easy/easy/ _______________ Low level API (boost_fcontext_t) You refer to "ucontext_t" with no link or description. The example code is out of place without first seeing the documentation of boost_fcontext_t and related functions. Following the -> navigation order, the example comes first. Commenting the example and providing an introduction explaining what it illustrates would work. There is no expected output shown for the example. Presumably, the low level API is the part to port to new platforms, yet you don't state that. _______________ Struct boost_fcontext_t and related functions There is no documentation for boost_fcontext_t, particularly as it appears to be just an alias for boost_fcontext. I thought for a moment that you intend to permit different platforms to redefine the typedef to refer to different structures, as needed, but you've documented boost_fcontext_stack's ss_base and ss_limit fields, which suggests that you intend those to be part of the low level, yet documented, API. The result is that I can't figure out the purpose of the typedef. The "fc_" prefix makes sense, since it is used in boost_fcontext. By contrast, the "ss_" prefix does not make sense. I could see "fcs_", for example. ss_limit: Is the stack defined by [ss_base, ss_limit) or [ss_base, ss_limit]? "Pointer to the bottom of the stack" is ambiguous. fc_stack: The description is a little off. How about, "Tracks the memory for the context's stack"? fc_link: The description could be improved: "The address of the next context link in a chain, if any." boost_fcontext_start(): Effects are a little confusing. My suggestion: "Stores the current context data (stack pointer, instruction pointer, and CPU registers) to *ofc and restores the context data from *nfc, which implies jumping to *nfc's execution context. This function must be called when first entering *nfc's execution context." boost_fcontext_start(): Need a "Returns:" "The result of calling boost_fcontext_jump()." boost_fcontext_jump(): This likewise needs some work: Effects: "Stores the current context data (stack pointer, instruction pointer, and CPU registers) to *ofc and restores the context data from *nfc, which implies jumping to *nfc's execution context. The pointer argument, vp, is passed to the current context to be returned by the most recent call to boost_fcontext_start() or boost_fcontext_jump() in the same thread." Returns: "The third pointer argument passed to the most recent call to boost_fcontext_jump(), if any." boost_fcontext_make(): Precondition: s/finished /finishes, / and s/inside/in/ boost_fcontext_make(): Effects: s/if the context is activated next time/when the context is activated next/ _______________ Continuation 1st para: s/from Java/from the Java/ 2nd para: s/for functors objects/for a functor/ 3rd para: You say the co-routines run "in parallel", but there is no parallelism, so you should be clear about what does occur. _______________ ASIO 2nd para: s/a echo/an echo/ 3rd para: I quickly got lost in this description because it assumes familiarity with code presented later. It also assumes familiarity with control flow in Asio which can be described rather than assumed. 3rd para: s/reentered a/reentered, a/ s/a asynch./an async/ 4th para: s/adavantage/advantage/ s/bind()-version/bind() version/ s/easier implemented/more easily implemented/ s/For instance if/For instance, if/ s/a message is partialy received/only part of a message is received/ s/parser or serviced)/parsed or serviced),/ _______________ Performance The bullets are too terse. Perhaps the following captures your intent: "Performance of Boost.Context was measured on the platforms shown in the following table. Performance measurements were taken using rdtsc, with overhead corrections, on x86 platforms. In each case, stack protection was active, cache warm-up was accounted for, and the one running thread was pinned to a single CPU. The code was compiled using the build options, 'variant=release cxxflags=-DBOOST_DISABLE_ASSERTS'. "The numbers in the table are the number of cycles per iteration, based upon an average computed over 1000 iterations." _______________ Rationale NoThrow guarantee: I think you meant the following: "Member functions of context do not throw exceptions but do require that certain preconditions are satisfied: context jumps can only be made by instances which are not a _not-a-context_ and which are not complete." Pimpl idiom, 1st para: s/ it was required to separate both features in separate classes via pimpl idiom/, the use of the Pimpl Idiom was necessary/ Pimpl idiom, 3rd para: I suggest the following: "The Pimpl Idiom allows type-erasing the _stack-allocator_ type." Unwinding: s/resource/resources/ and s/a exception/an exception/ Protecting the stack: There are many changes to make here, so I'll suggest this rewrite: "Because the stack's size is fixed -- there is no support for split stacks -- it is important to protect against exceeding the stack's bounds. Otherwise, in the best case, overrunning the stack's memory will result in a segmentation fault or access violation and, in the worst case, the application's memory will be overwritten. stack_allocator appends a guard page to the stack to help detect overruns. The guard page consumes no physical memory, but generates a segmentation fault or access violation on access to the virtual memory addresses within it." setjmp()/longjmp(): s/The C99/C99/ s/frame, e.g. jumping/frame. Therefore, jumping/ ucontext_t: I don't know why anything in this section is included after the first sentence. ucontext_t, para 1: s/makecontext():/makecontext() is:/ ucontext_t, para 2: s/alter/later/ I would omit the "The signature of func is" part. That's clear from the makecontext() function pointer argument. Windows fibers: s/befor/before/ _____ Rob Stewart robert.stewart(a)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.

2 1