added documentation for the extensions

doc/Jamfile.jam

@@ -11,6 +11,11 @@ using boostbook ;
 using quickbook ;
 using doxygen ;
 
+
+local images = [ glob images/*.svg ] ;
+install images : $(images) : <location>html/boost_process ;
+install images_glob : $(images) : <location>../../../doc/html/boost_process ;         
+
 doxygen autodoc
 :
   ../../../boost/process.hpp
@@ -19,6 +24,8 @@ doxygen autodoc
   <doxygen:param>PREDEFINED=BOOST_PROCESS_DOXYGEN
   <doxygen:param>HIDE_UNDOC_CLASSES=YES
   <doxygen:param>HIDE_UNDOC_MEMBERS=YES
+  <doxygen:param>EXAMPLE_PATH=.
+  <xsl:path>.
 ;
 
 boostbook standalone
@@ -26,6 +33,7 @@ boostbook standalone
   process.qbk
 :
   <dependency>autodoc
+  <dependency>images 
   <xsl:param>boost.root=../../../..
   <xsl:param>html.stylesheet=../../../../doc/src/boostbook.css
 ;

doc/extend.qbk

@@ -1,3 +1,211 @@
-[section:extend Extending the Library]
+[def __on_exit__ [globalref boost::process::on_exit on_exit]]
+[def __on_success__ [globalref boost::process::extend::on_success ex::on_success]]
+[def __child__ [classref boost::process::child child]]
+[def __handler__ [classref boost::process::extend::handler handler]]
+[def __on_success__ [memberref boost::process::extend::handler::on_success on_success]]
+[def __posix_executor__ [classref boost::process::extend::posix_executor ex::posix_executor]]
+[def __windows_executor__ [classref boost::process::extend::windows_executor ex::windows_executor]]
+[def io_service  [@http://www.boost.org/doc/libs/release/doc/html/boost_asio/reference/io_service.html boost::asio::io_service]]
+[def __require_io_service__ [globalref boost::process::extend::require_io_service ex::require_io_service]]
+[def __async_handler__ [globalref boost::process::extend::async_handler ex::async_handler]]
+[def __get_io_service__ [funcref boost::process::extend::get_io_service ex::get_io_service]]
+
+[section:extend Extensions]
+To extend the library, the header [headerref boost/process/extend.hpp extend] is provided.
+
+It only provides the explicit style for custom properties, but no implicit style.
+
+What this means is, that a custom initializer can be implemented, a reference to which can be passed to one of the launching functions.
+If a class inherits [classref boost::process::extend::handler] it will be regarded as a initializer and thus directly put into the sequence 
+the executor gets passed.
+
+[section:structure Structure]
+
+The executor calls different handlers of the initializers during the process launch. 
+The basic structure is consists of three functions, as given below:
+
+* [globalref boost::process::extend::on_setup on_setup]
+* [globalref boost::process::extend::on_error on_error]
+* [globalref boost::process::extend::on_success on_success]
+
+'''
+<imagedata fileref="boost_process/windows_exec.svg"/>
+'''
+
+Additionally posix provides three more handlers, listed below:
+
+* [globalref boost::process::extend::on_fork_error on_fork_error]
+* [globalref boost::process::extend::on_exec_setup on_exec_setup]
+* [globalref boost::process::extend::on_exec_error on_exec_error] 
+
+For more information see the reference of [classref boost::process::extend::posix_executor posix_executor]. 
+
+[endsect]
+[section:simple Simple extensions]
+
+The simplest extension just takes a single handler, which can be done in a functional style.
+So let's start with a simple hello-world example, while we use a C++14 generic lambda.
+
+```
+using namespace boost::process;
+namespace ex = bp::extend;
+
+__child__ c("foo", ex::__on_success__=[](auto & exec) {std::cout << "hello world" << std::endl;});
+```
+
+Considering that lambda can also capture values, data can easily be shared between handlers. 
+
+To see which members the executor has, refer to [classref boost::process::extend::windows_executor windows_executor]
+and [classref boost::process::extend::posix_executor posix_executor].
+
+[note Combined with __on_exit__ this can also handle the process exit.]
+
+[caution The posix handler symbols are not defined on windows.]
+
+[endsect]
+
+[section:handler Handler Types]
+
+Since the previous example is in a functional style, it is not very reusable. 
+To solve that problem, the [classref boost::process::extend::handler handler] has an alias in the `boost::process::extend` namespace, to be inherited.
+So let's implement the hello world example in a class.
+
+```
+struct hello_world : __handler__
+{
+    template<typename Executor>
+    void __on_success__(Executor & exec) const
+    {
+        std::cout << "hello world" << std::endl;
+    }
+};
+
+//in our function
+__child__ c("foo", hello_world()); 
+```
+
+[note The implementation is done via overloading, not overriding.]
+
+Every handler not implemented dafaults to [classref boost::process::extend::handler handler], where an empty handler is defined for each event.
+
+[endsect]
+
+
+
+[section:async Asynchronous Functionality]
+
+Since `boost.process` provides an interface for [@http://www.boost.org/doc/libs/release/libs/asio/ boost.asio], 
+this functionality is also available for extensions. If the class needs the io_service for some reason, the following code will do that.
+
+```
+struct async_foo : __handler__, __require_io_service__ 
+{
+    tempalte<typename Executor>
+    void on_setup(Executor & exec)
+    {
+        __io_service__ & ios = __get_io_service__(exec.seq); //gives us a reference and a compiler error if not present.
+        //do something with ios
+    }
+};
+```
+
+[note Inheriting [globalref boost::process::extend::require_io_service require_io_service] is necessary, so [funcref boost::process::system system] provides one.]
+
+Additionally the handler can provide a function that is invoked when the child process exits. This is done through __async_handler__.
+
+[note [globalref boost::process::extend::async_handler async_handler] implies [globalref boost::process::extend::require_io_service require_io_service] .]
+
+```
+struct async_bar : __handler, __async_handler__
+{
+    template<typename Executor>
+    std::function<void(int, const std::error_code&)> on_exit_handler(Executor & exec)
+    {
+        auto handler = this->handler;
+        return [handler](int exit_code, const std::error_code & ec)
+               {
+                   std::cout << "hello world, I exited with " << exit_code << std::endl; 
+               };
+    
+    }
+}; 
+```
+
+
+[caution `on_exit_handler` does not default and is always required when [classref boost::process::extend::async_handler async_handler] is inherited. ]
+
+[endsect]
+
+[section:error Error handling]
+
+If an error occurs in the initializers it shall be told to the executor and not handles directly. This is because
+the behaviour can be changed through arguments passed to the launching function. Hence the the executor
+has the function `set_error`, which takes an [@http://en.cppreference.com/w/cpp/error/error_code std::error_code] and a string.
+Depending on the cofiguration of the executor, this may either throw, set an internal `error_code`, or do nothing.
+
+So let's take a simple example, where we set a randomly chosen `error_code`.
+
+```
+auto set_error = [](auto & exec)
+        {
+            std::error_code ec{42, std::system_category()};
+            exec.set_error(ec, "a fake error");
+            
+        };
+__child__ c("foo", on_setup=set_error);
+```
+
+Since we do not specify the error-handling mode in this example, this will throw [classref boost::process::process_error process_error]. 
+
+[endsect]
+
+[section:exec_over Executor Overloading]
+
+Now that we have a custom initializer, let's consider how we can handle differences between different executors.
+The distinction is between posix and windows and `char` and `wchar_t` on windows. 
+One solution is to use the [@http://www.boost.org/doc/libs/master/boost/system/api_config.hpp BOOST_WINDOWS_API and BOOST_POSIX_API] macros,
+which are automatically available as soon as any process-header is included.
+
+Another variant are the type aliases __posix_executor__ and __windows_executor__, where the executor, not on the current system is a forward-declaration.
+This works fine, because the function will never get invoked. So let's implement another example, which prints the executable name __on_success__.
+
+```
+struct hello_exe : __handler__
+{
+    template<typename Sequence>
+    void __on_success__(__posix_executor__<Sequence> & exec)
+    {
+        std::cout << "posix-exe: " << exec.exe << std::endl;
+    }
+    
+    template<typename Sequence>
+    void __on_success__(__windows_executor__<char, Sequence> & exec)
+    {
+        //note: exe might be a nullptr on windows.
+        if (exec.exe != nullptr)
+            std::cout << "windows-exe: " << exec.exe << std::endl;
+        else
+            std::cout << "windows didn't use exe" << std::endl;
+    }
+    
+    template<typename Sequence>
+    void __on_success__(__windows_executor__<wchar_t, Sequence> & exec)
+    {
+        //note: exe might be a nullptr on windows.
+        if (exec.exe != nullptr)
+            std::wcout << L"windows-exe: " << exec.exe << std::endl;
+        else
+            std::cout << "windows didn't use exe" << std::endl;
+    }
+    
+};
+```
+
+So given our example, the definitions with the non-native exectur are still a template so that they will not be evaluated if not used. Hence this provides a
+way to implement systems-specific code without using the preprocessor.
+
+[note If you only write a partial implementation, e.g. only for __posix_executor__, the other variants will default to __handler__].
+
+[endsect]
 
 [endsect]

doc/images/plantuml.txt

@@ -0,0 +1,118 @@
+Plantuml source file (for later edit)
+// Style
+
+skinparam backgroundColor #FFFFFF
+
+skinparam sequence {
+    ActorBorderColor DeepSkyBlue
+    ArrowColor #4a6484
+    
+    LifeLineBorderColor #4a6484
+    ParticipantBackgroundColor  #91c6ff
+    ParticipantBorderColor black
+    BoxBorderColor black
+}
+
+
+//posix no error
+/**
+\plantuml
+activate Father 
+
+box "Child Process" #LightGrey
+    participant Child
+    participant Exe
+end box
+
+Father->Father : on_setup
+activate Father
+deactivate Father
+Father->Child : fork
+activate Child 
+Father -> Father : wait for error
+deactivate Father
+
+
+Child->Child : on_exec_setup
+activate Child
+deactivate Child
+Child->Exe : execve
+deactivate Child
+activate Father
+activate Exe 
+
+Father -> Father : on_success 
+activate Father
+deactivate Father
+
+\endplantuml */
+
+//posix exec error
+/**
+\plantuml
+activate Father 
+
+Father->Father : on_setup
+activate Father
+deactivate Father
+Father->Child : fork
+activate Child 
+Father -> Father : wait for error
+deactivate Father
+
+Child->Child : on_exec_setup
+activate Child
+deactivate Child
+Child->Child : execve
+Child->Child : on_exec_error
+activate Child
+deactivate Child
+Child->Father : report
+deactivate Child
+activate Father 
+Father -> Father : on_error
+activate Father
+deactivate Father
+\endplantuml 
+
+//posix fork error
+\plantuml
+activate Father 
+
+Father->Father : on_setup
+activate Father
+deactivate Father
+Father->Father : fork
+Father -> Father : on_fork_error
+activate Father
+deactivate Father
+Father -> Father : on_error
+activate Father
+deactivate Father
+\endplantuml
+
+
+//windows.
+\plantuml
+activate Father 
+
+Father->Father : on_setup
+activate Father
+deactivate Father
+Father->Child : CreateProcess
+activate Child
+
+alt Successful Launch
+
+Father -> Father : on_success
+activate Father
+deactivate Father
+
+else Error during launch
+
+Father -> Father : on_error
+activate Father
+deactivate Father
+
+end
+\endplantuml

doc/images/posix_fork_err.svg

@@ -0,0 +1 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" contentScriptType="application/ecmascript" contentStyleType="text/css" height="355px" preserveAspectRatio="none" style="width:142px;height:355px;" version="1.1" viewBox="0 0 142 355" width="142px" zoomAndPan="magnify"><defs><filter height="300%" id="f7wjnsf" width="300%" x="-1" y="-1"><feGaussianBlur result="blurOut" stdDeviation="2.0"/><feColorMatrix in="blurOut" result="blurOut2" type="matrix" values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 .4 0"/><feOffset dx="4.0" dy="4.0" in="blurOut2" result="blurOut3"/><feBlend in="SourceGraphic" in2="blurOut3" mode="normal"/></filter></defs><g><rect fill="#FFFFFF" filter="url(#f7wjnsf)" height="259.5313" style="stroke: #4A6484; stroke-width: 1.0;" width="10" x="34" y="48.2969"/><rect fill="#FFFFFF" filter="url(#f7wjnsf)" height="28" style="stroke: #4A6484; stroke-width: 1.0;" width="10" x="39" y="77.2969"/><rect fill="#FFFFFF" filter="url(#f7wjnsf)" height="28" style="stroke: #4A6484; stroke-width: 1.0;" width="10" x="39" y="191.5625"/><rect fill="#FFFFFF" filter="url(#f7wjnsf)" height="28" style="stroke: #4A6484; stroke-width: 1.0;" width="10" x="39" y="263.6953"/><line style="stroke: #4A6484; stroke-width: 1.0; stroke-dasharray: 5.0,5.0;" x1="39" x2="39" y1="38.2969" y2="316.8281"/><rect fill="#91C6FF" filter="url(#f7wjnsf)" height="30.2969" style="stroke: #000000; stroke-width: 1.5;" width="58" x="8" y="3"/><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacingAndGlyphs" textLength="44" x="15" y="22.9951">Father</text><rect fill="#91C6FF" filter="url(#f7wjnsf)" height="30.2969" style="stroke: #000000; stroke-width: 1.5;" width="58" x="8" y="315.8281"/><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacingAndGlyphs" textLength="44" x="15" y="335.8232">Father</text><rect fill="#FFFFFF" filter="url(#f7wjnsf)" height="259.5313" style="stroke: #4A6484; stroke-width: 1.0;" width="10" x="34" y="48.2969"/><rect fill="#FFFFFF" filter="url(#f7wjnsf)" height="28" style="stroke: #4A6484; stroke-width: 1.0;" width="10" x="39" y="77.2969"/><rect fill="#FFFFFF" filter="url(#f7wjnsf)" height="28" style="stroke: #4A6484; stroke-width: 1.0;" width="10" x="39" y="191.5625"/><rect fill="#FFFFFF" filter="url(#f7wjnsf)" height="28" style="stroke: #4A6484; stroke-width: 1.0;" width="10" x="39" y="263.6953"/><line style="stroke: #4A6484; stroke-width: 1.0;" x1="49" x2="91" y1="69.4297" y2="69.4297"/><line style="stroke: #4A6484; stroke-width: 1.0;" x1="91" x2="91" y1="69.4297" y2="82.4297"/><line style="stroke: #4A6484; stroke-width: 1.0;" x1="50" x2="91" y1="82.4297" y2="82.4297"/><polygon fill="#4A6484" points="60,78.4297,50,82.4297,60,86.4297,56,82.4297" style="stroke: #4A6484; stroke-width: 1.0;"/><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacingAndGlyphs" textLength="59" x="56" y="64.3638">on_setup</text><line style="stroke: #4A6484; stroke-width: 1.0;" x1="44" x2="86" y1="141.5625" y2="141.5625"/><line style="stroke: #4A6484; stroke-width: 1.0;" x1="86" x2="86" y1="141.5625" y2="154.5625"/><line style="stroke: #4A6484; stroke-width: 1.0;" x1="45" x2="86" y1="154.5625" y2="154.5625"/><polygon fill="#4A6484" points="55,150.5625,45,154.5625,55,158.5625,51,154.5625" style="stroke: #4A6484; stroke-width: 1.0;"/><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacingAndGlyphs" textLength="24" x="51" y="136.4966">fork</text><line style="stroke: #4A6484; stroke-width: 1.0;" x1="49" x2="91" y1="183.6953" y2="183.6953"/><line style="stroke: #4A6484; stroke-width: 1.0;" x1="91" x2="91" y1="183.6953" y2="196.6953"/><line style="stroke: #4A6484; stroke-width: 1.0;" x1="50" x2="91" y1="196.6953" y2="196.6953"/><polygon fill="#4A6484" points="60,192.6953,50,196.6953,60,200.6953,56,196.6953" style="stroke: #4A6484; stroke-width: 1.0;"/><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacingAndGlyphs" textLength="85" x="56" y="178.6294">on_fork_error</text><line style="stroke: #4A6484; stroke-width: 1.0;" x1="49" x2="91" y1="255.8281" y2="255.8281"/><line style="stroke: #4A6484; stroke-width: 1.0;" x1="91" x2="91" y1="255.8281" y2="268.8281"/><line style="stroke: #4A6484; stroke-width: 1.0;" x1="50" x2="91" y1="268.8281" y2="268.8281"/><polygon fill="#4A6484" points="60,264.8281,50,268.8281,60,272.8281,56,268.8281" style="stroke: #4A6484; stroke-width: 1.0;"/><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacingAndGlyphs" textLength="54" x="56" y="250.7622">on_error</text></g></svg>

doc/introduction.qbk

@@ -19,6 +19,4 @@ Here's a simple example of how to start a program with Boost.Process:
 [import ../example/intro.cpp]
 [intro]
 
-[caution This is not yet an official Boost C++ library. It wasn't reviewed and can't be downloaded from [@http://www.boost.org/ www.boost.org]. It is however the latest version of an ongoing effort to create a process management library for Boost. For now the library can be downloaded or cloned from here [@https://github.com/klemens-morgenstern/boost-process/tree/develop https://github.com/klemens-morgenstern/boost-process/tree/develop].]
-
 [endsect]

doc/posix_pseudocode.xml

@@ -13,7 +13,7 @@ if (<methodname alt="boost::process::extend::posix_executor::error">error</metho
 pid = <ulink url="http://pubs.opengroup.org/onlinepubs/009695399/functions/fork.html">fork()</ulink>
 <methodname alt="boost::process::extend::handler::on_setup">on_setup</methodname>(*this);
 
-if (pid == -1) //fork error
+if (pid == -1) //fork error 
 {
     <methodname alt="boost::process::extend::posix_executor::set_error">set_error</methodname>(<functionname alt="boost::process::extend::get_last_error">get_last_error</functionname>());
     for (auto &amp; s : seq)
@@ -37,7 +37,7 @@ else if (pid == 0) //child process
     return <classname alt="boost::process::child">child</classname>(); //for C++ compliance
 }
 
-<classname alt="boost::process::child">child</classname>(pid, exit_code);
+<classname alt="boost::process::child">child</classname> c(pid, exit_code);
 
 <emphasis>unspecified();</emphasis>//here, we read the the error from the child process
 
@@ -50,7 +50,11 @@ else
 
 //now we check again, because a on_success handler might've errored.
 if (<methodname alt="boost::process::extend::posix_executor::error">error</methodname>())
+{
     for (auto &amp; s : seq)
         s.<methodname alt="boost::process::extend::handler::on_error">on_error</methodname>(*this, <methodname alt="boost::process::extend::posix_executor::error">error</methodname>());
-
+    return <classname alt="boost::process::child">child</classname>();
+}
+else
+    return c;
 </programlisting>

doc/tutorial.qbk

@@ -25,11 +25,9 @@
 [def bp::native_environment  [classref boost::process::basic_native_environment bp::native_environment]]
 [def boost::this_process::environment [funcref boost::this_process::environment boost::this_process::environment]]
 
-
-[def __wait_for__  [memberref boost::process::child::wait_for wait_for]]
-[def __wait_until__  [memberref boost::process::child::wait_until wait_until]]
-[def __detach__  [memberref boost::process::child::detach detach]]
-
+[def __wait_for__ [memberref boost::process::child::wait_for wait_for]]
+[def __wait_until__ [memberref boost::process::child::wait_until wait_until]]
+[def __detach__ [memberref boost::process::child::detach detach]]
 
 [def __reference__ [link process.reference reference]]
 

doc/windows_pseudocode.xml

@@ -0,0 +1,42 @@
+<?xml version="1.0" standalone="yes"?>
+<programlisting>
+for (auto &amp; s : seq)
+    s.<methodname alt="boost::process::extend::handler::on_setup">on_setup</methodname>(*this);
+
+if (<methodname alt="boost::process::extend::windows_executor::error">error</methodname>())
+{
+    for (auto &amp; s : seq)
+       s.<methodname alt="boost::process::extend::handler::on_error">on_error</methodname>(*this, <methodname alt="boost::process::extend::windows_executor::error">error</methodname>());
+    return <classname alt="boost::process::child">child</classname>();
+}
+int err_code = <ulink url="https://msdn.microsoft.com/en-us/library/windows/desktop/ms682425.aspx">CreateProcess</ulink>(
+         exe,
+         cmd_line,
+         proc_attrs,
+         thread_attrs,
+         creation_flags,
+         env,
+         work_dir,
+         startup_info,
+         proc_info);
+
+<classname alt="boost::process::child">child</classname> c(proc_info, exit_code);
+
+if (<methodname alt="boost::process::extend::windows_executor::error">error</methodname>())
+    for (auto &amp; s : seq)
+        s.<methodname alt="boost::process::extend::handler::on_error">on_error</methodname>(*this, <methodname alt="boost::process::extend::windows_executor::error">error</methodname>());
+else
+    for (auto &amp; s : seq)
+        s.<methodname alt="boost::process::extend::handler::on_error">on_success</methodname>(*this);
+
+//now we check again, because a on_success handler might've errored.
+if (<methodname alt="boost::process::extend::windows_executor::error">error</methodname>())
+{
+    for (auto &amp; s : seq)
+        s.<methodname alt="boost::process::extend::handler::on_error">on_error</methodname>(*this, <methodname alt="boost::process::extend::windows_executor::error">error</methodname>());
+    return <classname alt="boost::process::child">child</classname>();
+}
+else
+    return c;
+
+</programlisting>

include/boost/process/detail/windows/env_init.hpp

@@ -28,7 +28,7 @@ struct env_init : public ::boost::process::detail::handler_base
     constexpr static ::boost::detail::winapi::DWORD_ creation_flag(char)    {return 0u;}
     constexpr static ::boost::detail::winapi::DWORD_ creation_flag(wchar_t)
     {
-    	return ::boost::detail::winapi::CREATE_UNICODE_ENVIRONMENT_;
+       return ::boost::detail::winapi::CREATE_UNICODE_ENVIRONMENT_;
     }
 
     template <class WindowsExecutor>

include/boost/process/detail/windows/executor.hpp

@@ -83,8 +83,8 @@ struct startup_info_impl
 
     void set_startup_info_ex()
     {
-    	startup_info.cb = sizeof(startup_info_ex_t);
-    	creation_flags  = ::boost::detail::winapi::EXTENDED_STARTUPINFO_PRESENT_;
+       startup_info.cb = sizeof(startup_info_ex_t);
+       creation_flags  = ::boost::detail::winapi::EXTENDED_STARTUPINFO_PRESENT_;
     }
 };
 

include/boost/process/extend.hpp

@@ -11,9 +11,11 @@
 #if defined(BOOST_WINDOWS_API)
 #include <boost/process/detail/windows/executor.hpp>
 #include <boost/process/detail/windows/async_handler.hpp>
+#include <boost/process/detail/windows/asio_fwd.hpp>
 #else
 #include <boost/process/detail/posix/executor.hpp>
 #include <boost/process/detail/posix/async_handler.hpp>
+#include <boost/process/detail/posix/asio_fwd.hpp>
 #endif
 
 
@@ -29,10 +31,6 @@
 
 namespace boost {
 namespace process {
-namespace asio {
-class io_service;
-}
-
 namespace detail {
 template<typename Tuple>
 inline asio::io_service& get_io_service(const Tuple & tup);
@@ -52,7 +50,7 @@ struct posix_executor;
 #elif defined(BOOST_POSIX_API)
 
 template<typename Sequence>
-using posix_executor = ::boost::process::detail::posix::executor<Args...>;
+using posix_executor = ::boost::process::detail::posix::executor<Sequence>;
 template<typename Char, typename Sequence>
 struct windows_executor;
 
@@ -65,20 +63,20 @@ using ::boost::process::detail::get_io_service;
 using ::boost::process::detail::get_last_error;
 using ::boost::process::detail::throw_last_error;
 
-///This handler is invoked before the process in launched, to setup parameters.
+///This handler is invoked before the process in launched, to setup parameters. The required signature is `void(Exec &)`, where `Exec` is a template parameter.
 constexpr boost::process::detail::make_handler_t<boost::process::detail::on_setup_>   on_setup;
-///This handler is invoked if an error occured.
+///This handler is invoked if an error occured. The required signature is `void(auto & exec, const std::error_code&)`, where `Exec` is a template parameter.
 constexpr boost::process::detail::make_handler_t<boost::process::detail::on_error_>   on_error;
-///This handler is invoked if launching the process has succeeded.
+///This handler is invoked if launching the process has succeeded. The required signature is `void(auto & exec)`, where `Exec` is a template parameter.
 constexpr boost::process::detail::make_handler_t<boost::process::detail::on_success_> on_success;
 
 #if defined(BOOST_POSIX_API) || defined(BOOST_PROCESS_DOXYGEN)
-///This handler is invoked if the fork failed. \note Only available on posix.
+///This handler is invoked if the fork failed. The required signature is `void(auto & exec)`, where `Exec` is a template parameter. \note Only available on posix.
 constexpr ::boost::process::detail::make_handler_t<::boost::process::detail::posix::on_fork_error_  >   on_fork_error;
-///This handler is invoked if the fork succeeded. \note Only available on posix.
+///This handler is invoked if the fork succeeded. The required signature is `void(Exec &)`, where `Exec` is a template parameter. \note Only available on posix.
 constexpr ::boost::process::detail::make_handler_t<::boost::process::detail::posix::on_exec_setup_  >   on_exec_setup;
-///This handler is invoked if the exec call errored. \note Only available on posix.
-constexpr ::boost::process::detail::make_handler_t<::boost::process::detail::posix::on_exec_error_     >   on_exec_error;
+///This handler is invoked if the exec call errored. The required signature is `void(auto & exec)`, where `Exec` is a template parameter. \note Only available on posix.
+constexpr ::boost::process::detail::make_handler_t<::boost::process::detail::posix::on_exec_error_  >   on_exec_error;
 #endif
 
 #if defined(BOOST_PROCESS_DOXYGEN)
@@ -164,15 +162,7 @@ struct require_io_service {};
  *
  \code{.cpp}
 template<typename Executor>
-std::function<void(int, const std::error_code&)> on_exit_handler(Executor & exec)
-{
-    auto handler = this->handler;
-    return [handler](int exit_code, const std::error_code & ec)
-           {
-                handler(static_cast<int>(exit_code), ec);
-           };
-
-}
+std::function<void(int, const std::error_code&)> on_exit_handler(Executor & exec);
  \endcode
 
  The callback will be obtained by calling this function on setup and it will be
@@ -191,17 +181,25 @@ struct async_handler : handler, require_io_service
  * \note It is an alias for the implementation on posix, and a forward-declaration on windows.
  *
  * \tparam Sequence The used initializer-sequence, it is fulfills the boost.fusion [sequence](http://www.boost.org/doc/libs/master/libs/fusion/doc/html/fusion/sequence.html) concept.
- *
+
+
 \xmlonly
-The basic structure of the invocation is given below (in pseudo-code).
+As information for extension development, here is the structure of the process launching (in pseudo-code and uml)
+<xi:include href="posix_pseudocode.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
 
-<xi:include
-     href="/boost/libs/process/doc/posix_pseudocode.xml"
-     xmlns:xi="http://www.w3.org/2001/XInclude" />
+<para>The sequence if when no error occurs.</para>
+<imagedata fileref="boost_process/posix_success.svg"/>
 
+<para>The sequence if the execution fails.</para>
+<imagedata fileref="boost_process/posix_exec_err.svg"/>
+
+<para>The sequence if the fork fails.</para>
+<imagedata fileref="boost_process/posix_fork_err.svg"/>
 \endxmlonly
- *
- * \note Error handling is done through a pipe, unless \ref ignore_error is used.
+
+
+\note Error handling if execve fails is done through a pipe, unless \ref ignore_error is used.
+
  */
 template<typename Sequence>
 struct posix_executor
@@ -236,7 +234,14 @@ struct posix_executor
  * \tparam Sequence The used initializer-sequence, it is fulfills the boost.fusion [sequence](http://www.boost.org/doc/libs/master/libs/fusion/doc/html/fusion/sequence.html) concept.
  * \tparam Char The used char-type, either `char` or `wchar_t`.
  *
- *
+
+\xmlonly
+As information for extension development, here is the structure of the process launching (in pseudo-code and uml)
+<xi:include href="windows_pseudocode.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
+<para>The sequence for windows process creation.</para>
+<imagedata fileref="boost_process/windows_exec.svg"/>
+\endxmlonly
+
  */
 
 template<typename Char, typename Sequence>

test/extensions.cpp

@@ -70,8 +70,8 @@ std::string st = "not called";
 
 struct overload_handler : ex::handler
 {
-    template <class ...Args>
-    void on_setup(ex::windows_executor<Args...>& exec) const
+    template <class Char, class Sequence>
+    void on_setup(ex::windows_executor<Char, Sequence>& exec) const
     {
     	st = "windows";
     	const char* env = exec.env;