Planet

navi

home

PPS

about

screenshots

download

development

forum

Context Navigation

source: downloads/boost_1_34_1/libs/statechart/doc/faq.html @ 33

Last change on this file since 33 was 29, checked in by landauf, 16 years ago
updated boost from 1_33_1 to 1_34_1
File size: 28.7 KB

Line
1	<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
2
3	<html>
4	<head>
5	<meta http-equiv="Content-Language" content="en-us">
6	<meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
7	<meta name="GENERATOR" content="Microsoft FrontPage 6.0">
8	<meta name="ProgId" content="FrontPage.Editor.Document">
9	<link rel="stylesheet" type="text/css" href="../../../boost.css">
10
11	<title>The Boost Statechart Library - FAQ</title>
12	</head>
13
14	<body link="#0000FF" vlink="#800080">
15	<table border="0" cellpadding="7" cellspacing="0" width="100%" summary=
16	"header">
17	<tr>
18	<td valign="top" width="300">
19	<h3><a href="../../../index.htm"><img alt="C++ Boost" src=
20	"../../../boost.png" border="0" width="277" height="86"></a></h3>
21	</td>
22
23	<td valign="top">
24	<h1 align="center">The Boost Statechart Library</h1>
25
26	<h2 align="center">Frequently Asked Questions (FAQs)</h2>
27	</td>
28	</tr>
29	</table>
30	<hr>
31
32	<dl class="page-index">
33	<dt><a href="#StateLocalStorage">What's so cool about state-local
34	storage?</a></dt>
35
36	<dt><a href="#HideInnerWorkings">How can I hide the inner workings of a
37	state machine from its clients?</a></dt>
38
39	<dt><a href="#MachineInheritance">Is it possible to inherit from a given
40	state machine and modify its layout in the subclass?</a></dt>
41
42	<dt><a href="#Uml2">What about UML2.0 features?</a></dt>
43
44	<dt><a href="#EmbeddedApplications">Is Boost.Statechart suitable for
45	embedded applications?</a></dt>
46
47	<dt><a href="#HardRealtime">Is your library suitable for applications
48	with hard real-time requirements?</a></dt>
49
50	<dt><a href="#TemplatedStates">With templated states I get an error that
51	'inner_context_type' is not defined. What's wrong?</a></dt>
52
53	<dt><a href="#CompilerError">My compiler reports an error in the library
54	code. Is this a bug in Boost.Statechart?</a></dt>
55
56	<dt><a href="#Dll">How can I compile a state machine into a dynamic link
57	library (DLL)?</a></dt>
58
59	<dt><a href="#PolymorphicEvents">Does Boost.Statechart support
60	polymorphic events?</a></dt>
61
62	<dt><a href="#WrongExitActionOrder">Why are exit-actions called in the
63	wrong order when I use multiple inheritance?</a></dt>
64	</dl>
65
66	<h2><a name="StateLocalStorage" id="StateLocalStorage">What's so cool about
67	state-local storage?</a></h2>
68
69	<p>This is best explained with an example:</p>
70	<pre>
71	struct Active;
72	struct Stopped;
73	struct Running;
74	struct StopWatch : sc::state_machine< StopWatch, Active >
75	{
76	// startTime_ remains uninitialized, because there is no reasonable default
77	StopWatch() : elapsedTime_( 0.0 ) {}
78	~StopWatch()
79	{
80	terminate();
81	}
82
83	double ElapsedTime() const
84	{
85	// Ugly switch over the current state.
86	if ( state_cast< const Stopped * >() != 0 )
87	{
88	return elapsedTime_;
89	}
90	else if ( state_cast< const Running * >() != 0 )
91	{
92	return elapsedTime_ + std::difftime( std::time( 0 ), startTime_ );
93	}
94	else // we're terminated
95	{
96	throw std::bad_cast();
97	}
98	}
99
100	// elapsedTime_ is only meaningful when the machine is not terminated
101	double elapsedTime_;
102	// startTime_ is only meaningful when the machine is in Running
103	std::time_t startTime_;
104	};
105
106	struct Active : sc::state< Active, StopWatch, Stopped >
107	{
108	typedef sc::transition< EvReset, Active > reactions;
109
110	Active( my_context ctx ) : my_base( ctx )
111	{
112	outermost_context().elapsedTime_ = 0.0;
113	}
114	};
115
116	struct Running : sc::state< Running, Active >
117	{
118	typedef sc::transition< EvStartStop, Stopped > reactions;
119
120	Running( my_context ctx ) : my_base( ctx )
121	{
122	outermost_context().startTime_ = std::time( 0 );
123	}
124
125	~Running()
126	{
127	outermost_context().elapsedTime_ +=
128	std::difftime( std::time( 0 ), outermost_context().startTime_ );
129	}
130	};
131
132	struct Stopped : sc::simple_state< Stopped, Active >
133	{
134	typedef sc::transition< EvStartStop, Running > reactions;
135	};
136	</pre>
137
138	<p>This StopWatch does not make any use of state-local storage while
139	implementing the same behavior as the <a href=
140	"tutorial.html#BasicTopicsAStopWatch">tutorial StopWatch</a>. Even though
141	this code is probably easier to read for the untrained eye, it does have a
142	few problems that are absent in the original:</p>
143
144	<ul>
145	<li>This StopWatch class has data members that have a meaningful value
146	only if the state machine happens to be in a certain state. That is, the
147	lifetimes of these variables are not identical with the one of the
148	StopWatch object containing them. Since the lifetimes are managed by the
149	entry and exit actions of states, we need to use an ugly switch over the
150	current state (see <code>StopWatch::ElapsedTime()</code>) if we want to
151	access them from a context where the current state is unclear. This
152	essentially duplicates some of the state logic of the FSM. Therefore,
153	whenever we need to change the layout of the state machine we will likely
154	also need to change the ugly switch. Even worse, if we forget to change
155	the switch, the code will probably still compile and maybe even silently
156	do the wrong thing. Note that this is impossible with the version in the
157	tutorial, which will at least throw an exception and often just refuse to
158	compile. Moreover, for the tutorial StopWatch there's a much higher
159	chance that a programmer will get a change correct the first time since
160	the code that calculates the elapsed time is located close to the code
161	that updates the variables</li>
162
163	<li>We need to change the StopWatch class whenever we want to introduce a
164	new variable or change the type of an already existing variable. That is,
165	many changes in the FSM will likely lead to a change in the StopWatch
166	class. In all FSMs that do not employ state-local storage, the
167	<code>state_machine<></code> subtype will therefore be a change
168	hotspot, which is a pretty sure indicator for a bad design</li>
169	</ul>
170
171	<p>Both points are not much of a problem in a small example like this,
172	which can easily be implemented in a single translation unit by a single
173	programmer. However, they quickly become a major problem for a big complex
174	machine spread over multiple translation units, which are possibly even
175	maintained by different programmers.</p>
176
177	<h2><a name="HideInnerWorkings" id="HideInnerWorkings">How can I hide the
178	inner workings of a state machine from its clients?</a></h2>
179
180	<p>To see why and how this is possible it is important to recall the
181	following facts:</p>
182
183	<ul>
184	<li>Member functions of a C++ class template are instantiated at the
185	point where they're actually called. If the function is never called, it
186	will not be instantiated and not a single assembly instruction will ever
187	be generated</li>
188
189	<li>The <code>InitialState</code> template parameter of
190	<code>sc::state_machine</code> can be an incomplete type (i.e. forward
191	declared)</li>
192	</ul>
193
194	<p>The class template member function
195	<code>state_machine<>::initiate()</code> creates an object of the
196	initial state. So, the definition of this state must be known before the
197	compiler reaches the point where <code>initiate()</code> is called. To be
198	able to hide the initial state of a state machine in a .cpp file we must
199	therefore no longer let clients call <code>initiate()</code>. Instead, we
200	do so in the .cpp file, at a point where the full definition of the initial
201	state is known.</p>
202
203	<p>Example:</p>
204
205	<p>StopWatch.hpp:</p>
206	<pre>
207	// define events ...
208
209	struct Active; // the only visible forward
210	struct StopWatch : sc::state_machine< StopWatch, Active >
211	{
212	StopWatch();
213	};
214	</pre>
215
216	<p>StopWatch.cpp:</p>
217	<pre>
218	struct Stopped;
219	struct Active : sc::simple_state< Active, StopWatch, Stopped >
220	{
221	typedef sc::transition< EvReset, Active > reactions;
222	};
223
224	struct Running : sc::simple_state< Running, Active >
225	{
226	typedef sc::transition< EvStartStop, Stopped > reactions;
227	};
228
229	struct Stopped : sc::simple_state< Stopped, Active >
230	{
231	typedef sc::transition< EvStartStop, Running > reactions;
232	};
233
234	StopWatch::StopWatch()
235	{
236	// For example, we might want to ensure that the state
237	// machine is already started after construction.
238	// Alternatively, we could add our own initiate() function
239	// to StopWatch and call the base class initiate() in the
240	// implementation.
241	<b>initiate();</b>
242	}
243	</pre>
244
245	<h2><a name="MachineInheritance" id="MachineInheritance">Is it possible to
246	inherit from a given state machine and modify its layout in the
247	subclass?</a></h2>
248
249	<p>Yes, but contrary to what some FSM code generators allow,
250	Boost.Statechart machines can do so only in a way that was foreseen by the
251	designer of the base state machine:</p>
252	<pre>
253	struct EvStart : sc::event< EvStart > {};
254
255	struct Idle;
256	struct PumpBase : sc::state_machine< PumpBase, Idle >
257	{
258	<b>virtual sc::result react(
259	</b> <b>Idle & idle, const EvStart & ) const;
260	</b>};
261
262	struct Idle : sc::simple_state< Idle, PumpBase >
263	{
264	typedef sc::custom_reaction< EvStart > reactions;
265
266	sc::result react( const EvStart & evt )
267	{
268	<b>return context< PumpBase >().react( *this, evt );</b>
269	}
270	};
271
272	struct Running : sc::simple_state< Running, PumpBase > {};
273
274	sc::result PumpBase::react(
275	Idle & idle, const EvStart & ) const
276	{
277	<b>return idle.transit< Running >();
278	</b>}
279
280
281	struct MyRunning : sc::simple_state< MyRunning, PumpBase > {};
282
283	struct MyPump : PumpBase
284	{
285	virtual sc::result react(
286	Idle & idle, const EvStart & ) const
287	{
288	<b>return idle.transit< MyRunning >();
289	</b> }
290	};
291	</pre>
292
293	<h2><a name="Uml2" id="Uml2">What about UML 2.0 features?</a></h2>
294
295	<p>The library was designed before 2.0 came along. Therefore, if not
296	explicitly noted otherwise, the library implements the behavior mandated by
297	the UML1.5 standard. Here's an incomplete list of differences between the
298	2.0 semantics & Boost.Statechart semantics:</p>
299
300	<ul>
301	<li>All transitions are always external. Local transitions are not
302	supported at all. Unfortunately, the UML2.0 specifications are not
303	entirely clear how local transitions are supposed to work, see <a href=
304	"http://thread.gmane.org/gmane.comp.lib.boost.user/18641">here</a> for
305	more information</li>
306
307	<li>There is no direct support for the UML2.0 elements entry point and
308	exit point. However, both can easily be simulated, the former with a
309	typedef and the latter with a state that is a template (with the
310	transition destination as a template parameter)</li>
311	</ul>
312
313	<h2><a name="EmbeddedApplications" id="EmbeddedApplications">Is
314	Boost.Statechart suitable for embedded applications?</a></h2>
315
316	<p>It depends. As explained under <a href=
317	"performance.html#SpeedVersusScalabilityTradeoffs">Speed versus scalability
318	tradeoffs</a> on the Performance page, the virtually limitless scalability
319	offered by this library does have its price. Especially small and simple
320	FSMs can easily be implemented so that they consume fewer cycles and less
321	memory and occupy less code space in the executable. Here are some
322	obviously <b>very rough</b> estimates:</p>
323
324	<ul>
325	<li>For a state machine with at most one simultaneously active state
326	(that is, the machine is flat and does not have orthogonal regions) with
327	trivial actions, customized memory management and compiled with a good
328	optimizing compiler, a Pentium 4 class CPU should not spend more than
329	1000 cycles inside <code>state_machine<>::process_event()</code>.
330	This worst-case time to process one event scales more or less linearly
331	with the number of simultaneously active states for more complex state
332	machines, with the typical average being much lower than that. So, a
333	fairly complex machine with at most 10 simultaneously active states
334	running on a 100MHz CPU should be able to process more than 10'000 events
335	per second</li>
336
337	<li>A single state machine object uses typically less than 1KB of memory,
338	even if it implements a very complex machine</li>
339
340	<li>For code size, it is difficult to give a concrete guideline but tests
341	with the BitMachine example suggest that code size scales more or less
342	linearly with the number of states (transitions seem to have only little
343	impact). When compiled with MSVC7.1 on Windows, 32 states and 224
344	transitions seem to fit in ~108KB executable code (with all optimizations
345	turned on).<br>
346	Moreover, the library can be compiled with C++ RTTI and exception
347	handling turned off, resulting in significant savings on most
348	platforms</li>
349	</ul>
350
351	<p>As mentioned above, these are very rough estimates derived from the use
352	of the library on a desktop PC, so they should only be used to decide
353	whether there is a point in making your own performance tests on your
354	target platform.</p>
355
356	<h2><a name="HardRealtime" id="HardRealtime">Is your library suitable for
357	applications with hard real-time requirements?</a></h2>
358
359	<p>Yes. Out of the box, the only operations taking potentially
360	non-deterministic time that the library performs are calls to
361	<code>std::allocator<></code> member functions and
362	<code>dynamic_cast</code>s. <code>std::allocator<></code> member
363	function calls can be avoided by passing a custom allocator to
364	<code>event<></code>, <code>state_machine<></code>,
365	<code>asynchronous_state_machine<></code>,
366	<code>fifo_scheduler<></code> and <code>fifo_worker<></code>.
367	<code>dynamic_cast</code>s can be avoided by not calling the
368	<code>state_cast<></code> member functions of
369	<code>state_machine<></code>, <code>simple_state<></code> and
370	<code>state<></code> but using the deterministic variant
371	<code>state_downcast<></code> instead.</p>
372
373	<h2><a name="TemplatedStates" id="TemplatedStates">With templated states I
374	get an error that 'inner_context_type' is not defined. What's
375	wrong?</a></h2>
376
377	<p>The following code generates such an error:</p>
378	<pre>
379	#include <boost/statechart/state_machine.hpp>
380	#include <boost/statechart/simple_state.hpp>
381
382	namespace sc = boost::statechart;
383
384	template< typename X > struct A;
385	struct Machine : sc::state_machine< Machine, A< int > > {};
386
387	template< typename X > struct B;
388	template< typename X >
389	struct A : sc::simple_state< A< X >, Machine, B< X > > {};
390
391	template< typename X >
392	struct B : sc::simple_state< B< X >, A< X > > {};
393
394	int main()
395	{
396	Machine machine;
397	machine.initiate();
398	return 0;
399	}
400	</pre>
401
402	<p>If the templates <code>A</code> and <code>B</code> are replaced with
403	normal types, the above code compiles without errors. This is rooted in the
404	fact that C++ treats forward-declared templates differently than
405	forward-declared types. Namely, the compiler tries to access member
406	typedefs of <code>B< X ></code> at a point where the template has not
407	yet been defined. Luckily, this can easily be avoided by putting all inner
408	initial state arguments in an <code>mpl::list<></code>, as
409	follows:</p>
410	<pre>
411	struct A : sc::simple_state<
412	A< X >, Machine, mpl::list< B< X > > > {};
413	</pre>
414
415	<p>See <a href=
416	"http://article.gmane.org/gmane.comp.lib.boost.devel/128741">this post</a>
417	for technical details.</p>
418
419	<h2><a name="CompilerError" id="CompilerError">My compiler reports an error
420	in the library code. Is this a bug in Boost.Statechart?</a></h2>
421
422	<p>Probably not. There are several possible reasons for such compile-time
423	errors:</p>
424
425	<ol>
426	<li>Your compiler is too buggy to compile the library, see <a href=
427	"index.html#SupportedPlatforms">here</a> for information on the status of
428	your compiler. If you absolutely must use such a compiler for your
429	project, I'm afraid Boost.Statechart is not for you.</li>
430
431	<li>The error is reported on a line similar to the following:
432	<pre>
433	BOOST_STATIC_ASSERT( ( mpl::less<
434	orthogonal_position,
435	typename context_type::no_of_orthogonal_regions >::value ) );
436	</pre>Most probably, there is an error in your code. The library has many
437	such compile-time assertions to ensure that invalid state machines cannot be
438	compiled (for an idea what kinds of errors are reported at compile time, see
439	the compile-fail tests). Above each of these assertions there is a comment
440	explaining the problem. On almost all current compilers an error in template
441	code is accompanied by the current "instantiation stack". Very much like the
442	call stack you see in the debugger, this "instantiation stack" allows you to
443	trace the error back through instantiations of library code until you hit the
444	line of your code that causes the problem. As an example, here's the MSVC7.1
445	error message for the code in InconsistentHistoryTest1.cpp:
446	<pre>
447	...\boost\statechart\shallow_history.hpp(34) : error C2027: use of undefined type 'boost::STATIC_ASSERTION_FAILURE<x>'
448	with
449	[
450	x=false
451	]
452	...\boost\statechart\shallow_history.hpp(34) : see reference to class template instantiation 'boost::STATIC_ASSERTION_FAILURE<x>' being compiled
453	with
454	[
455	x=false
456	]
457	...\boost\statechart\simple_state.hpp(861) : see reference to class template instantiation 'boost::statechart::shallow_history<DefaultState>' being compiled
458	with
459	[
460	DefaultState=B
461	]
462	...\boost\statechart\simple_state.hpp(599) : see reference to function template instantiation 'void boost::statechart::simple_state<MostDerived,Context,InnerInitial>::deep_construct_inner_impl_non_empty::deep_construct_inner_impl<InnerList>(const boost::statechart::simple_state<MostDerived,Context,InnerInitial>::inner_context_ptr_type &,boost::statechart::simple_state<MostDerived,Context,InnerInitial>::outermost_context_base_type &)' being compiled
463	with
464	[
465	MostDerived=A,
466	Context=InconsistentHistoryTest,
467	InnerInitial=boost::mpl::list<boost::statechart::shallow_history<B>>,
468	InnerList=boost::statechart::simple_state<A,InconsistentHistoryTest,boost::mpl::list<boost::statechart::shallow_history<B>>>::inner_initial_list
469	]
470	...\boost\statechart\simple_state.hpp(567) : see reference to function template instantiation 'void boost::statechart::simple_state<MostDerived,Context,InnerInitial>::deep_construct_inner<boost::statechart::simple_state<MostDerived,Context,InnerInitial>::inner_initial_list>(const boost::statechart::simple_state<MostDerived,Context,InnerInitial>::inner_context_ptr_type &,boost::statechart::simple_state<MostDerived,Context,InnerInitial>::outermost_context_base_type &)' being compiled
471	with
472	[
473	MostDerived=A,
474	Context=InconsistentHistoryTest,
475	InnerInitial=boost::mpl::list<boost::statechart::shallow_history<B>>
476	]
477	...\boost\statechart\simple_state.hpp(563) : while compiling class-template member function 'void boost::statechart::simple_state<MostDerived,Context,InnerInitial>::deep_construct(const boost::statechart::simple_state<MostDerived,Context,InnerInitial>::context_ptr_type & ,boost::statechart::simple_state<MostDerived,Context,InnerInitial>::outermost_context_base_type &)'
478	with
479	[
480	MostDerived=A,
481	Context=InconsistentHistoryTest,
482	InnerInitial=boost::mpl::list<boost::statechart::shallow_history<B>>
483	]
484	...\libs\statechart\test\InconsistentHistoryTest1.cpp(29) : see reference to class template instantiation 'boost::statechart::simple_state<MostDerived,Context,InnerInitial>' being compiled
485	with
486	[
487	MostDerived=A,
488	Context=InconsistentHistoryTest,
489	InnerInitial=boost::mpl::list<boost::statechart::shallow_history<B>>
490	]
491	</pre>Depending on the IDE you use, it is possible that you need to switch to
492	another window to see this full error message (e.g. for Visual Studio 2003,
493	you need to switch to the Output window). Starting at the top and going down
494	the list of instantiations you see that each of them is accompanied by a file
495	name and a line number. Ignoring all files belonging to the library, we find
496	the culprit close to the bottom in file InconsistentHistoryTest1.cpp on line
497	29.
498	</li>
499
500	<li>The error is reported on a line nowhere near a BOOST_STATIC_ASSERT.
501	Use the technique described under point 2 to see what line of your code
502	causes the problem. If your code is correct then you've found a bug in
503	either the compiler or Boost.Statechart. Please <a href=
504	"contact.html">send me</a> a small but complete program showing the
505	problem. Thank you!</li>
506	</ol>
507
508	<h2><a name="Dll" id="Dll">How can I compile a state machine into a dynamic
509	link library (DLL)?</a></h2>
510
511	<p>Invisible to the user, the library uses static data members to implement
512	its own speed-optimized RTTI-mechanism for <code>event<></code> and
513	<code>simple_state<></code> subtypes. Whenever such a subtype is
514	defined in a header file and then included in multiple TUs, the linker
515	later needs to eliminate the duplicate definitions of static data members.
516	This usually works flawlessly as long as all these TUs are
517	<b>statically</b> linked into the same binary. It is a lot more complex
518	when DLLs are involved. The TuTest*.?pp files illustrate this:</p>
519
520	<ul>
521	<li><a href="../test/TuTest.hpp">TuTest.hpp</a>: Instantiates a class
522	template containing a static data member</li>
523
524	<li><a href="../test/TuTest.cpp">TuTest.cpp</a>: Includes TuTest.hpp and
525	is compiled into a DLL</li>
526
527	<li><a href="../test/TuTestMain.cpp">TuTestMain.cpp</a>: Includes
528	TuTest.hpp and is compiled into an executable</li>
529	</ul>
530
531	<p>Without any precautions (e.g. <code>__declspec(dllexport)</code> on MSVC
532	compatible compilers), on most platforms both binaries (exe & dll) now
533	contain their own instance of the static data member. Since the RTTI
534	mechanism assumes that there is exactly one object of that member at
535	runtime, the mechanism fails spectacularly when the process running the exe
536	also loads the dll. Different platforms deal differently with this
537	problem:</p>
538
539	<ul>
540	<li>On some platforms (e.g. MinGW) there simply doesn't seem to be a way
541	to enforce that such a member only exists once at runtime. Therefore, the
542	internal RTTI mechanism cannot be used reliably in conjunction with DLLs.
543	Disabling it by defining <a href=
544	"configuration.html#ApplicationDefinedMacros">BOOST_STATECHART_USE_NATIVE_RTTI</a>
545	in all TUs will <b>usually</b> work around the problem</li>
546
547	<li>MSVC-compatible compilers support <code>__declspec(dllimport)</code>
548	and <code>__declspec(dllexport)</code>, which allow to define exactly
549	what needs to be loaded from a DLL (see TuTest for an example how to do
550	this). Therefore, the internal RTTI mechanism can be used but care must
551	be taken to correctly export and import all <code>event<></code>
552	and <code>simple_state<></code> subtypes defined in headers that
553	are compiled into more than one binary. Alternatively, of course <a href=
554	"configuration.html#ApplicationDefinedMacros">BOOST_STATECHART_USE_NATIVE_RTTI</a>
555	can also be used to save the work of importing and exporting</li>
556	</ul>
557
558	<h2><a name="PolymorphicEvents" id="PolymorphicEvents">Does
559	Boost.Statechart support polymorphic events?</a></h2>
560
561	<p>No. Although events can be derived from each other to write common code
562	only once, <a href="definitions.html#Reaction">reactions</a> can only be
563	defined for most-derived events.</p>
564
565	<p>Example:</p>
566	<pre>
567	template< class MostDerived >
568	struct EvButtonPressed : sc::event< MostDerived >
569	{
570	// common code
571	};
572
573	struct EvPlayButtonPressed :
574	EvButtonPressed< EvPlayButtonPressed > {};
575	struct EvStopButtonPressed :
576	EvButtonPressed< EvStopButtonPressed > {};
577	struct EvForwardButtonPressed :
578	EvButtonPressed< EvForwardButtonPressed > {};
579
580	/* ... */
581
582	// We want to turn the player on, no matter what button we
583	// press in the Off state. Although we can write the reaction
584	// code only once, we must mention all most-derived events in
585	// the reaction list.
586	struct Off : sc::simple_state< Off, Mp3Player >
587	{
588	typedef mpl::list<
589	sc::custom_reaction< EvPlayButtonPressed >,
590	sc::custom_reaction< EvStopButtonPressed >,
591	sc::custom_reaction< EvForwardButtonPressed >
592	> reactions;
593
594	template< class MostDerived >
595	sc::result react( const EvButtonPressed< MostDerived > & )
596	{
597	// ...
598	}
599	};
600	</pre>
601
602	<h2><a name="WrongExitActionOrder" id="WrongExitActionOrder">Why are
603	exit-actions called in the wrong order when I use multiple
604	inheritance?</a></h2>
605
606	<p><b>Update</b>: The implementation has changed considerably in this area.
607	It is still possible to get this behavior under rare circumstances (when an
608	action propagates an exception in a state machine with orthogonal regions
609	<b>and</b> if the statechart layout satisfies certain conditions), but it
610	can no longer be demonstrated with the example program below. However, the
611	described workaround is still valid and ensures that this behavior will
612	never show up.</p>
613
614	<p>They definitely aren't for the <code>simple_state<></code> and
615	<code>state<></code> subtypes, but the destructors of additional
616	bases might be called in construction order (rather than the reverse
617	construction order):</p>
618	<pre>
619	#include <boost/statechart/state_machine.hpp>
620	#include <boost/statechart/simple_state.hpp>
621
622	namespace sc = boost::statechart;
623
624	class EntryExitDisplayer
625	{
626	protected:
627	EntryExitDisplayer( const char * pName ) :
628	pName_( pName )
629	{
630	std::cout << pName_ << " entered\n";
631	}
632
633	~EntryExitDisplayer()
634	{
635	std::cout << pName_ << " exited\n";
636	}
637
638	private:
639	const char * const pName_;
640	};
641
642	struct Outer;
643	struct Machine : sc::state_machine< Machine, Outer > {};
644	struct Inner;
645	struct Outer : EntryExitDisplayer, sc::simple_state<
646	Outer, Machine, Inner >
647	{
648	Outer() : EntryExitDisplayer( "Outer" ) {}
649	};
650
651	struct Inner : EntryExitDisplayer,
652	sc::simple_state< Inner, Outer >
653	{
654	Inner() : EntryExitDisplayer( "Inner" ) {}
655	};
656
657	int main()
658	{
659	Machine myMachine;
660	myMachine.initiate();
661	return 0;
662	}
663	</pre>
664
665	<p>This program will produce the following output:</p>
666	<pre>
667	Outer entered
668	Inner entered
669	Outer exited
670	Inner exited
671	</pre>
672
673	<p>That is, the <b><code>EntryExitDisplayer</code> base class portion</b>
674	of <code>Outer</code> is destructed before the one of <code>Inner</code>
675	although <code>Inner::~Inner()</code> is called before
676	<code>Outer::~Outer()</code>. This somewhat counter-intuitive behavior is
677	caused by the following facts:</p>
678
679	<ul>
680	<li>The <code>simple_state<></code> base class portion of
681	<code>Inner</code> is responsible to destruct <code>Outer</code></li>
682
683	<li>Destructors of base class portions are called in the reverse order of
684	construction</li>
685	</ul>
686
687	<p>So, when the <code>Outer</code> destructor is called the call stack
688	looks as follows:</p>
689	<pre>
690	Outer::~Outer()
691	simple_state< Inner, ... >::~simple_state()
692	Inner::~Inner()
693	</pre>
694
695	<p>Note that <code>Inner::~Inner()</code> did not yet have a chance to
696	destroy its <code>EntryExitDisplayer</code> base class portion, as it first
697	has to call the destructor of the <b>second</b> base class. Now
698	<code>Outer::~Outer()</code> will first destruct its <code>simple_state<
699	Outer, ... ></code> base class portion and then do the same with its
700	<code>EntryExitDisplayer</code> base class portion. The stack then unwinds
701	back to <code>Inner::~Inner()</code>, which can then finally finish by
702	calling <code>EntryExitDisplayer::~EntryExitDisplayer()</code>.</p>
703
704	<p>Luckily, there is an easy work-around: Always let
705	<code>simple_state<></code> and <code>state<></code> be the
706	first base class of a state. This ensures that destructors of additional
707	bases are called before recursion employed by state base destructors can
708	alter the order of destruction.</p>
709	<hr>
710
711	<p><a href="http://validator.w3.org/check?uri=referer"><img border="0" src=
712	"http://www.w3.org/Icons/valid-html401" alt="Valid HTML 4.01 Transitional"
713	height="31" width="88"></a></p>
714
715	<p>Revised
716	<!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->03 December, 2006<!--webbot bot="Timestamp" endspan i-checksum="38512" --></p>
717
718	<p><i>Copyright © 2003-<!--webbot bot="Timestamp" s-type="EDITED" s-format="%Y" startspan -->2006<!--webbot bot="Timestamp" endspan i-checksum="770" -->
719	<a href="contact.html">Andreas Huber Dönni</a></i></p>
720
721	<p><i>Distributed under the Boost Software License, Version 1.0. (See
722	accompanying file <a href="../../../LICENSE_1_0.txt">LICENSE_1_0.txt</a> or
723	copy at <a href=
724	"http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</a>)</i></p>
725	</body>
726	</html>

Note: See TracBrowser for help on using the repository browser.

Download in other formats: