[Boost-commit] svn:boost r78180 - trunk/libs/context/doc

Subject: [Boost-commit] svn:boost r78180 - trunk/libs/context/doc
From: oliver.kowalke_at_[hidden]
Date: 2012-04-24 11:49:12

Author: olli
Date: 2012-04-24 11:49:11 EDT (Tue, 24 Apr 2012)
New Revision: 78180
URL: http://svn.boost.org/trac/boost/changeset/78180

Log:
context: update of documentation

Added:
   trunk/libs/context/doc/Jamfile.v2   (contents, props changed)
Text files modified: 
   trunk/libs/context/doc/acknowledgements.qbk |     2 +-                                      
   trunk/libs/context/doc/fcontext.qbk         |    36 ++++++++++++++++--------------------    
   trunk/libs/context/doc/overview.qbk         |     4 ++--                                    
   trunk/libs/context/doc/performance.qbk      |    12 ++++++------                            
   trunk/libs/context/doc/rationale.qbk        |    26 +++++++++++++-------------              
   trunk/libs/context/doc/requirements.qbk     |     2 +-                                      
   6 files changed, 39 insertions(+), 43 deletions(-)

Added: trunk/libs/context/doc/Jamfile.v2
==============================================================================
--- (empty file)
+++ trunk/libs/context/doc/Jamfile.v2	2012-04-24 11:49:11 EDT (Tue, 24 Apr 2012)
@@ -0,0 +1,33 @@
+# (C) Copyright 2008 Anthony Williams
+#
+# Distributed under the Boost Software License, Version 1.0. (See accompanying 
+# file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+
+path-constant boost-images : ../../../doc/src/images ;
+
+xml context : context.qbk ;
+
+boostbook standalone
+    :
+        context
+    :
+        # HTML options first:
+        # Use graphics not text for navigation:
+        <xsl:param>navig.graphics=1
+        # How far down we chunk nested sections, basically all of them:
+        <xsl:param>chunk.section.depth=3
+        # Don't put the first section on the same page as the TOC:
+        <xsl:param>chunk.first.sections=1
+        # How far down sections get TOC's
+        <xsl:param>toc.section.depth=10
+        # Max depth in each TOC:
+        <xsl:param>toc.max.depth=3
+        # How far down we go with TOC's
+        <xsl:param>generate.section.toc.level=10
+        # Path for links to Boost:
+        <xsl:param>boost.root=../../../..
+        # Path for libraries index:
+        <xsl:param>boost.libraries=../../../../libs/libraries.htm
+        # Use the main Boost stylesheet:
+        <xsl:param>html.stylesheet=../../../../doc/html/boostbook.css
+    ;

Modified: trunk/libs/context/doc/acknowledgements.qbk
==============================================================================
--- trunk/libs/context/doc/acknowledgements.qbk	(original)
+++ trunk/libs/context/doc/acknowledgements.qbk	2012-04-24 11:49:11 EDT (Tue, 24 Apr 2012)
@@ -10,6 +10,6 @@
 I'd like to thank Adreas Fett, Artyom Beilis, Fernando Pelliccioni,
 Giovanni Piero Deretta, Gordon Woodhull, Helge Bahmann, Holger Grund, 
 Jeffrey Lee Hellrung (Jr.), Keith Jeffery, Phil Endecott, Robert Stewart,
-Vicente J. Botet Escriba.
+Steven Watanabe, Vicente J. Botet Escriba.
 
 [endsect]

Modified: trunk/libs/context/doc/fcontext.qbk
==============================================================================
--- trunk/libs/context/doc/fcontext.qbk	(original)
+++ trunk/libs/context/doc/fcontext.qbk	2012-04-24 11:49:11 EDT (Tue, 24 Apr 2012)
@@ -32,16 +32,16 @@
             // context-function
             void f( intptr);
 
-			// creates and manages a protected stack (with guard page)
-			boost::ctx::protected_stack stack( boost::ctx::default_stacksize() );
+            // creates and manages a protected stack (with guard page)
+            boost::ctx::protected_stack stack( boost::ctx::default_stacksize() );
 
-			// let fcontext_t fc use stack
-			fc.fc_stack.base = stack.address();
-			fc.fc_stack.limit =
-				static_cast< char * >( fc.fc_stack.base) - stack.size();
+            // let fcontext_t fc use stack
+            fc.fc_stack.base = stack.address();
+            fc.fc_stack.limit =
+                static_cast< char * >( fc.fc_stack.base) - stack.size();
 
-			// context fc used f() as context function
-			make_fcontext( & fc, f);
+            // context fc uses f() as context function
+            make_fcontext( & fc, f);
 
 __fcontext__ requires a pointer to the top of the stack (__fc_base__) as well
 as a pointer to the lower bound of the stack (__fc_limit__).
