1 files changed, 42 insertions, 0 deletions
diff --git a/libs/context/doc/overview.qbk b/libs/context/doc/overview.qbk
new file mode 100644
index 0000000000..d08381f635
--- /dev/null
+++ b/libs/context/doc/overview.qbk
@@ -0,0 +1,42 @@
+[/
+          Copyright Oliver Kowalke 2009.
+ 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
+]
+
+[section:overview Overview]
+
+__boost_context__ is a foundational library that provides a sort of cooperative
+multitasking on a single thread. 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 __fcontext__ instance represents a specific point in the application's
+execution path. This is useful for building higher-level abstractions, like
+__coroutines__, __coop_threads__ or an aquivalent to
+[@http://msdn.microsoft.com/en-us/library/9k7k7cf0%28v=vs.80%29.aspx C# keyword __yield__]
+in C++.
+
+A __fcontext__ provides the means to suspend the current execution path and to
+transfer execution control, thereby permitting another __fcontext__ to run on the
+current thread. This stateful transfer mechanism enables a __fcontext__ to
+suspend execution from within nested functions and, later, to resume from where
+it was suspended. While the execution path represented by a __fcontext__ 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 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
+the specific headers specified by the descriptions of each class or function, or
+include the master library header:
+
+    #include <boost/context/all.hpp>
+
+which includes all the other headers in turn.
+
+All functions and classes are contained in the namespace __context_ns__.
+
+[endsect]