ceph/src/boost/libs/context/doc/overview.qbk

   1 [/
   2           Copyright Oliver Kowalke 2014.
   3  Distributed under the Boost Software License, Version 1.0.
   4     (See accompanying file LICENSE_1_0.txt or copy at
   5           http://www.boost.org/LICENSE_1_0.txt
   6 ]
   7
   8 [section:overview Overview]
   9
  10 __boost_context__ is a foundational library that provides a sort of cooperative
  11 multitasking on a single thread. By providing an abstraction of the current
  12 execution state in the current thread, including the stack (with local
  13 variables) and stack pointer, all registers and CPU flags, and the instruction
  14 pointer, a __econtext__ represents a specific point in the application's
  15 execution path. This is useful for building higher-level abstractions, like
  16 __coroutines__, __coop_threads__ or an equivalent to
  17 [@http://msdn.microsoft.com/en-us/library/9k7k7cf0%28v=vs.80%29.aspx C# keyword __yield__]
  18 in C++.
  19
  20 __econtext__ provides the means to suspend the current execution path and to
  21 transfer execution control, thereby permitting another context to run on the
  22 current thread. This state full transfer mechanism enables a context to suspend
  23 execution from within nested functions and, later, to resume from where it was
  24 suspended. While the execution path represented by a __econtext__ only runs on a
  25 single thread, it can be migrated to another thread at any given time.
  26
  27 A context switch between threads requires system calls (involving the OS
  28 kernel), which can cost more than thousand CPU cycles on x86 CPUs. By contrast,
  29 transferring control among them requires only few CPU cycles because it does not
  30 involve system calls as it is done within a single thread.
  31
  32 In order to use the classes and functions described here, you can either include
  33 the specific headers specified by the descriptions of each class or function, or
  34 include the master library header:
  35
  36     #include <boost/context/all.hpp>
  37
  38 which includes all the other headers in turn.
  39
  40 All functions and classes are contained in the namespace __context_ns__.
  41
  42 [note This library requires C++11!]
  43
  44 [endsect]