@@ -147,23 +147,23 @@
         int main( int argc, char * argv[])
         {
             ctx::stack_allocator alloc;
-            
+
             fc1.fc_stack.base = alloc.allocate(ctx::minimum_stacksize());
             fc1.fc_stack.limit =
                 static_cast< char * >( fc1.fc_stack.base) - ctx::minimum_stacksize();
             fc1.fc_link = & fcm;
             pair_t p( std::make_pair( 2, 7) );
             ctx::make_fcontext( & fc1, f1);
-            
+
             int res = ( int) ctx::jump_fcontext( & fcm, & fc1, ( intptr_t) & p);
             std::cout << p.first << " + " << p.second << " == " << res << std::endl;
-            
+
             p = std::make_pair( 5, 6);
             res = ( int) ctx::jump_fcontext( & fcm, & fc1, ( intptr_t) & p);
             std::cout << p.first << " + " << p.second << " == " << res << std::endl;
-            
+
             std::cout << "main: done" << std::endl;
-            
+
             return EXIT_SUCCESS;
         }
 
@@ -218,18 +218,14 @@
 [[Member:] [Tracks the memory for the context's stack.]]
 ]
 
-[heading `fc_link`]
-[variablelist
-[[Member:] [The address of the next context link in a chain, if any.]]
-]
-
-[heading `intptr_t jump_fcontext( fcontext_t * ofc, fcontext_t * nfc, intptr_t p)`]
+[heading `intptr_t jump_fcontext( fcontext_t * ofc, fcontext_t * nfc, intptr_t p, bool preserve_fpu)`]
 [variablelist
 [[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 intptr_t argument, `p`,
 is passed to the current context to be returned by the most recent call to
-`jump_fcontext()` in the same thread.]]
+`jump_fcontext()` in the same thread. The last argument controls if fpu registers
+have to be preserved.]]
 [[Returns:] [The third pointer argument passed to the most recent call to
 `jump_fcontext()`, if any.]]
 ]

Modified: trunk/libs/context/doc/overview.qbk
==============================================================================
--- trunk/libs/context/doc/overview.qbk	(original)
+++ trunk/libs/context/doc/overview.qbk	2012-04-24 11:49:11 EDT (Tue, 24 Apr 2012)
@@ -25,8 +25,8 @@
 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
+kernel), which can cost more than thousand CPU cycles on x86 CPUs. By contrast,
+transferring control among them requires only fewer than hundred CPU cycles because
 it does not involve system calls as it is done within a single thread.
 
 In order to use the classes and functions described here, you can either include

Modified: trunk/libs/context/doc/performance.qbk
==============================================================================
--- trunk/libs/context/doc/performance.qbk	(original)
+++ trunk/libs/context/doc/performance.qbk	2012-04-24 11:49:11 EDT (Tue, 24 Apr 2012)
@@ -12,7 +12,7 @@
 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'.
+'variant = release cxxflags = -DBOOST_DISABLE_ASSERTS'.
 
 The numbers in the table are the number of cycles per iteration, based upon an
 average computed over 256 iterations.
@@ -27,11 +27,11 @@
         [43 cycles]
     ]
     [
-        [Intel Core2 Quad (64bit Linux)]
-        [1739 cycles]
-        [117 cycles]
-        [117 cycles]
-        [117 cycles]
+        [Intel Core2 Q6700 (64bit Linux)]
+        [1472 cycles]
+        [172 cycles]
+        [63 cycles]
+        [60 cycles]
     ]
 ]
 

Modified: trunk/libs/context/doc/rationale.qbk
==============================================================================
--- trunk/libs/context/doc/rationale.qbk	(original)
+++ trunk/libs/context/doc/rationale.qbk	2012-04-24 11:49:11 EDT (Tue, 24 Apr 2012)
@@ -15,18 +15,6 @@
 'Inline Assembler']].
 
 
-[heading Protecting the stack]
-
-Because the stack's size is fixed -- there is no support for split stacks yet -- 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.
-
-
 [heading fcontext_t]
 
 __boost_context__ provides the low level API fcontext_t which is
@@ -36,11 +24,23 @@
 [note Context switches do not preserve the signal mask on UNIX systems.]
 
 Because the assembler code uses the byte layout of __fcontext__ to access 
-its members __fcontext_t must be a POD. This requires that __fcontext__ has only a
+its members __fcontext__ must be a POD. This requires that __fcontext__ has only a
 default constructor, no visibility keywords (e.g. private, public, protected), no
 virtual methods and all members and base clases are PODs too.
 
 
+[heading Protecting the stack]
+
+Because the stack's size is fixed -- there is no support for split stacks yet -- 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.
+
+
 [section Other APIs ]
 
 [heading setjmp()/longjmp()]

Modified: trunk/libs/context/doc/requirements.qbk
==============================================================================
--- trunk/libs/context/doc/requirements.qbk	(original)
+++ trunk/libs/context/doc/requirements.qbk	2012-04-24 11:49:11 EDT (Tue, 24 Apr 2012)
@@ -12,7 +12,7 @@
 therefore, requires GNU AS for supported POSIX systems, and MASM for Windows
 systems.
 
-[important Please note that address-model=64 must be given to bjam comand line
+[important Please note that address-model=64 must be given to bjam command line
 on 64bit Windows (boost-build issue).]
 
 [endsect]