boost-react-native-bundle

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> <html> <head> <meta http-equiv="Content-Language" content="en-us"> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="GENERATOR" content="Microsoft FrontPage 12.0"> <meta name="ProgId" content="FrontPage.Editor.Document"> <link rel="stylesheet" type="text/css" href="../../../boost.css"> <title>The Boost Statechart Library - Reference</title> <style type="text/css"> .style1 { width: 45%; } </style> </head> <body link="#0000FF" vlink="#800080"> <table border="0" cellpadding="7" cellspacing="0" width="100%" summary= "header"> <tr> <td valign="top" width="300"> <h3><a href="../../../index.htm"><img alt="C++ Boost" src= "../../../boost.png" border="0" width="277" height="86"></a></h3> </td> <td valign="top"> <h1 align="center">The Boost Statechart Library</h1> <h2 align="center">Reference</h2> </td> </tr> </table> <hr> <h2>Contents</h2> <dl class="page-index"> <dt><a href="#Concepts">Concepts</a></dt> <dd><a href="#Scheduler">Scheduler</a></dd> <dd><a href="#FifoWorker">FifoWorker</a></dd> <dd><a href="#ExceptionTranslator">ExceptionTranslator</a></dd> <dd><a href="#StateBase">StateBase</a></dd> <dd><a href="#SimpleState">SimpleState</a></dd> <dd><a href="#State">State</a></dd> <dd><a href="#Event">Event</a></dd> <dt><a href="#state_machine.hpp">state_machine.hpp</a></dt> <dd><a href="#ClassTemplatestate_machine">Class template <code>state_machine</code></a></dd> <dt><a href= "#asynchronous_state_machine.hpp">asynchronous_state_machine.hpp</a></dt> <dd><a href="#ClassTemplateasynchronous_state_machine">Class template <code>asynchronous_state_machine</code></a></dd> <dt><a href="#event_processor.hpp">event_processor.hpp</a></dt> <dd><a href="#ClassTemplateevent_processor">Class template <code>event_processor</code></a></dd> <dt><a href="#fifo_scheduler.hpp">fifo_scheduler.hpp</a></dt> <dd><a href="#ClassTemplatefifo_scheduler">Class template <code>fifo_scheduler</code></a></dd> <dt><a href="#exception_translator.hpp">exception_translator.hpp</a></dt> <dd><a href="#ClassTemplateexception_translator">Class template <code>exception_translator</code></a></dd> <dt><a href= "#null_exception_translator.hpp">null_exception_translator.hpp</a></dt> <dd><a href="#Classnull_exception_translator">Class <code>null_exception_translator</code></a></dd> <dt> </dt> <dt><a href="#simple_state.hpp">simple_state.hpp</a></dt> <dd><a href="#Enumhistory_mode">Enum <code>history_mode</code></a></dd> <dd><a href="#ClassTemplatesimple_state">Class template <code>simple_state</code></a></dd> <dt><a href="#state.hpp">state.hpp</a></dt> <dd><a href="#ClassTemplatestate">Class template <code>state</code></a></dd> <dt><a href="#shallow_history.hpp">shallow_history.hpp</a></dt> <dd><a href="#ClassTemplateshallow_history">Class template <code>shallow_history</code></a></dd> <dt><a href="#deep_history.hpp">deep_history.hpp</a></dt> <dd><a href="#ClassTemplatedeep_history">Class template <code>deep_history</code></a></dd> <dt> </dt> <dt><a href="#event_base.hpp">event_base.hpp</a></dt> <dd><a href="#Classevent_base">Class <code>event_base</code></a></dd> <dt><a href="#event.hpp">event.hpp</a></dt> <dd><a href="#ClassTemplateevent">Class template <code>event</code></a></dd> <dt> </dt> <dt><a href="#transition.hpp">transition.hpp</a></dt> <dd><a href="#ClassTemplatetransition">Class template <code>transition</code></a></dd> <dt><a href="#in_state_reaction.hpp">in_state_reaction.hpp</a></dt> <dd><a href="#ClassTemplatein_state_reaction">Class template in_state_reaction</a></dd> <dt><a href="#termination.hpp">termination.hpp</a></dt> <dd><a href="#ClassTemplatetermination">Class template <code>termination</code></a></dd> <dt><a href="#deferral.hpp">deferral.hpp</a></dt> <dd><a href="#ClassTemplatedeferral">Class template <code>deferral</code></a></dd> <dt><a href="#custom_reaction.hpp">custom_reaction.hpp</a></dt> <dd><a href="#ClassTemplatecustom_reaction">Class template <code>custom_reaction</code></a></dd> <dt><a href="#result.hpp">result.hpp</a></dt> <dd><a href="#Classresult">Class <code>result</code></a></dd> </dl> <hr> <h1><a name="Concepts" id="Concepts">Concepts</a></h1> <h2><a name="Scheduler" id="Scheduler">Scheduler</a> concept</h2> <p>A Scheduler type defines the following:</p> <ul> <li>What is passed to the constructors of <code><a href= "#ClassTemplateevent_processor">event_processor<></a></code> subtypes and how the lifetime of such objects is managed</li> <li>Whether or not multiple <code>event_processor<></code> subtype objects can share the same queue and scheduler thread</li> <li>How events are added to the schedulers' queue</li> <li>Whether and how to wait for new events when the schedulers' queue runs empty</li> <li>Whether and what type of locking is used to ensure thread-safety</li> <li>Whether it is possible to queue events for no longer existing <code>event_processor<></code> subtype objects and what happens when such an event is processed</li> <li>What happens when one of the serviced <code>event_processor<></code> subtype objects propagates an exception</li> </ul> <p>For a Scheduler type <code>S</code> and an object <code>cpc</code> of type <code>const S::processor_context</code> the following expressions must be well-formed and have the indicated results:</p> <table border="3" cellpadding="2" width="100%" summary="Scheduler concept"> <tr> <td><b>Expression</b></td> <td><b>Type</b></td> <td><b>Result</b></td> </tr> <tr> <td><code>cpc.my_scheduler()</code></td> <td><code>S &</code></td> <td>A reference to the scheduler</td> </tr> <tr> <td><code>cpc.my_handle()</code></td> <td><code>S::processor_handle</code></td> <td>The handle identifying the <code>event_processor<></code> subtype object</td> </tr> </table> <p>To protect against abuse, all members of <code>S::processor_context</code> should be declared private. As a result, <code>event_processor<></code> must be a friend of <code>S::processor_context</code>.</p> <h2><a name="FifoWorker" id="FifoWorker">FifoWorker</a> concept</h2> <p>A FifoWorker type defines the following:</p> <ul> <li>Whether and how to wait for new work items when the internal work queue runs empty</li> <li>Whether and what type of locking is used to ensure thread-safety</li> </ul> <p>For a FifoWorker type <code>F</code>, an object <code>f</code> of that type, a <code>const</code> object <code>cf</code> of that type, a parameterless function object <code>w</code> of arbitrary type and an <code>unsigned long</code> value <code>n</code> the following expressions/statements must be well-formed and have the indicated results:</p> <table border="3" cellpadding="2" width="100%" summary= "FifoWorker concept"> <tr> <td><b>Expression/Statement</b></td> <td><b>Type</b></td> <td><b>Effects/Result</b></td> </tr> <tr> <td><code>F::work_item</code></td> <td><code>boost::function0< void ></code></td> <td> </td> </tr> <tr> <td><code>F()</code> or <code>F( false )</code></td> <td><code>F</code></td> <td>Constructs a <b>non-blocking</b> (see below) object of the FifoWorker type. In single-threaded builds the second expression is not well-formed</td> </tr> <tr> <td><code>F( true )</code></td> <td><code>F</code></td> <td>Constructs a <b>blocking</b> (see below) object of the FifoWorker type. Not well-formed in single-threaded builds</td> </tr> <tr> <td><code>f.queue_work_item( w );</code></td> <td> </td> <td>Constructs and queues an object of type <code>F::work_item</code>, passing <code>w</code> as the only argument</td> </tr> <tr> <td><code>f.terminate();</code></td> <td> </td> <td>Creates and queues an object of type <code>F::work_item</code> that, when later executed in <code>operator()()</code>, leads to a modification of internal state so that <code>terminated()</code> henceforth returns <code>true</code></td> </tr> <tr> <td><code>cf.terminated();</code></td> <td><code>bool</code></td> <td><code>true</code> if <code>terminate()</code> has been called and the resulting work item has been executed in <code>operator()()</code>. Returns <code>false</code> otherwise<br> <br> <b>Must only be called from the thread that also calls <code>operator()()</code></b></td> </tr> <tr> <td><code>f( n );</code></td> <td><code>unsigned long</code></td> <td> Enters a loop that, with each cycle, dequeues and calls <code>operator()()</code> on the oldest work item in the queue. <p>The loop is left and the number of executed work items returned if one or more of the following conditions are met:</p> <ul> <li><code>f.terminated() == true</code></li> <li>The application is single-threaded and the internal queue is empty</li> <li>The application is multi-threaded and the internal queue is empty and the worker was created as non-blocking</li> <li><code>n != 0</code> and the number of work items that have been processed since <code>operator()()</code> was called equals <code>n</code></li> </ul> <p>If the queue is empty and none of the above conditions are met then the thread calling <code>operator()()</code> is put into a wait state until <code>f.queue_work_item()</code> is called from another thread.<br> <br> <b>Must only be called from exactly one thread</b></p> </td> </tr> <tr> <td><code>f();</code></td> <td><code>unsigned long</code></td> <td>Has exactly the same semantics as <code>f( n );</code> with <code>n == 0</code> (see above)</td> </tr> </table> <h2><a name="ExceptionTranslator" id= "ExceptionTranslator">ExceptionTranslator</a> concept</h2> <p>An ExceptionTranslator type defines how C++ exceptions occurring during state machine operation are translated to exception events.</p> <p>For an ExceptionTranslator object <code>et</code>, a parameterless function object <code>a</code> of arbitrary type returning <code><a href= "#Classresult">result</a></code> and a function object <code>eh</code> of arbitrary type taking a <code>const <a href= "#Classevent_base">event_base</a> &</code> parameter and returning <code><a href="#Classresult">result</a></code> the following expression must be well-formed and have the indicated results:</p> <table border="3" cellpadding="2" width="100%" summary= "ExceptionTranslator concept"> <tr> <td><b>Expression</b></td> <td><b>Type</b></td> <td><b>Effects/Result</b></td> </tr> <tr> <td><code>et( a, eh );</code></td> <td><code>result</code></td> <td> <ol> <li>Attempts to execute <code>return a();</code></li> <li>If <code>a()</code> propagates an exception, the exception is caught</li> <li>Inside the catch block calls <code>eh</code>, passing a suitable stack-allocated model of the <a href="#Event">Event</a> concept</li> <li>Returns the result returned by <code>eh</code></li> </ol> </td> </tr> </table> <h2><a name="StateBase" id="StateBase">StateBase</a> concept</h2> <p>A StateBase type is the common base of all states of a given state machine type. <code>state_machine<>::state_base_type</code> is a model of the StateBase concept.</p> <p>For a StateBase type <code>S</code> and a <code>const</code> object <code>cs</code> of that type the following expressions must be well-formed and have the indicated results:</p> <table border="3" cellpadding="2" width="100%" summary="StateBase concept"> <tr> <td><b>Expression</b></td> <td><b>Type</b></td> <td><b>Result</b></td> </tr> <tr> <td><code>cs.outer_state_ptr()</code></td> <td><code>const S *</code></td> <td><code>0</code> if <code>cs</code> is an <a href= "definitions.html#OutermostState">outermost state</a>, a pointer to the direct outer state of <code>cs</code> otherwise</td> </tr> <tr> <td><code>cs.dynamic_type()</code></td> <td><code>S::id_type</code></td> <td>A value unambiguously identifying the most-derived type of <code>cs</code>. <code>S::id_type</code> values are comparable with <code>operator==()</code> and <code>operator!=()</code>. An unspecified collating order can be established with <code>std::less< S::id_type ></code>. In contrast to <code>typeid( cs )</code>, this function is available even on platforms that do not support C++ RTTI (or have been configured to not support it)</td> </tr> <tr> <td><code>cs.custom_dynamic_type_ptr<<br>   Type >()</code></td> <td><code>const Type *</code></td> <td>A pointer to the custom type identifier or <code>0</code>. If <code>!= 0</code>, <code>Type</code> must match the type of the previously set pointer. This function is only available if <a href= "configuration.html#ApplicationDefinedMacros">BOOST_STATECHART_USE_NATIVE_RTTI</a> is not defined</td> </tr> </table> <h2><a name="SimpleState" id="SimpleState">SimpleState</a> concept</h2> <p>A SimpleState type defines one state of a particular state machine.</p> <p>For a SimpleState type <code>S</code> and a pointer <code>pS</code> pointing to an object of type <code>S</code> allocated with <code>new</code> the following expressions/statements must be well-formed and have the indicated effects/results:</p> <table border="3" cellpadding="2" width="100%" summary= "SimpleState concept"> <tr> <td><b>Expression/Statement</b></td> <td><b>Type</b></td> <td><b>Effects/Result/Notes</b></td> </tr> <tr> <td><code><a href= "#ClassTemplatesimple_state">simple_state</a><<br>   S, C, I, h > * pB =<br>     pS;</code></td> <td> </td> <td><code>simple_state< S, C, I, h ></code> must be an unambiguous public base of <code>S</code>. See <code><a href= "#ClassTemplatesimple_state">simple_state<></a></code> documentation for the requirements and semantics of <code>C</code>, <code>I</code> and <code>h</code></td> </tr> <tr> <td><code>new S()</code></td> <td><code>S *</code></td> <td>Enters the state <code>S</code>. Certain functions must not be called from <code>S::S()</code>, see <a href= "#ClassTemplatesimple_state"><code>simple_state<></code></a> documentation for more information</td> </tr> <tr> <td><code>pS->exit();</code></td> <td> </td> <td>Exits the state <code>S</code> (first stage). The definition of an <code>exit</code> member function within models of the SimpleState concept is optional since <code>simple_state<></code> already defines the following public member: <code>void exit() {}</code>. <code>exit()</code> is not called when a state is exited while an exception is pending, see <code><a href= "#simple_state::terminate">simple_state<>::terminate()</a></code> for more information</td> </tr> <tr> <td><code>delete pS;</code></td> <td> </td> <td>Exits the state <code>S</code> (second stage)</td> </tr> <tr> <td><code>S::reactions</code></td> <td>An <code>mpl::list<></code> that is either empty or contains instantiations of the <code><a href= "#ClassTemplatecustom_reaction">custom_reaction</a></code>, <code><a href= "#ClassTemplatein_state_reaction">in_state_reaction</a></code>, <code><a href="#ClassTemplatedeferral">deferral</a></code>, <code><a href="#ClassTemplatetermination">termination</a></code> or <code><a href="#ClassTemplatetransition">transition</a></code> class templates. If there is only a single reaction then it can also be <code>typedef</code>ed directly, without wrapping it into an <code>mpl::list<></code></td> <td>The declaration of a <code>reactions</code> member <code>typedef</code> within models of the SimpleState concept is optional since <code>simple_state<></code> already defines the following public member: <code>typedef mpl::list<> reactions;</code></td> </tr> </table> <h2><a name="State" id="State">State</a> concept</h2> <p>A State is a <b>refinement</b> of <a href="#SimpleState">SimpleState</a> (that is, except for the default constructor a State type must also satisfy SimpleState requirements). For a State type <code>S</code>, a pointer <code>pS</code> of type <code>S *</code> pointing to an object of type <code>S</code> allocated with <code>new</code>, and an object <code>mc</code> of type <code>state< S, C, I, h ></code><code>::my_context</code> the following expressions/statements must be well-formed:</p> <table border="3" cellpadding="2" width="100%" summary="State concept"> <tr> <td><b>Expression/Statement</b></td> <td><b>Type</b></td> <td><b>Effects/Result/Notes</b></td> </tr> <tr> <td><code><a href="#ClassTemplatestate">state</a>< S, C, I, h > *<br>   pB = pS;</code></td> <td> </td> <td><code>state< S, C, I, h ></code> must be an unambiguous public base of <code>S</code>. See <code><a href= "#ClassTemplatestate">state<></a></code> documentation for the requirements and semantics of <code>C</code>, <code>I</code> and <code>h</code></td> </tr> <tr> <td><code>new S( mc )</code></td> <td><code>S *</code></td> <td>Enters the state <code>S</code>. No restrictions exist regarding the functions that can be called from <code>S::S()</code> (in contrast to the constructors of models of the SimpleState concept). <code>mc</code> must be forwarded to <code>state< S, C, I, h >::state()</code></td> </tr> </table> <h2><a name="Event" id="Event">Event</a> concept</h2> <p>A Event type defines an event for which state machines can define reactions.</p> <p>For a Event type <code>E</code> and a pointer <code>pCE</code> of type <code>const E *</code> pointing to an object of type <code>E</code> allocated with <code>new</code> the following expressions/statements must be well-formed and have the indicated effects/results:</p> <table border="3" cellpadding="2" width="100%" summary="Event concept"> <tr> <td><b>Expression/Statement</b></td> <td><b>Type</b></td> <td><b>Effects/Result/Notes</b></td> </tr> <tr> <td><code>const <a href="#ClassTemplateevent">event</a>< E > * pCB = pCE;</code></td> <td> </td> <td><code>event< E ></code> must be an unambiguous public base of <code>E</code></td> </tr> <tr> <td><code>new E( *pCE )</code></td> <td><code>E *</code></td> <td>Makes a copy of <code>pE</code></td> </tr> </table> <h1>Header <boost/statechart/<a name="state_machine.hpp" id= "state_machine.hpp">state_machine.hpp</a>></h1> <h2><a name="ClassTemplatestate_machine" id= "ClassTemplatestate_machine">Class template <code>state_machine</code></a></h2> <p>This is the base class template of all synchronous state machines.</p> <h3>Class template <code>state_machine</code> parameters</h3> <table border="3" cellpadding="2" width="100%" summary= "state_machine parameters"> <tr> <td><b>Template parameter</b></td> <td><b>Requirements</b></td> <td><b>Semantics</b></td> <td><b>Default</b></td> </tr> <tr> <td><code>MostDerived</code></td> <td>The most-derived subtype of this class template</td> <td> </td> <td> </td> </tr> <tr> <td><code>InitialState</code></td> <td>A model of the <a href="#SimpleState">SimpleState</a> or <a href="#State">State</a> concepts. The <code>Context</code> argument passed to the <code><a href= "#ClassTemplatesimple_state">simple_state<></a></code> or <code><a href="#ClassTemplatestate">state<></a></code> base of  <code>InitialState</code> must be <code>MostDerived</code>. That is, <code>InitialState</code> must be an <a href= "definitions.html#OutermostState">outermost state</a> of this state machine</td> <td>The state that is entered when <code>state_machine<><br> ::initiate()</code> is called</td> <td> </td> </tr> <tr> <td><code>Allocator</code></td> <td>A model of the standard Allocator concept</td> <td><code>Allocator::rebind<>::other</code> is used to allocate and deallocate all <code>simple_state</code> subtype objects and internal objects of dynamic storage duration</td> <td><code>std::allocator< void ></code></td> </tr> <tr> <td><code>ExceptionTranslator</code></td> <td>A model of the ExceptionTranslator concept</td> <td>see <a href= "#ExceptionTranslator">ExceptionTranslator</a> concept</td> <td><code>null_exception_translator</code></td> </tr> </table> <h3>Class template <code>state_machine</code> synopsis</h3> <pre> namespace boost { namespace statechart { template< class MostDerived, class InitialState, class Allocator = std::allocator< void >, class ExceptionTranslator = null_exception_translator > class state_machine : noncopyable { public: typedef MostDerived outermost_context_type; void <a href="#initiate">initiate</a>(); void <a href="#terminate">terminate</a>(); bool <a href="#terminated">terminated</a>() const; void <a href="#process_event">process_event</a>( const <a href= "#Classevent_base">event_base</a> & ); template< class Target > Target <a href="#state_cast">state_cast</a>() const; template< class Target > Target <a href="#state_downcast">state_downcast</a>() const; // a model of the <a href="#StateBase">StateBase</a> concept typedef <i>implementation-defined</i> state_base_type; // a model of the standard Forward Iterator concept typedef <i>implementation-defined</i> state_iterator; state_iterator <a href="#state_begin">state_begin</a>() const; state_iterator <a href="#state_end">state_end</a>() const; void <a href="#unconsumed_event">unconsumed_event</a>( const <a href= "#Classevent_base">event_base</a> & ) {} protected: <a href="#state_machine">state_machine</a>(); <a href="#state_machinedtor">~state_machine</a>(); void <a href="#post_event2">post_event</a>( const intrusive_ptr< const <a href= "#Classevent_base">event_base</a> > & ); void <a href="#post_event3">post_event</a>( const <a href= "#Classevent_base">event_base</a> & ); const event_base * <a href="#triggering_event1">triggering_event</a>() const; }; } } </pre> <h3>Class template <code>state_machine</code> constructor and destructor</h3> <pre> <a name="state_machine" id="state_machine">state_machine</a>(); </pre> <p><b>Effects</b>: Constructs a non-running state machine</p> <pre> <a name="state_machinedtor" id="state_machinedtor">~state_machine</a>(); </pre> <p><b>Effects</b>: Destructs the currently active outermost state and all its direct and indirect inner states. Innermost states are destructed first. Other states are destructed as soon as all their direct and indirect inner states have been destructed. The inner states of each state are destructed according to the number of their orthogonal region. The state in the orthogonal region with the highest number is always destructed first, then the state in the region with the second-highest number and so on<br> <b>Note</b>: Does not attempt to call any <code>exit</code> member functions</p> <h3>Class template <code>state_machine</code> modifier functions</h3> <pre> void <a name="initiate" id="initiate">initiate</a>(); </pre> <p><b>Effects</b>:</p> <ol> <li>Calls <code>terminate()</code></li> <li>Constructs a function object <code>action</code> with a parameter-less <code>operator()()</code> returning <code><a href= "#Classresult">result</a></code> that <ol type="a"> <li>enters (constructs) the state specified with the <code>InitialState</code> template parameter</li> <li>enters the tree formed by the direct and indirect inner initial states of <code>InitialState</code> depth first. The inner states of each state are entered according to the number of their orthogonal region. The state in orthogonal region 0 is always entered first, then the state in region 1 and so on</li> </ol> </li> <li>Constructs a function object <code>exceptionEventHandler</code> with an <code>operator()()</code> returning <code>result</code> and accepting an exception event parameter that processes the passed exception event, with the following differences to the processing of normal events: <ul type="disc"> <li>From the moment when the exception has been thrown until right after the execution of the exception event reaction, states that need to be exited are only destructed but no <code>exit</code> member functions are called</li> <li><a href="definitions.html#Reaction">Reaction</a> search always starts with the outermost <a href= "definitions.html#UnstableState">unstable state</a></li> <li>As for normal events, reaction search moves outward when the current state cannot handle the event. However, if there is no outer state (an <a href="definitions.html#OutermostState">outermost state</a> has been reached) the reaction search is considered unsuccessful. That is, exception events will never be dispatched to orthogonal regions other than the one that caused the exception event</li> <li>Should an exception be thrown during exception event reaction search or reaction execution then the exception is propagated out of the <code>exceptionEventHandler</code> function object (that is, <code>ExceptionTranslator</code> is <b>not</b> used to translate exceptions thrown while processing an exception event)</li> <li>If no reaction could be found for the exception event or if the state machine is not stable after processing the exception event, the original exception is rethrown. Otherwise, a <code><a href= "#Classresult">result</a></code> object is returned equal to the one returned by <code>simple_state<>::discard_event()</code></li> </ul> </li> <li>Passes <code>action</code> and <code>exceptionEventHandler</code> to <code>ExceptionTranslator::operator()()</code>. If <code>ExceptionTranslator::operator()()</code> throws an exception, the exception is propagated to the caller. If the caller catches the exception, the currently active outermost state and all its direct and indirect inner states are destructed. Innermost states are destructed first. Other states are destructed as soon as all their direct and indirect inner states have been destructed. The inner states of each state are destructed according to the number of their orthogonal region. The state in the orthogonal region with the highest number is always destructed first, then the state in the region with the second-highest number and so on. Continues with step 5 otherwise (the return value is discarded)</li> <li>Processes all posted events (see <code>process_event()</code>). Returns to the caller if there are no more posted events</li> </ol> <p><b>Throws</b>: Any exceptions propagated from <code>ExceptionTranslator::operator()()</code>. Exceptions never originate in the library itself but only in code supplied through template parameters:</p> <ul> <li><code>Allocator::rebind<>::other::allocate()</code></li> <li>state constructors</li> <li><code>react</code> member functions</li> <li><code>exit</code> member functions</li> <li>transition-actions</li> </ul> <pre> void <a name="terminate" id="terminate">terminate</a>(); </pre> <p><b>Effects</b>:</p> <ol> <li>Constructs a function object <code>action</code> with a parameter-less <code>operator()()</code> returning <code><a href= "#Classresult">result</a></code> that <a href= "#simple_state::terminate">terminates</a> the currently active outermost state, discards all remaining events and clears all history information</li> <li>Constructs a function object <code>exceptionEventHandler</code> with an <code>operator()()</code> returning <code><a href= "#Classresult">result</a></code> and accepting an exception event parameter that processes the passed exception event, with the following differences to the processing of normal events: <ul type="disc"> <li>From the moment when the exception has been thrown until right after the execution of the exception event reaction, states that need to be exited are only destructed but no <code>exit</code> member functions are called</li> <li><a href="definitions.html#Reaction">Reaction</a> search always starts with the outermost <a href= "definitions.html#UnstableState">unstable state</a></li> <li>As for normal events, reaction search moves outward when the current state cannot handle the event. However, if there is no outer state (an <a href="definitions.html#OutermostState">outermost state</a> has been reached) the reaction search is considered unsuccessful. That is, exception events will never be dispatched to orthogonal regions other than the one that caused the exception event</li> <li>Should an exception be thrown during exception event reaction search or reaction execution then the exception is propagated out of the <code>exceptionEventHandler</code> function object (that is, <code>ExceptionTranslator</code> is <b>not</b> used to translate exceptions thrown while processing an exception event)</li> <li>If no reaction could be found for the exception event or if the state machine is not stable after processing the exception event, the original exception is rethrown. Otherwise, a <code><a href= "#Classresult">result</a></code> object is returned equal to the one returned by <code>simple_state<>::discard_event()</code></li> </ul> </li> <li>Passes <code>action</code> and <code>exceptionEventHandler</code> to <code>ExceptionTranslator::operator()()</code>. If <code>ExceptionTranslator::operator()()</code> throws an exception, the exception is propagated to the caller. If the caller catches the exception, the currently active outermost state and all its direct and indirect inner states are destructed. Innermost states are destructed first. Other states are destructed as soon as all their direct and indirect inner states have been destructed. The inner states of each state are destructed according to the number of their orthogonal region. The state in the orthogonal region with the highest number is always destructed first, then the state in the region with the second-highest number and so on. Otherwise, returns to the caller</li> </ol> <p><b>Throws</b>: Any exceptions propagated from <code>ExceptionTranslator::operator()</code>. Exceptions never originate in the library itself but only in code supplied through template parameters:</p> <ul> <li><code>Allocator::rebind<>::other::allocate()</code></li> <li>state constructors</li> <li><code>react</code> member functions</li> <li><code>exit</code> member functions</li> <li>transition-actions</li> </ul> <pre> void <a name="process_event" id= "process_event">process_event</a>( const <a href= "#Classevent_base">event_base</a> & ); </pre> <p><b>Effects</b>:</p> <ol> <li>Selects the passed event as the current event (henceforth referred to as <code>currentEvent</code>)</li> <li>Starts a new <a href="definitions.html#Reaction">reaction</a> search</li> <li>Selects an arbitrary but in this reaction search not yet visited state from all the currently active <a href= "definitions.html#InnermostState">innermost states</a>. If no such state exists then continues with step 10</li> <li>Constructs a function object <code>action</code> with a parameter-less <code>operator()()</code> returning <code><a href= "#Classresult">result</a></code> that does the following: <ol type="a"> <li>Searches a reaction suitable for <code>currentEvent</code>, starting with the current innermost state and moving outward until a state defining a reaction for the event is found. Returns <code>simple_state<>::forward_event()</code> if no reaction has been found</li> <li>Executes the found reaction. If the reaction result is equal to the return value of <code>simple_state<>::forward_event()</code> then resumes the reaction search (step a). Returns the reaction result otherwise</li> </ol> </li> <li>Constructs a function object <code>exceptionEventHandler</code> returning <code><a href="#Classresult">result</a></code> and accepting an exception event parameter that processes the passed exception event, with the following differences to the processing of normal events: <ul type="disc"> <li>From the moment when the exception has been thrown until right after the execution of the exception event reaction, states that need to be exited are only destructed but no <code>exit</code> member functions are called</li> <li>If the state machine is stable when the exception event is processed then exception event reaction search starts with the innermost state that was last visited during the last normal event reaction search (the exception event was generated as a result of this normal reaction search)</li> <li>If the state machine is <a href= "definitions.html#UnstableStateMachine">unstable</a> when the exception event is processed then exception event reaction search starts with the outermost <a href= "definitions.html#UnstableState">unstable state</a></li> <li>As for normal events, reaction search moves outward when the current state cannot handle the event. However, if there is no outer state (an <a href="definitions.html#OutermostState">outermost state</a> has been reached) the reaction search is considered unsuccessful. That is, exception events will never be dispatched to orthogonal regions other than the one that caused the exception event</li> <li>Should an exception be thrown during exception event reaction search or reaction execution then the exception is propagated out of the <code>exceptionEventHandler</code> function object (that is, <code>ExceptionTranslator</code> is <b>not</b> used to translate exceptions thrown while processing an exception event)</li> <li>If no reaction could be found for the exception event or if the state machine is not stable after processing the exception event, the original exception is rethrown. Otherwise, a <code><a href= "#Classresult">result</a></code> object is returned equal to the one returned by <code>simple_state<>::discard_event()</code></li> </ul> </li> <li>Passes <code>action</code> and <code>exceptionEventHandler</code> to <code>ExceptionTranslator::operator()()</code>. If <code>ExceptionTranslator::operator()()</code> throws an exception, the exception is propagated to the caller. If the caller catches the exception, the currently active outermost state and all its direct and indirect inner states are destructed. Innermost states are destructed first. Other states are destructed as soon as all their direct and indirect inner states have been destructed. The inner states of each state are destructed according to the number of their orthogonal region. The state in the orthogonal region with the highest number is always destructed first, then the state in the region with the second-highest number and so on. Otherwise continues with step 7</li> <li>If the return value of <code>ExceptionTranslator::operator()()</code> is equal to the one of <code>simple_state<>::forward_event()</code> then continues with step 3</li> <li>If the return value of <code>ExceptionTranslator::operator()()</code> is equal to the one of <code>simple_state<>::defer_event()</code> then the return value of <code>currentEvent.<a href= "#intrusive_from_this">intrusive_from_this</a>()</code> is stored in the deferred events queue. Continues with step 11</li> <li>If the return value of <code>ExceptionTranslator::operator()()</code> is equal to the one of <code>simple_state<>::discard_event()</code> then continues with step 11</li> <li>Calls <code>static_cast< MostDerived * >( this )->unconsumed_event( currentEvent )</code>. If <code>unconsumed_event()</code> throws an exception, the exception is propagated to the caller. Such an exception never leads to the destruction of any states (in contrast to exceptions propagated from <code>ExceptionTranslator::operator()()</code>)</li> <li>If the posted events queue is non-empty then dequeues the first event, selects it as <code>currentEvent</code> and continues with step 2. Returns to the caller otherwise</li> </ol> <p><b>Throws</b>: Any exceptions propagated from <code>MostDerived::unconsumed_event()</code> or <code>ExceptionTranslator::operator()</code>. Exceptions never originate in the library itself but only in code supplied through template parameters:</p> <ul> <li><code>Allocator::rebind<>::other::allocate()</code></li> <li>state constructors</li> <li><code>react</code> member functions</li> <li><code>exit</code> member functions</li> <li>transition-actions</li> <li><code>MostDerived::unconsumed_event()</code></li> </ul> <pre> void <a name="post_event2" id="post_event2">post_event</a>( const intrusive_ptr< const <a href= "#Classevent_base">event_base</a> > & ); </pre> <p><b>Effects</b>: Pushes the passed event into the posted events queue<br> <b>Throws</b>: Any exceptions propagated from <code>Allocator::allocate()</code></p> <pre> void <a name="post_event3" id="post_event3">post_event</a>( const <a href= "#Classevent_base">event_base</a> & evt ); </pre> <p><b>Effects</b>: <code>post_event( evt.intrusive_from_this() );</code><br> <b>Throws</b>: Any exceptions propagated from <code>Allocator::allocate()</code></p> <pre> void <a name="unconsumed_event" id= "unconsumed_event">unconsumed_event</a>( const <a href= "#Classevent_base">event_base</a> & evt ); </pre> <p><b>Effects</b>: None<br> <b>Note</b>: This function (or, if present, the equally named derived class member function) is called by <a href="#process_event">process_event</a>() whenever a dispatched event did not trigger a reaction, see <a href= "#process_event">process_event</a>() effects, point 10 for more information.</p> <h3>Class template <code>state_machine</code> observer functions</h3> <pre> bool <a name="terminated" id="terminated">terminated</a>() const; </pre> <p><b>Returns</b>: <code>true</code>, if the machine is terminated. Returns <code>false</code> otherwise<br> <b>Note</b>: Is equivalent to <code>state_begin() == state_end()</code></p> <pre> template< class Target > Target <a name="state_cast" id="state_cast">state_cast</a>() const; </pre> <p><b>Returns</b>: Depending on the form of <code>Target</code> either a reference or a pointer to <code>const</code> if at least one of the currently active states can successfully be <code>dynamic_cast</code> to <code>Target</code>. Returns <code>0</code> for pointer targets and throws <code>std::bad_cast</code> for reference targets otherwise. <code>Target</code> can take either of the following forms: <code>const Class *</code> or <code>const Class &</code><br> <b>Throws</b>: <code>std::bad_cast</code> if <code>Target</code> is a reference type and none of the active states can be <code>dynamic_cast</code> to Target<br> <b>Note</b>: The search sequence is the same as for <code><a href= "#process_event">process_event</a>()</code></p> <pre> template< class Target > Target <a name="state_downcast" id= "state_downcast">state_downcast</a>() const; </pre> <p><b>Requires</b>: For reference targets the compiler must support partial specialization of class templates, otherwise a compile-time error will result. The type denoted by <code>Target</code> must be a model of the <a href="#SimpleState">SimpleState</a> or <a href="#State">State</a> concepts<br> <b>Returns</b>: Depending on the form of <code>Target</code> either a reference or a pointer to <code>const</code> if <code>Target</code> is equal to the most-derived type of a currently active state. Returns <code>0</code> for pointer targets and throws <code>std::bad_cast</code> for reference targets otherwise. <code>Target</code> can take either of the following forms: <code>const Class *</code> or <code>const Class &</code><br> <b>Throws</b>: <code>std::bad_cast</code> if <code>Target</code> is a reference type and none of the active states has a most derived type equal to <code>Target</code><br> <b>Note</b>: The search sequence is the same as for <code><a href= "#process_event">process_event</a>()</code></p> <pre> state_iterator <a name="state_begin" id= "state_begin">state_begin</a>() const; </pre> <pre> state_iterator <a name="state_end" id="state_end">state_end</a>() const; </pre> <p><b>Return</b>: Iterator objects, the range [<code>state_begin()</code>, <code>state_end()</code>) refers to all currently active <a href= "definitions.html#InnermostState">innermost states</a>. For an object <code>i</code> of type <code>state_iterator</code>, <code>*i</code> returns a <code>const state_base_type &</code> and <code>i.operator->()</code> returns a <code>const state_base_type *</code><br> <b>Note</b>: The position of a given innermost state in the range is arbitrary. It may change with each call to a modifier function. Moreover, all iterators are invalidated whenever a modifier function is called</p> <pre> const event_base * <a name="triggering_event1" id="triggering_event1">triggering_event</a>(); </pre> <p><b>Returns</b>: A pointer to the event that triggered the reaction that is currently being executed. Returns <code>0</code> if no reaction is being executed or if the current reaction was triggered by either <code><a href="#initiate">initiate</a>()</code> or <code><a href="#terminate">terminate</a>()</code> </p> <h1>Header <boost/statechart/<br> <a name="asynchronous_state_machine.hpp" id= "asynchronous_state_machine.hpp">asynchronous_state_machine.hpp</a>></h1> <h2><a name="ClassTemplateasynchronous_state_machine" id= "ClassTemplateasynchronous_state_machine">Class template <code>asynchronous_state_machine</code></a></h2> <p>This is the base class template of all asynchronous state machines.</p> <h3>Class template <code>asynchronous_state_machine</code> parameters</h3> <table border="3" cellpadding="2" width="100%" summary= "asynchronous_state_machine parameters"> <tr> <td><b>Template parameter</b></td> <td><b>Requirements</b></td> <td><b>Semantics</b></td> <td><b>Default</b></td> </tr> <tr> <td><code>MostDerived</code></td> <td>The most-derived subtype of this class template</td> <td> </td> <td> </td> </tr> <tr> <td><code>InitialState</code></td> <td>A model of the <a href="#SimpleState">SimpleState</a> or <a href="#State">State</a> concepts. The <code>Context</code> argument passed to the <code><a href= "#ClassTemplatesimple_state">simple_state<></a></code> or <code><a href="#ClassTemplatestate">state<></a></code> base of <code>InitialState</code> must be <code>MostDerived</code>. That is, <code>InitialState</code> must be an <a href= "definitions.html#OutermostState">outermost state</a> of this state machine</td> <td>The state that is entered when the state machine is initiated through the <code>Scheduler</code> object</td> <td> </td> </tr> <tr> <td><code>Scheduler</code></td> <td>A model of the Scheduler concept</td> <td>see <a href="#Scheduler">Scheduler</a> concept</td> <td><code>fifo_scheduler<></code></td> </tr> <tr> <td><code>Allocator</code></td> <td>A model of the standard Allocator concept</td> <td> </td> <td><code>std::allocator< void ></code></td> </tr> <tr> <td><code>ExceptionTranslator</code></td> <td>A model of the ExceptionTranslator concept</td> <td>see <a href= "#ExceptionTranslator">ExceptionTranslator</a> concept</td> <td><code>null_exception_translator</code></td> </tr> </table> <h3>Class template <code>asynchronous_state_machine</code> synopsis</h3> <pre> namespace boost { namespace statechart { template< class MostDerived, class InitialState, class Scheduler = fifo_scheduler<>, class Allocator = std::allocator< void >, class ExceptionTranslator = null_exception_translator > class asynchronous_state_machine : public state_machine< MostDerived, InitialState, Allocator, ExceptionTranslator >, public event_processor< Scheduler > { protected: typedef asynchronous_state_machine my_base; asynchronous_state_machine( typename event_processor< Scheduler >::my_context ctx ); ~asynchronous_state_machine(); }; } } </pre> <h3>Class template <code>asynchronous_state_machine</code> constructor and destructor</h3> <pre> asynchronous_state_machine( typename event_processor< Scheduler >::my_context ctx ); </pre> <p><b>Effects</b>: Constructs a non-running asynchronous state machine<br> <b>Note</b>: Users cannot create <code>asynchronous_state_machine<></code> subtype objects directly. This can only be done through an object of the <code>Scheduler</code> class</p> <pre> ~asynchronous_state_machine(); </pre> <p><b>Effect