|
The Boost Statechart LibraryReference |
state_machine
asynchronous_state_machine
event_processor
fifo_scheduler
exception_translator
null_exception_translator
history_mode
simple_state
state
shallow_history
deep_history
event_base
event
transition
termination
deferral
custom_reaction
result
A Scheduler type defines the following:
event_processor<>
subtypes and how the lifetime of such objects is managedevent_processor<>
subtype objects
can share the same queue and scheduler thread
event_processor<>
subtype objects and what happens when such an
event is processedevent_processor<>
subtype objects propagates an exceptionFor a Scheduler type S
and an object
cpc
of type const S::processor_context
the following expressions
must be well-formed and have the indicated results:
Expression | Type | Result |
cpc.my_scheduler() |
S & |
A reference to the scheduler |
cpc.my_handle() |
S::processor_handle |
The handle identifying the event_processor<>
subtype object |
To protect against abuse, all members of S::processor_context
should be declared private. As a result, event_processor<>
must
be a friend of S::processor_context
.
A FifoWorker type defines the following:
For a FifoWorker type F
, an object f
of that
type, a const
object cf
of that type, a
parameterless function object w
of arbitrary type and an
unsigned long
value n
the following expressions/statements must be
well-formed and have the indicated results:
Expression/Statement | Type | Effects/Result |
F::work_item |
boost::function0< |
|
F() or F( false ) |
F |
Constructs a non-blocking (see below) object of the FifoWorker type. In single-threaded builds the second expression is not well-formed |
F( true ) |
F |
Constructs a blocking (see below) object of the FifoWorker type. Not well-formed in single-threaded builds |
f.queue_work_item( w ); |
Constructs and queues an object of type F::work_item ,
passing w as the only argument |
|
f.terminate(); |
Creates and queues an object of type F::work_item
that, when later executed in operator()() , leads to a
modification of internal state so that terminated()
henceforth returns true |
|
cf.terminated(); |
bool |
true if terminate() has been
called and the resulting work item has been executed in operator()() .
Returns false otherwiseMust only be called from the thread that also calls operator()() |
f( n ); |
unsigned long |
Enters a loop that, with each cycle, dequeues and calls
operator()() on the oldest work item in the queue.The loop is left and the number of executed work items returned if one or more of the following conditions are met:
If the queue is empty and none of the above conditions are met then the
thread calling |
f(); |
unsigned long |
Has exactly the same semantics as f( n );
with n == 0 (see above) |
An ExceptionTranslator type defines how C++ exceptions occurring during state machine operation are translated to exception events.
For an ExceptionTranslator object et
, a parameterless function
object a
of arbitrary type returning
result
and a function object eh
of
arbitrary type taking a const event_base
&
parameter and returning
result
the following expression must be well-formed and have
the indicated results:
Expression | Type | Effects/Result |
et( a, eh ); |
result |
|
A StateBase type is the common base of all states of a given state machine
type. state_machine<>::state_base_type
is a model of the
StateBase concept.
For a StateBase type S
and a const
object
cs
of that type the following expressions must be well-formed and have
the indicated results:
Expression | Type | Result |
cs.outer_state_ptr() |
const S * |
0 if cs is an
outermost state, a pointer
to the direct outer state of cs otherwise |
cs.dynamic_type() |
S::id_type |
A value unambiguously identifying the most-derived type of
cs . S::id_type values are comparable with
operator==() and operator!=() . An unspecified
collating order can be established with std::less< S::id_type > |
cs.custom_dynamic_type_ptr< |
const Type * |
A pointer to the custom type identifier or 0 .
If != 0 , Type must match the type of the
previously set pointer. This function is only available if
BOOST_STATECHART_USE_NATIVE_RTTI is not defined |
typeid( cs ) |
const std:: |
A value unambiguously identifying the most-derived type of
cs , if
BOOST_STATECHART_USE_NATIVE_RTTI is defined. Otherwise, a value
identifying the StateBase type is returned |
A SimpleState type defines one state of a particular state machine.
For a SimpleState type S
and a pointer pS
pointing to an object of type S
allocated with new
the following expressions/statements must be well-formed
and have the indicated effects/results:
Expression/Statement | Type | Effects/Result/Notes |
simple_state< |
simple_state< S, C, I, h > must be an unambiguous
public base of S . See
simple_state<>
documentation for the requirements and semantics of C ,
I and h |
|
new S() |
S * |
Enters the state S . Certain functions must not be called from
S::S() , see
simple_state<>
documentation for more information |
pS->exit(); |
Exits the state S (first stage). The definition of an
exit member function within models of the SimpleState concept is
optional since simple_state<> already defines the following public member:
void exit() {} . exit() is not called when a
state is exited while an exception is pending, see
simple_state<>::terminate()
for more information |
|
delete pS; |
Exits the state S (second stage) |
|
S::reactions |
An mpl::list<> that is either empty or
contains instantiations of
the custom_reaction ,
in_state_reaction ,
deferral ,
termination or
transition class
templates. If there is only a single reaction then it can also be
typedef ed
directly, without wrapping it into an mpl::list<> |
The declaration of a reactions member typedef
within models of the SimpleState concept is optional since simple_state<>
already defines the following public member: typedef mpl::list<>
reactions; |
A State is a refinement of SimpleState
(that is, except for the default constructor a State type must also satisfy
SimpleState requirements). For a State type S
, a pointer pS
of type S *
pointing to an object of type S
allocated with new
, and an object mc
of type
state< S, C, I, h >
::my_context
the following expressions/statements must be well-formed:
Expression/Statement | Type | Effects/Result/Notes |
state< S, C, I, h > * |
state< S, C, I, h > must be an unambiguous
public base of S . See
state<>
documentation for the requirements and semantics of C ,
I and h |
|
new S( mc ) |
S * |
Enters the state S . No restrictions exist regarding the
functions that can be called from S::S() (in contrast to the
constructors of models of the SimpleState concept). mc must
be forwarded to
state< S, C, I, h >::state() |
A Event type defines an event for which state machines can define reactions.
For a Event type E
and a pointer pCE
of type
const E *
pointing to an object of type E
allocated with new
the following expressions/statements must be well-formed
and have the indicated effects/results:
Expression/Statement | Type | Effects/Result/Notes |
const event<
E > * pCB = pCE; |
event< E > must be an unambiguous
public base of E |
|
new E( *pCE ) |
E * |
Makes a copy of pE |
state_machine
This is the base class template of all synchronous state machines.
state_machine
parametersTemplate parameter | Requirements | Semantics | Default |
MostDerived |
The most-derived subtype of this class template | ||
InitialState |
A model of the SimpleState or State
concepts. The
Context argument passed to the
simple_state<> or
state<> base of InitialState must be MostDerived . That is,
InitialState must be an
outermost state of this state machine |
The state that is entered when state_machine<> is called |
|
Allocator |
A model of the standard Allocator concept | std::allocator< void > |
|
ExceptionTranslator |
A model of the ExceptionTranslator concept | see ExceptionTranslator concept | null_exception_translator |
state_machine
synopsisnamespace 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 initiate(); void terminate(); bool terminated() const; void process_event( const event_base & ); template< class Target > Target state_cast() const; template< class Target > Target state_downcast() const; // a model of the StateBase concept typedef implementation-defined state_base_type; // a model of the standard Forward Iterator concept typedef implementation-defined state_iterator; state_iterator state_begin() const; state_iterator state_end() const; protected: state_machine(); ~state_machine(); }; } }
state_machine
constructor and destructorstate_machine();
Effects: Constructs a non-running state machine
~state_machine();
Effects: 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
Note: Does not attempt to call any exit
member functions
state_machine
modifier functionsvoid initiate();
Effects:
terminate()
action
with a parameter-less
operator()()
returning result
thatInitialState
template parameterInitialState
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 onexceptionEventHandler
with an
operator()()
returning result
and accepting an
exception event parameter that processes the passed exception event, with
the following differences to the processing of normal events:exit
member functions are called
exceptionEventHandler
function object (that is,
ExceptionTranslator
is not used to translate exceptions
thrown while processing an exception event)result
object is returned equal to the one returned by simple_state<>::discard_event()
action
and exceptionEventHandler
to
ExceptionTranslator::operator()()
.
If ExceptionTranslator::operator()()
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)process_event()
).
Returns to the caller if there are no more posted eventsThrows: Any exceptions propagated from
ExceptionTranslator::operator()()
. Exceptions never originate in the
library itself but only in code supplied through template parameters:
operator new()
(used to allocate states)Allocator::allocate()
react
member functionsexit
member functionsvoid terminate();
Effects:
action
with a parameter-less
operator()()
returning result
that terminates the currently active
outermost state, discards all remaining events and clears all history
informationexceptionEventHandler
with an
operator()()
returning result
and accepting an
exception event parameter that processes the passed exception event, with
the following differences to the processing of normal events:exit
member functions are called
exceptionEventHandler
function object (that is,
ExceptionTranslator
is not used to translate exceptions
thrown while processing an exception event)result
object is returned equal to the one returned by simple_state<>::discard_event()
action
and exceptionEventHandler
to ExceptionTranslator::operator()()
.
If ExceptionTranslator::operator()()
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
callerThrows: Any exceptions propagated from
ExceptionTranslator::operator()
. Exceptions never originate in the
library itself but only in code supplied through template parameters:
operator new()
(used to allocate states)Allocator::allocate()
react
member functionsexit
member functionsvoid process_event( const event_base & );
Effects:
currentEvent
)action
with a parameter-less
operator()()
returning result
that does the following:currentEvent
, starting with the
current innermost state and moving outward until a state defining a
reaction for the event is found. Returns simple_state<>::forward_event()
if no reaction has been foundsimple_state<>::forward_event()
then resumes
the reaction search (step a). Returns the reaction result otherwiseexceptionEventHandler
returning
result
and accepting an exception
event parameter that processes the passed exception event, with the
following differences to the processing of normal events:exit
member functions are calledexceptionEventHandler
function object (that is,
ExceptionTranslator
is not used to translate exceptions
thrown while processing an exception event)result
object is returned equal to the one returned by simple_state<>::discard_event()
action
and exceptionEventHandler
to ExceptionTranslator::operator()()
.
If ExceptionTranslator::operator()()
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 ExceptionTranslator::operator()()
is
equal to the one of simple_state<>::forward_event()
then
continues with step 3ExceptionTranslator::operator()()
is
equal to the one of simple_state<>::defer_event()
then the
return value of currentEvent.intrusive_from_this()
is stored in a state-specific queue. Continues with step 10ExceptionTranslator::operator()()
is
equal to the one of simple_state<>::discard_event()
then continues with
step 10currentEvent
and continues with step 2. Returns to the
caller otherwiseThrows: Any exceptions propagated from
ExceptionTranslator::operator()
. Exceptions never originate in the
library itself but only in code supplied through template parameters:
operator new()
(used to allocate states)Allocator::allocate()
react
member functionsexit
member functionsstate_machine
observer functionsbool terminated() const;
Returns: true
, if the machine is terminated. Returns
false
otherwise
Note: Is equivalent to state_begin() == state_end()
template< class Target > Target state_cast() const;
Returns: Depending on the form of Target
either a
reference or a pointer to const
if at least one of the currently
active states can successfully be dynamic_cast
to Target
.
Returns 0
for pointer targets and throws std::bad_cast
for reference targets otherwise. Target
can take either of the
following forms: const Class *
or const Class &
Throws: std::bad_cast
if Target
is a
reference type and none of the active states can be dynamic_cast
to Target
Note: The search sequence is the same as for
process_event()
template< class Target > Target state_downcast() const;
Requires: For reference targets the compiler must support partial
specialization of class templates, otherwise a compile-time error will result.
The type denoted by Target
must be a model of the
SimpleState or State concepts
Returns: Depending on the form of Target
either a
reference or a pointer to const
if Target
is equal
to the most-derived type of a currently active state. Returns 0
for pointer targets and throws std::bad_cast
for reference
targets otherwise. Target
can take either of the following forms:
const Class *
or const Class &
Throws: std::bad_cast
if Target
is a
reference type and none of the active states has a most derived type equal to
Target
Note: The search sequence is the same as for
process_event()
state_iterator state_begin() const;
state_iterator state_end() const;
Return: Iterator objects, the range [state_begin()
,
state_end()
) refers to all currently active
innermost states. For an object
i
of type state_iterator
, *i
returns a
const state_base_type &
and i.operator->()
returns a
const state_base_type *
Note: 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
asynchronous_state_machine
This is the base class template of all asynchronous state machines.
asynchronous_state_machine
parametersTemplate parameter | Requirements | Semantics | Default |
MostDerived |
The most-derived subtype of this class template | ||
InitialState |
A model of the SimpleState or State
concepts. The Context argument passed to the
simple_state<>
or
state<> base of InitialState must be MostDerived . That is,
InitialState must be an
outermost state of this state machine |
The state that is entered when the state machine is
initiated through the Scheduler object |
|
Scheduler |
A model of the Scheduler concept | see Scheduler concept | fifo_scheduler<> |
Allocator |
A model of the standard Allocator concept | std::allocator< void > |
|
ExceptionTranslator |
A model of the ExceptionTranslator concept | see ExceptionTranslator concept | null_exception_translator |
asynchronous_state_machine
synopsisnamespace 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 event_processor< Scheduler > { protected: typedef asynchronous_state_machine my_base; asynchronous_state_machine( typename event_processor< Scheduler >::my_context ctx ); ~asynchronous_state_machine(); }; } }
asynchronous_state_machine
constructor and
destructorasynchronous_state_machine( typename event_processor< Scheduler >::my_context ctx );
Effects: Constructs a non-running asynchronous state machine
Note: Users cannot create asynchronous_state_machine<>
subtype objects directly. This can only be done through an object of the
Scheduler
class
~asynchronous_state_machine();
Effects: Destructs the state machine
Note: Users cannot destruct asynchronous_state_machine<>
subtype objects directly. This can only be done through an object of the
Scheduler
class
event_processor
This is the base class template of all types that process events.
asynchronous_state_machine<>
is just one possible event processor
implementation.
event_processor
parametersTemplate parameter | Requirements | Semantics | Default |
Scheduler |
A model of the Scheduler concept | see Scheduler concept |
event_processor
synopsisnamespace boost { namespace statechart { template< class Scheduler > class event_processor { public: virtual ~event_processor(); Scheduler & my_scheduler() const; typedef typename Scheduler::processor_handle processor_handle; processor_handle my_handle() const; void initiate(); void process_event( const event_base & evt ); void terminate(); protected: typedef const typename Scheduler::processor_context & my_context; event_processor( my_context ctx ); private: virtual void initiate_impl() = 0; virtual void process_event_impl( const event_base & evt ) = 0; virtual void terminate_impl() = 0; }; } }
event_processor
constructor and destructorevent_processor( my_context ctx );
Effects: Constructs an event processor object and stores copies of
the reference returned by myContext.my_scheduler()
and the object
returned by myContext.my_handle()
Note: Users cannot create event_processor<>
subtype
objects directly. This can only be done through an object of the
Scheduler
class
virtual ~event_processor();
Effects: Destructs an event processor object
Note: Users cannot destruct event_processor<>
subtype
objects directly. This can only be done through an object of the
Scheduler
class
event_processor
modifier functionsvoid initiate();
Effects: initiate_impl();
Throws: Any exceptions propagated from the implementation of
initiate_impl()
void process_event( const event_base & evt );
Effects: process_event_impl( evt );
Throws: Any exceptions propagated from the implementation of
process_event_impl()
void terminate();
Effects: terminate_impl();
Throws: Any exceptions propagated from the implementation of
terminate_impl()
event_processor
observer functionsScheduler & my_scheduler() const;
Returns: The Scheduler
reference obtained in the
constructor
processor_handle my_handle() const;
Returns: The processor_handle
object obtained in the
constructor
fifo_scheduler
This class template is a model of the Scheduler concept.
fifo_scheduler
parametersTemplate parameter | Requirements | Semantics | Default |
FifoWorker |
A model of the FifoWorker concept | see FifoWorker concept | fifo_worker<> |
Allocator |
A model of the standard Allocator concept | std::allocator< void > |
fifo_scheduler
synopsisnamespace boost { namespace statechart { template< class FifoWorker = fifo_worker<>, class Allocator = std::allocator< void > > class fifo_scheduler : noncopyable { public: fifo_scheduler( bool waitOnEmptyQueue = false ); typedef implementation-defined processor_handle; class processor_context : noncopyable { processor_context( fifo_scheduler & scheduler, const processor_handle & theHandle ); fifo_scheduler & my_scheduler() const; const processor_handle & my_handle() const; friend class fifo_scheduler; friend class event_processor< fifo_scheduler >; }; template< class Processor > processor_handle create_processor(); template< class Processor, typename Param1 > processor_handle create_processor( Param1 param1 ); // More create_processor overloads void destroy_processor( processor_handle processor ); void initiate_processor( processor_handle processor ); void terminate_processor( processor_handle processor ); typedef intrusive_ptr< const event_base > event_ptr_type; void queue_event( const processor_handle & processor, const event_ptr_type & pEvent ); typedef typename FifoWorker::work_item work_item; void queue_work_item( const work_item & item ); void terminate(); bool terminated() const; unsigned long operator()( unsigned long maxEventCount = 0 ); }; } }
fifo_scheduler
constructorfifo_scheduler( bool waitOnEmptyQueue = false );
Effects: Constructs a fifo_scheduler<>
object. In
multi-threaded builds, waitOnEmptyQueue
is forwarded to the
constructor of a data member of type FifoWorker
. In
single-threaded builds, the FifoWorker
data member is
default-constructed
Note: In single-threaded builds the fifo_scheduler<>
constructor does not accept any parameters and operator()()
thus
always returns to the caller when the event queue is empty
fifo_scheduler
modifier functionstemplate< class Processor > processor_handle create_processor();
Requires: The Processor
type must be a direct or
indirect subtype of the
event_processor
class template
Effects: Creates and passes to FifoWorker::queue_work_item()
an object of type FifoWorker::work_item
that, when later executed
in FifoWorker::operator()()
, leads to a call to the constructor
of Processor
, passing an appropriate processor_context
object as the only argument
Returns: A processor_handle
object that henceforth
identifies the created event processor object
Throws: Any exceptions propagated from Allocator::allocate()
Caution: The current implementation of this function makes an
(indirect) call to global operator new()
. Unless global
operator new()
is replaced, care must be taken when to call this
function in applications with hard real-time requirements
template< class Processor, typename Param1 > processor_handle create_processor( Param1 param1 );
Requires: The Processor
type must be a direct or
indirect subtype of the
event_processor
class template
Effects: Creates and passes to FifoWorker::queue_work_item()
an object of type FifoWorker::work_item
that, when later executed
in FifoWorker::operator()()
, leads to a call to the constructor
of Processor
, passing an appropriate processor_context
object and param1
as arguments
Returns: A processor_handle
object that henceforth
identifies the created event processor object
Throws: Any exceptions propagated from Allocator::allocate()
Note: boost::ref()
and boost::cref()
can be used
to pass arguments by reference rather than by copy. fifo_scheduler<>
has 5 additional create_processor<>
overloads, allowing to pass
up to 6 custom arguments to the constructors of event processors
Caution: The current implementation of this and all other overloads
make (indirect) calls to global operator new()
. Unless global
operator new()
is replaced, care must be taken when to call these
overloads in applications with hard real-time requirements
void destroy_processor( processor_handle processor );
Requires: processor
was obtained from a call to one of
the create_processor<>()
overloads on the same
fifo_scheduler<>
object
Effects: Creates and passes to FifoWorker::queue_work_item()
an object of type FifoWorker::work_item
that, when later executed
in FifoWorker::operator()()
, leads to a call to the destructor of
the event processor object associated with processor
. The object
is silently discarded if the event processor object has been destructed before
Throws: Any exceptions propagated from Allocator::allocate()
Caution: The current implementation of this function leads to an
(indirect) call to global operator delete()
(the call is made
when the last processor_handle
object associated with the event
processor object is destructed). Unless global operator delete()
is replaced, care must be taken when to call this function in applications
with hard real-time requirements
void initiate_processor( processor_handle processor );
Requires: processor
was obtained from a call to one of
the create_processor()
overloads on the same fifo_scheduler<>
object
Effects: Creates and passes to FifoWorker::queue_work_item()
an object of type FifoWorker::work_item
that, when later executed
in FifoWorker::operator()()
, leads to a call to
initiate()
on the event
processor object associated with processor
. The object is
silently discarded if the event processor object has been destructed before
Throws: Any exceptions propagated from Allocator::allocate()
void terminate_processor( processor_handle processor );
Requires: processor
was obtained from a call to one of
the create_processor<>()
overloads on the same
fifo_scheduler<>
object
Effects: Creates and passes to FifoWorker::queue_work_item()
an object of type FifoWorker::work_item
that, when later executed
in FifoWorker::operator()()
, leads to a call to
terminate()
on the event
processor object associated with processor
. The object is
silently discarded if the event processor object has been destructed before
Throws: Any exceptions propagated from Allocator::allocate()
void queue_event( const processor_handle & processor, const event_ptr_type & pEvent );
Requires: pEvent.get() != 0
and processor
was obtained from a call to one of the create_processor<>()
overloads on the same fifo_scheduler<>
object
Effects: Creates and passes to FifoWorker::queue_work_item()
an object of type FifoWorker::work_item
that, when later executed
in FifoWorker::operator()()
, leads to a call to
process_event( *pEvent )
on the event processor object associated with processor
. The
object is silently discarded if the event processor object has been destructed
before
Throws: Any exceptions propagated from Allocator::allocate()
void queue_work_item( const work_item & item );
Effects: Calls FifoWorker::queue_work_item( item );
Throws: Any exceptions propagated from Allocator::allocate()
void terminate();
Effects: Calls FifoWorker::terminate()
Throws: Any exceptions propagated from Allocator::allocate()
unsigned long operator()( unsigned long maxEventCount = 0 );
Requires: Must only be called from exactly one thread
Effects: Calls FifoWorker::operator()( maxEventCount )
Returns: The return value of the above call
Throws: Any exceptions propagated from Allocator::allocate()
and operator()()
of the queued FifoWorker::work_item
objects
fifo_scheduler
observer functionsbool terminated() const;
Requires: Must only be called from the thread that also calls
operator()()
Returns: FifoWorker::terminated();
exception_translator
This class template is a model of the ExceptionTranslator concept.
exception_translator
parametersTemplate parameter | Requirements | Semantics | Default |
ExceptionEvent |
A model of the Event concept | The type of event that is dispatched when an exception is propagated into the framework | exception_thrown |
exception_translator
synopsis & semanticsnamespace boost { namespace statechart { class exception_thrown : public event< exception_thrown > {}; template< class ExceptionEvent = exception_thrown > class exception_translator { public: template< class Action, class ExceptionEventHandler > result operator()( Action action, ExceptionEventHandler eventHandler ) { try { return action(); } catch( ... ) { return eventHandler( ExceptionEvent() ); } } }; } }
null_exception_translator
This class is a model of the ExceptionTranslator concept.
null_exception_translator
synopsis & semanticsnamespace boost { namespace statechart { class null_exception_translator { public: template< class Action, class ExceptionEventHandler > result operator()( Action action, ExceptionEventHandler ) { return action(); } }; } }
history_mode
Defines the history type of a state.
namespace boost { namespace statechart { enum history_mode { has_no_history, has_shallow_history, has_deep_history, has_full_history // shallow & deep }; } }
simple_state
This is the base class template for all models of the
SimpleState concept. Such models must not call any of the following simple_state<>
member functions from
their constructors:
void post_event( const intrusive_ptr< const event_base > & ); void post_event( const event_base & ); template< class HistoryContext, implementation-defined-unsigned-integer-type orthogonalPosition > void clear_shallow_history(); template< class HistoryContext, implementation-defined-unsigned-integer-type orthogonalPosition > void clear_deep_history(); outermost_context_type & outermost_context(); const outermost_context_type & outermost_context() const; template< class OtherContext > OtherContext & context(); template< class OtherContext > const OtherContext & context() const; template< class Target > Target state_cast() const; template< class Target > Target state_downcast() const; state_iterator state_begin() const; state_iterator state_end() const;
States that need to call any of these member functions from their constructors
must derive from the state
class template.
simple_state
parametersTemplate parameter | Requirements | Semantics | Default |
MostDerived |
The most-derived subtype of this class template | ||
Context |
A most-derived direct or indirect subtype of the
state_machine or
asynchronous_state_machine
class templates or a model of the SimpleState
or State concepts or an
instantiation of the
simple_state<>::orthogonal class template. Must be a complete type |
Defines the states' position in the state hierarchy | |
InnerInitial |
An mpl::list<> containing models of the
SimpleState or State
concepts or instantiations of the
shallow_history or
deep_history class templates. If
there is only a single inner initial state that is not a template
instantiation then it can also be passed directly, without wrapping it
into an mpl::list<> . The Context argument passed to the
simple_state<>
or
state<> base of each state in the list must correspond
to the orthogonal region it belongs to. That is, the first state in the
list must pass MostDerived::orthogonal< 0 > , the second
MostDerived::orthogonal< 1 > and so forth.
MostDerived::orthogonal< 0 > and MostDerived are
synonymous |
Defines the inner initial state for each orthogonal region. By default, a state does not have inner states | unspecified |
historyMode |
One of the values defined in the
history_mode
enumeration |
Defines whether the state saves shallow, deep or both histories upon exit | has_no_history |
simple_state
synopsisnamespace boost { namespace statechart { template< class MostDerived, class Context, class InnerInitial = unspecified, history_mode historyMode = has_no_history > class simple_state : implementation-defined { public: // by default, a state has no reactions typedef mpl::list<> reactions; // see template parameters template< implementation-defined-unsigned-integer-type innerOrthogonalPosition > struct orthogonal { // implementation-defined }; typedef typename Context::outermost_context_type outermost_context_type; outermost_context_type & outermost_context(); const outermost_context_type & outermost_context() const; template< class OtherContext > OtherContext & context(); template< class OtherContext > const OtherContext & context() const; template< class Target > Target state_cast() const; template< class Target > Target state_downcast() const; // a model of the StateBase concept typedef implementation-defined state_base_type; // a model of the standard Forward Iterator concept typedef implementation-defined state_iterator; state_iterator state_begin() const; state_iterator state_end() const; void post_event( const intrusive_ptr< const event_base > & ); void post_event( const event_base & ); result discard_event(); result forward_event(); result defer_event(); template< class DestinationState > result transit(); template< class DestinationState, class TransitionContext, class Event > result transit( void ( TransitionContext::* )( const Event & ), const Event & ); result terminate(); template< class HistoryContext, implementation-defined-unsigned-integer-type orthogonalPosition > void clear_shallow_history(); template< class HistoryContext, implementation-defined-unsigned-integer-type orthogonalPosition > void clear_deep_history(); static id_type static_type(); template< class CustomId > static const CustomId * custom_static_type_ptr(); template< class CustomId > static void custom_static_type_ptr( const CustomId * ); void exit() {} protected: simple_state(); ~simple_state(); }; } }
simple_state
constructor and destructorsimple_state();
Requires: The constructors of all direct and indirect subtypes
must be exception-neutral
Effects: Constructs a state object
Throws: Any exceptions propagated from Allocator::allocate()
(the template parameter passed to the base class of
outermost_context_type
)
~simple_state();
Effects: Pushes all events deferred by the state into the posted events queue
simple_state
modifier functionsvoid post_event( const intrusive_ptr< const event_base > & );
Requires: If called from a constructor of a direct or indirect
subtype then the most-derived type must directly or indirectly derive
from the state
class template. All direct and indirect
callers must be exception-neutral
Effects: Pushes the passed event into the state machine's posted events
queue
Throws: Any exceptions propagated from Allocator::allocate()
(the template parameter passed to the base class of
outermost_context_type
)
void post_event( const event_base & evt );
Requires: If called from a constructor of a direct or indirect
subtype then the most-derived type must directly or indirectly derive
from the state
class template. All direct and indirect
callers must be exception-neutral
Effects: post_event( evt.intrusive_from_this()
);
Throws: Any exceptions propagated from Allocator::allocate()
(the template parameter passed to the base class of
outermost_context_type
)
result discard_event();
Requires: Must only be called from within react
member
functions, which are called by
custom_reaction<>
instantiations. All direct and indirect callers must be exception-neutral
Effects: Instructs the state machine to discard the current event and
to continue with the processing of the remaining events (see
state_machine<>::process_event()
for
details)
Returns: A
result
object. The user-supplied react
member
function must return this object to its caller
result forward_event();
Requires: Must only be called from within react
member
functions, which are called by
custom_reaction<>
instantiations. All direct and indirect callers must be exception-neutral
Effects: Instructs the state machine to forward the current event to
the next state (see state_machine<>::process_event()
for details)
Returns: A
result
object. The user-supplied react
member
function must return this object to its caller
result defer_event();
Requires: Must only be called from within react
member
functions, which are called by
custom_reaction<>
instantiations. All
direct and indirect callers must be exception-neutral
Effects: Instructs the state machine to defer the current event and to
continue with the processing of the remaining events (see
state_machine<>::process_event()
for
details)
Returns: A
result
object. The user-supplied react
member
function must return this object to its caller
Throws: Any exceptions propagated from Allocator::allocate()
(the template parameter passed to the base class of
outermost_context_type
)
template< class DestinationState > result transit();
Requires: Must only be called from within react
member
functions, which are called by
custom_reaction<>
instantiations. All direct and indirect callers must be exception-neutral
Effects:
DestinationState
.
Innermost states are exited first. Other states are exited as soon as all
their direct and indirect inner states have been exited. The inner states of
each state are exited according to the number of their orthogonal region.
The state in the orthogonal region with the highest number is always exited
first, then the state in the region with the second-highest number and so on.exit
member function is
called. If exit
throws then steps 3 and 4 are not executedDestinationState
itself or a direct or indirect outer state of DestinationState
DestinationState
and beyond 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
state_machine<>::process_event()
for
details)Returns: A
result
object. The user-supplied react
member
function must return this object to its caller
Throws: Any exceptions propagated from:
operator new()
(used to allocate states)Allocator::allocate()
(the template
parameter passed to the base class of outermost_context_type
)exit
member functionsCaution: Inevitably destructs this state before returning to
the calling react
member function, which must therefore not
attempt to access anything except stack objects before returning to its caller
template< class DestinationState, class TransitionContext, class Event > result transit( void ( TransitionContext::* )( const Event & ), const Event & );
Requires: Must only be called from within react
member
functions, which are called by
custom_reaction<>
instantiations. All direct and indirect callers must be exception-neutral
Effects:
DestinationState
.
Innermost states are exited first. Other states are exited as soon as all
their direct and indirect inner states have been exited. The inner states of
each state are exited according to the number of their orthogonal region.
The state in the orthogonal region with the highest number is always exited
first, then the state in the region with the second-highest number and so on.exit
member function is
called. If exit
throws then steps 3 and 4 are not executedDestinationState
itself or a direct or indirect outer state of DestinationState
DestinationState
and beyond 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
state_machine<>::process_event()
for
details)Returns: A
result
object. The user-supplied react
member
function must return this object to its caller
Throws: Any exceptions propagated from:
operator new()
(used to allocate states)Allocator::allocate()
(the template
parameter passed to the base class of outermost_context_type
)exit
member functionsCaution: Inevitably destructs this state before returning to
the calling react
member function, which must therefore not
attempt to access anything except stack objects before returning to its caller
result terminate();
Requires: Must only be called from within react
member
functions, which are called by
custom_reaction<>
instantiations. All direct and indirect callers must be exception-neutral
Effects: Exits this state and all its direct and indirect
inner states. Innermost states are exited first. Other states are exited as
soon as all their direct and indirect inner states have been exited. The inner
states of each state are exited according to the number of their orthogonal
region. The state in the orthogonal region with the highest number is always
exited first, then the state in the region with the second-highest number and
so on.
The process of exiting a state consists of the following steps:
exit
member function is
called. If exit
throws then steps 3 and 4 are not executedAlso instructs the state machine to discard the current event and to
continue with the processing of the remaining events (see
state_machine<>::process_event()
for
details)
Returns: A
result
object. The user-supplied react
member
function must return this object to its caller
Throws: Any exceptions propagated from:
Allocator::allocate()
(the template
parameter passed to the base class of outermost_context_type
, used
to allocate space to save history)exit
member functionsNote: If this state is the only currently active inner state of its
direct outer state then the direct outer state is terminated also. The same
applies recursively for all indirect outer states
Caution: Inevitably destructs this state before returning to
the calling react
member function, which must therefore not
attempt to access anything except stack objects before returning to its caller
template< class HistoryContext, implementation-defined-unsigned-integer-type orthogonalPosition > void clear_shallow_history();
Requires: If called from a constructor of a direct or indirect
subtype then the most-derived type must directly or indirectly derive
from the state
class template. The historyMode
argument passed to the
simple_state<>
or
state<>
base of HistoryContext
must be equal to has_shallow_history
or has_full_history
Effects: Clears the shallow history of the orthogonal region specified
by orthogonalPosition
of the state specified by
HistoryContext
Throws: Any exceptions propagated from Allocator::allocate()
(the template parameter passed to the base class of
outermost_context_type
)
template< class HistoryContext, implementation-defined-unsigned-integer-type orthogonalPosition > void clear_deep_history();
Requires: If called from a constructor of a direct or indirect
subtype then the most-derived type must directly or indirectly derive
from the state
class template. The historyMode
argument passed to the
simple_state<>
or
state<>
base of HistoryContext
must be equal to has_deep_history
or has_full_history
Effects: Clears the deep history of the orthogonal region specified by
orthogonalPosition
of the state specified by HistoryContext
Throws: Any exceptions propagated from Allocator::allocate()
(the template parameter passed to the base class of
outermost_context_type
)
simple_state
observer functionsoutermost_context_type & outermost_context();
Requires: If called from a constructor of a direct or indirect
subtype then the most-derived type must directly or indirectly derive
from the state
class template
Returns: A reference to the outermost context, which is always the state
machine this state belongs to
const outermost_context_type & outermost_context() const;
Requires: If called from a constructor of a direct or indirect
subtype then the most-derived type must directly or indirectly derive
from the state
class template
Returns: A reference to the const outermost context, which is always the
state machine this state belongs to
template< class OtherContext > OtherContext & context();
Requires: If called from a constructor of a direct or indirect
subtype then the most-derived type must directly or indirectly derive
from the state
class template
Returns: A reference to a direct or indirect context
template< class OtherContext > const OtherContext & context() const;
Requires: If called from a constructor of a direct or indirect
subtype then the most-derived type must directly or indirectly derive
from the state
class template
Returns: A reference to a const direct or indirect context
template< class Target > Target state_cast() const;
Requires: If called from a constructor of a direct or indirect
subtype then the most-derived type must directly or indirectly derive
from the state
class template
Returns: Has exactly the same semantics as
state_machine<>::state_cast<>()
Throws: Has exactly the same semantics as
state_machine<>::state_cast<>()
Note: The result is unspecified if this function is called when the
machine is unstable
template< class Target > Target state_downcast() const;
Requires: If called from a constructor of a direct or indirect
subtype then the most-derived type must directly or indirectly derive
from the state
class template. Moreover,
state_machine<>::state_downcast<>()
requirements
also apply
Returns: Has exactly the same semantics as
state_machine<>::state_downcast<>()
Throws: Has exactly the same semantics as
state_machine<>::state_downcast<>()
Note: The result is unspecified if this function is called when the
machine is unstable
state_iterator state_begin() const;
state_iterator state_end() const;
Require: If called from a constructor of a direct or indirect
subtype then the most-derived type must directly or indirectly derive
from the state
class template
Return: Have exactly the same semantics as
state_machine<>::state_begin()
and
state_machine<>::state_end()
Note: The result is unspecified if these functions are called
when the machine is unstable
simple_state
static functionsstatic id_type static_type();
Returns: A value unambiguously identifying the type of
MostDerived
Note: id_type
values are comparable with
operator==()
and operator!=()
. An unspecified collating
order can be established with std::less< id_type >
template< class CustomId > static const CustomId * custom_static_type_ptr();
Requires: If a custom type identifier has been set then
CustomId
must match the type of the previously set pointer
Returns: The pointer to the custom type identifier for MostDerived
or 0
Note: This function is not available if
BOOST_STATECHART_USE_NATIVE_RTTI
is defined
template< class CustomId > static void custom_static_type_ptr( const CustomId * );
Effects: Sets the pointer to the custom type identifier for
MostDerived
Note: This function is not available if
BOOST_STATECHART_USE_NATIVE_RTTI
is defined
state
This is the base class template for all models of the
State concept. Such models typically need to call at least one of the
following simple_state<>
member functions from their constructors:
void post_event( const intrusive_ptr< const event_base > & ); void post_event( const event_base & ); template< class HistoryContext, implementation-defined-unsigned-integer-type orthogonalPosition > void clear_shallow_history(); template< class HistoryContext, implementation-defined-unsigned-integer-type orthogonalPosition > void clear_deep_history(); outermost_context_type & outermost_context(); const outermost_context_type & outermost_context() const; template< class OtherContext > OtherContext & context(); template< class OtherContext > const OtherContext & context() const; template< class Target > Target state_cast() const; template< class Target > Target state_downcast() const; state_iterator state_begin() const; state_iterator state_end() const;
States that do not need to call any of these member functions from their
constructors should rather derive from the
simple_state
class template,
what saves the implementation of the forwarding constructor.
state
synopsisnamespace boost { namespace statechart { template< class MostDerived, class Context, class InnerInitial = unspecified, history_mode historyMode = has_no_history > class state : public simple_state< MostDerived, Context, InnerInitial, historyMode > { protected: struct my_context { // implementation-defined }; typedef state my_base; state( my_context ctx ); ~state(); }; } }
Direct and indirect subtypes of state<>
must provide a
constructor with the same signature as the state<>
constructor,
forwarding the context parameter.
shallow_history
This class template is used to specify a shallow history transition target or a shallow history inner initial state.
shallow_history
parametersTemplate parameter | Requirements | Semantics |
DefaultState |
A model of the SimpleState or
State concepts. The type passed as Context argument to the
simple_state<>
or
state<> base of DefaultState
must itself pass has_shallow_history
or has_full_history as historyMode argument to its
simple_state<>
or
state<> base |
The state that is entered if shallow history is not available |
shallow_history
synopsisnamespace boost { namespace statechart { template< class DefaultState > class shallow_history { // implementation-defined }; } }
deep_history
This class template is used to specify a deep history transition target or a deep history inner initial state. The current deep history implementation has some limitations.
deep_history
parametersTemplate parameter | Requirements | Semantics |
DefaultState |
A model of the SimpleState or
State concepts. The type passed as Context argument to the
simple_state<>
or
state<> base of DefaultState
must itself pass has_deep_history
or has_full_history as historyMode argument to its
simple_state<>
or
state<> base |
The state that is entered if deep history is not available |
deep_history
synopsisnamespace boost { namespace statechart { template< class DefaultState > class deep_history { // implementation-defined }; } }
event_base
This is the common base of all events.
event_base
synopsisnamespace boost { namespace statechart { class event_base { public: intrusive_ptr< const event_base > intrusive_from_this() const; typedef implementation-defined id_type; id_type dynamic_type() const; template< typename CustomId > const CustomId * custom_dynamic_type_ptr() const; protected: event_base( unspecified-parameter ); virtual ~event_base(); }; } }
event_base
constructor and destructorevent_base( unspecified-parameter );
Effects: Constructs the common base portion of an event
virtual ~event_base();
Effects: Destructs the common base portion of an event
event_base
observer functionsintrusive_ptr< const event_base > intrusive_from_this() const;
Returns: If this
is already referenced by an
intrusive_ptr<>
, returns another intrusive_ptr< const event_base >
referencing this
. Otherwise, returns an intrusive_ptr<
const event_base >
referencing a newly created copy of the most-derived object
id_type dynamic_type() const;
Returns: A value unambiguously identifying the most-derived type
Note: id_type
values are comparable with
operator==()
and operator!=()
. An unspecified collating
order can be established with std::less< id_type >
template< typename CustomId > const CustomId * custom_dynamic_type_ptr() const;
Requires: If a custom type identifier has been set then
CustomId
must match the type of the previously set pointer
Returns: A pointer to the custom type identifier or 0
Note: This function is not available if
BOOST_STATECHART_USE_NATIVE_RTTI
is defined
event
This is the base class template of all events.
event
synopsisnamespace boost { namespace statechart { template< class MostDerived > class event : implementation-defined { public: static id_type static_type(); template< class CustomId > static const CustomId * custom_static_type_ptr(); template< class CustomId > static void custom_static_type_ptr( const CustomId * ); protected: event(); virtual ~event(); }; } }
event
constructor and destructorevent();
Effects: Constructs an event
virtual ~event();
Effects: Destructs an event
event
static functionsstatic id_type static_type();
Returns: A value unambiguously identifying the type of
MostDerived
Note: id_type
values are comparable with
operator==()
and operator!=()
. An unspecified collating
order can be established with std::less< id_type >
template< class CustomId > static const CustomId * custom_static_type_ptr();
Requires: If a custom type identifier has been set then
CustomId
must match the type of the previously set pointer
Returns: The pointer to the custom type identifier for MostDerived
or 0
Note: This function is not available if
BOOST_STATECHART_USE_NATIVE_RTTI
is defined
template< class CustomId > static void custom_static_type_ptr( const CustomId * );
Effects: Sets the pointer to the custom type identifier for
MostDerived
Note: This function is not available if
BOOST_STATECHART_USE_NATIVE_RTTI
is defined
transition
This class template is used to specify a transition reaction.
Instantiations of this template can appear in the reactions
member typedef
in models of the SimpleState
and State concepts.
transition
parametersTemplate parameter | Requirements | Semantics | Default |
Event |
A model of the Event concept | The event triggering the transition | |
Destination |
A model of the SimpleState
or State concepts
or an instantiation of the
shallow_history or
deep_history class
templates. The source state (the state for which this transition is
defined) and Destination must have a common direct or
indirect context |
The destination state to make a transition to | |
TransitionContext |
A common context of the source and Destination
state |
The state of which the transition action is a member | unspecified |
pTransitionAction |
A pointer to a member function of TransitionContext .
The member function must accept a const Event & parameter and
return void |
The transition action that is executed during the transition. By default no transition action is executed | unspecified |
transition
synopsisnamespace boost { namespace statechart { template< class Event, class Destination, class TransitionContext = unspecified, void ( TransitionContext::*pTransitionAction )( const Event & ) = unspecified > class transition { // implementation-defined }; } }
transition
semanticsWhen executed, one of the following calls to a member function of the state for which the reaction was defined is made:
transit< Destination >()
, if no
transition action was specifiedtransit< Destination >( pTransitionAction,
currentEvent )
, if a transition action was specifiedin_state_reaction
This class template is used to specify an in-state reaction.
Instantiations of this template can appear in the reactions
member typedef
in models of the SimpleState
and State concepts.
in_state_reaction
parametersTemplate parameter | Requirements | Semantics |
Event |
A model of the Event concept | The event triggering the in-state reaction |
ReactionContext |
Either the state defining the in-state reaction itself or one of it direct or indirect contexts | The state of which the action is a member |
pAction |
A pointer to a member function of ReactionContext .
The member function must accept a const Event & parameter and
return void |
The action that is executed during the in-state reaction |
in_state_reaction
synopsisnamespace boost { namespace statechart { template< class Event, class ReactionContext, void ( ReactionContext::*pAction )( const Event & ) > class in_state_reaction { // implementation-defined }; } }
in_state_reaction
semanticsWhen executed, pAction
is called, passing the triggering event
as the only argument.
termination
This class template is used to specify a termination reaction. Instantiations
of this template can appear in the reactions
member typedef
in models of the SimpleState
and State concepts.
termination
parametersTemplate parameter | Requirements | Semantics |
Event |
A model of the Event concept | The event triggering the termination |
termination
synopsisnamespace boost { namespace statechart { template< class Event > class termination { // implementation-defined }; } }
termination
semanticsWhen executed, a call is made to the
terminate
member function of the
state for which the reaction was defined.
deferral
This class template is used to specify a deferral reaction. Instantiations of
this template can appear in the reactions
member typedef
in models of the SimpleState
and State concepts.
deferral
parametersTemplate parameter | Requirements | Semantics |
Event |
A model of the Event concept | The event triggering the deferral |
deferral
synopsisnamespace boost { namespace statechart { template< class Event > class deferral { // implementation-defined }; } }
deferral
semanticsWhen executed, a call is made to the
defer_event
member function of the state for which the reaction was
defined.
custom_reaction
This class template is used to specify a custom reaction. Instantiations of
this template can appear in the reactions
member typedef
in models of the SimpleState
and State concepts.
custom_reaction
parametersTemplate parameter | Requirements | Semantics |
Event |
A model of the Event concept | The event triggering the custom reaction |
custom_reaction
synopsisnamespace boost { namespace statechart { template< class Event > class custom_reaction { // implementation-defined }; } }
custom_reaction
semanticsWhen executed, a call is made to the user-supplied react
member function of the state for which the reaction was defined. The
react
member function must have the following signature:
result react( const Event & );
and must call exactly one of the following reaction functions and return
the obtained result
object:
result discard_event(); result forward_event(); result defer_event(); template< class DestinationState > result transit(); template< class DestinationState, class TransitionContext, class Event > result transit( void ( TransitionContext::* )( const Event & ), const Event & ); result terminate();
result
Defines the nature of the reaction taken in a user-supplied react
member function (called when a
custom_reaction
is
executed). Objects of this type are always obtained by calling one of the
reaction functions and must be returned from the react
member
function immediately.
namespace boost { namespace statechart { class result { public: result( const result & other ); ~result(); private: // Result objects are not assignable result & operator=( const result & other ); }; } }
result
constructor and destructorresult( const result & other );
Requires: other
is not consumed
Effects: Copy-constructs a new result
object and marks
other
as consumed. That is, result
has destructive
copy semantics
~result();
Requires: this
is marked as consumed
Effects: Destructs the result object
Revised 19 June, 2005
© Copyright Andreas Huber Dönni 2003-2005. The link refers to a spam honeypot. Please remove the words spam and trap to obtain my real address.
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)