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 12.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 - Reference</title> 12 <style type="text/css"> 13 .style1 14 { 15 width: 45%; 16 } 17 </style> 18</head> 19 20<body link="#0000FF" vlink="#800080"> 21 <table border="0" cellpadding="7" cellspacing="0" width="100%" summary= 22 "header"> 23 <tr> 24 <td valign="top" width="300"> 25 <h3><a href="../../../index.htm"><img alt="C++ Boost" src= 26 "../../../boost.png" border="0" width="277" height="86"></a></h3> 27 </td> 28 29 <td valign="top"> 30 <h1 align="center">The Boost Statechart Library</h1> 31 32 <h2 align="center">Reference</h2> 33 </td> 34 </tr> 35 </table> 36 <hr> 37 38 <h2>Contents</h2> 39 40 <dl class="page-index"> 41 <dt><a href="#Concepts">Concepts</a></dt> 42 43 <dd><a href="#Scheduler">Scheduler</a></dd> 44 45 <dd><a href="#FifoWorker">FifoWorker</a></dd> 46 47 <dd><a href="#ExceptionTranslator">ExceptionTranslator</a></dd> 48 49 <dd><a href="#StateBase">StateBase</a></dd> 50 51 <dd><a href="#SimpleState">SimpleState</a></dd> 52 53 <dd><a href="#State">State</a></dd> 54 55 <dd><a href="#Event">Event</a></dd> 56 57 <dt><a href="#state_machine.hpp">state_machine.hpp</a></dt> 58 59 <dd><a href="#ClassTemplatestate_machine">Class template 60 <code>state_machine</code></a></dd> 61 62 <dt><a href= 63 "#asynchronous_state_machine.hpp">asynchronous_state_machine.hpp</a></dt> 64 65 <dd><a href="#ClassTemplateasynchronous_state_machine">Class template 66 <code>asynchronous_state_machine</code></a></dd> 67 68 <dt><a href="#event_processor.hpp">event_processor.hpp</a></dt> 69 70 <dd><a href="#ClassTemplateevent_processor">Class template 71 <code>event_processor</code></a></dd> 72 73 <dt><a href="#fifo_scheduler.hpp">fifo_scheduler.hpp</a></dt> 74 75 <dd><a href="#ClassTemplatefifo_scheduler">Class template 76 <code>fifo_scheduler</code></a></dd> 77 78 <dt><a href="#exception_translator.hpp">exception_translator.hpp</a></dt> 79 80 <dd><a href="#ClassTemplateexception_translator">Class template 81 <code>exception_translator</code></a></dd> 82 83 <dt><a href= 84 "#null_exception_translator.hpp">null_exception_translator.hpp</a></dt> 85 86 <dd><a href="#Classnull_exception_translator">Class 87 <code>null_exception_translator</code></a></dd> 88 89 <dt> </dt> 90 91 <dt><a href="#simple_state.hpp">simple_state.hpp</a></dt> 92 93 <dd><a href="#Enumhistory_mode">Enum <code>history_mode</code></a></dd> 94 95 <dd><a href="#ClassTemplatesimple_state">Class template 96 <code>simple_state</code></a></dd> 97 98 <dt><a href="#state.hpp">state.hpp</a></dt> 99 100 <dd><a href="#ClassTemplatestate">Class template 101 <code>state</code></a></dd> 102 103 <dt><a href="#shallow_history.hpp">shallow_history.hpp</a></dt> 104 105 <dd><a href="#ClassTemplateshallow_history">Class template 106 <code>shallow_history</code></a></dd> 107 108 <dt><a href="#deep_history.hpp">deep_history.hpp</a></dt> 109 110 <dd><a href="#ClassTemplatedeep_history">Class template 111 <code>deep_history</code></a></dd> 112 113 <dt> </dt> 114 115 <dt><a href="#event_base.hpp">event_base.hpp</a></dt> 116 117 <dd><a href="#Classevent_base">Class <code>event_base</code></a></dd> 118 119 <dt><a href="#event.hpp">event.hpp</a></dt> 120 121 <dd><a href="#ClassTemplateevent">Class template 122 <code>event</code></a></dd> 123 124 <dt> </dt> 125 126 <dt><a href="#transition.hpp">transition.hpp</a></dt> 127 128 <dd><a href="#ClassTemplatetransition">Class template 129 <code>transition</code></a></dd> 130 131 <dt><a href="#in_state_reaction.hpp">in_state_reaction.hpp</a></dt> 132 133 <dd><a href="#ClassTemplatein_state_reaction">Class template 134 in_state_reaction</a></dd> 135 136 <dt><a href="#termination.hpp">termination.hpp</a></dt> 137 138 <dd><a href="#ClassTemplatetermination">Class template 139 <code>termination</code></a></dd> 140 141 <dt><a href="#deferral.hpp">deferral.hpp</a></dt> 142 143 <dd><a href="#ClassTemplatedeferral">Class template 144 <code>deferral</code></a></dd> 145 146 <dt><a href="#custom_reaction.hpp">custom_reaction.hpp</a></dt> 147 148 <dd><a href="#ClassTemplatecustom_reaction">Class template 149 <code>custom_reaction</code></a></dd> 150 151 <dt><a href="#result.hpp">result.hpp</a></dt> 152 153 <dd><a href="#Classresult">Class <code>result</code></a></dd> 154 </dl> 155 <hr> 156 157 <h1><a name="Concepts" id="Concepts">Concepts</a></h1> 158 159 <h2><a name="Scheduler" id="Scheduler">Scheduler</a> concept</h2> 160 161 <p>A Scheduler type defines the following:</p> 162 163 <ul> 164 <li>What is passed to the constructors of <code><a href= 165 "#ClassTemplateevent_processor">event_processor<></a></code> 166 subtypes and how the lifetime of such objects is managed</li> 167 168 <li>Whether or not multiple <code>event_processor<></code> subtype 169 objects can share the same queue and scheduler thread</li> 170 171 <li>How events are added to the schedulers' queue</li> 172 173 <li>Whether and how to wait for new events when the schedulers' queue 174 runs empty</li> 175 176 <li>Whether and what type of locking is used to ensure thread-safety</li> 177 178 <li>Whether it is possible to queue events for no longer existing 179 <code>event_processor<></code> subtype objects and what happens 180 when such an event is processed</li> 181 182 <li>What happens when one of the serviced 183 <code>event_processor<></code> subtype objects propagates an 184 exception</li> 185 </ul> 186 187 <p>For a Scheduler type <code>S</code> and an object <code>cpc</code> of 188 type <code>const S::processor_context</code> the following expressions must 189 be well-formed and have the indicated results:</p> 190 191 <table border="3" cellpadding="2" width="100%" summary="Scheduler concept"> 192 <tr> 193 <td><b>Expression</b></td> 194 195 <td><b>Type</b></td> 196 197 <td><b>Result</b></td> 198 </tr> 199 200 <tr> 201 <td><code>cpc.my_scheduler()</code></td> 202 203 <td><code>S &</code></td> 204 205 <td>A reference to the scheduler</td> 206 </tr> 207 208 <tr> 209 <td><code>cpc.my_handle()</code></td> 210 211 <td><code>S::processor_handle</code></td> 212 213 <td>The handle identifying the 214 <code>event_processor<></code> subtype object</td> 215 </tr> 216 </table> 217 218 <p>To protect against abuse, all members of 219 <code>S::processor_context</code> should be declared private. As a result, 220 <code>event_processor<></code> must be a friend of 221 <code>S::processor_context</code>.</p> 222 223 <h2><a name="FifoWorker" id="FifoWorker">FifoWorker</a> concept</h2> 224 225 <p>A FifoWorker type defines the following:</p> 226 227 <ul> 228 <li>Whether and how to wait for new work items when the internal work 229 queue runs empty</li> 230 231 <li>Whether and what type of locking is used to ensure thread-safety</li> 232 </ul> 233 234 <p>For a FifoWorker type <code>F</code>, an object <code>f</code> of that 235 type, a <code>const</code> object <code>cf</code> of that type, a 236 parameterless function object <code>w</code> of arbitrary type and an 237 <code>unsigned long</code> value <code>n</code> the following 238 expressions/statements must be well-formed and have the indicated 239 results:</p> 240 241 <table border="3" cellpadding="2" width="100%" summary= 242 "FifoWorker concept"> 243 <tr> 244 <td><b>Expression/Statement</b></td> 245 246 <td><b>Type</b></td> 247 248 <td><b>Effects/Result</b></td> 249 </tr> 250 251 <tr> 252 <td><code>F::work_item</code></td> 253 254 <td><code>boost::function0< void ></code></td> 255 256 <td> </td> 257 </tr> 258 259 <tr> 260 <td><code>F()</code> or <code>F( false )</code></td> 261 262 <td><code>F</code></td> 263 264 <td>Constructs a <b>non-blocking</b> (see below) object of 265 the FifoWorker type. In single-threaded builds the second expression is 266 not well-formed</td> 267 </tr> 268 269 <tr> 270 <td><code>F( true )</code></td> 271 272 <td><code>F</code></td> 273 274 <td>Constructs a <b>blocking</b> (see below) object of the 275 FifoWorker type. Not well-formed in single-threaded builds</td> 276 </tr> 277 278 <tr> 279 <td><code>f.queue_work_item( w );</code></td> 280 281 <td> </td> 282 283 <td>Constructs and queues an object of type 284 <code>F::work_item</code>, passing <code>w</code> as the only 285 argument</td> 286 </tr> 287 288 <tr> 289 <td><code>f.terminate();</code></td> 290 291 <td> </td> 292 293 <td>Creates and queues an object of type 294 <code>F::work_item</code> that, when later executed in 295 <code>operator()()</code>, leads to a modification of internal state so 296 that <code>terminated()</code> henceforth returns 297 <code>true</code></td> 298 </tr> 299 300 <tr> 301 <td><code>cf.terminated();</code></td> 302 303 <td><code>bool</code></td> 304 305 <td><code>true</code> if <code>terminate()</code> has been 306 called and the resulting work item has been executed in 307 <code>operator()()</code>. Returns <code>false</code> otherwise<br> 308 <br> 309 <b>Must only be called from the thread that also calls 310 <code>operator()()</code></b></td> 311 </tr> 312 313 <tr> 314 <td><code>f( n );</code></td> 315 316 <td><code>unsigned long</code></td> 317 318 <td> 319 Enters a loop that, with each cycle, dequeues and calls 320 <code>operator()()</code> on the oldest work item in the queue. 321 322 <p>The loop is left and the number of executed work items returned if 323 one or more of the following conditions are met:</p> 324 325 <ul> 326 <li><code>f.terminated() == true</code></li> 327 328 <li>The application is single-threaded and the internal queue is 329 empty</li> 330 331 <li>The application is multi-threaded and the internal queue is 332 empty and the worker was created as non-blocking</li> 333 334 <li><code>n != 0</code> and the number of work items that have been 335 processed since <code>operator()()</code> was called equals 336 <code>n</code></li> 337 </ul> 338 339 <p>If the queue is empty and none of the above conditions are met 340 then the thread calling <code>operator()()</code> is put into a wait 341 state until <code>f.queue_work_item()</code> is called from another 342 thread.<br> 343 <br> 344 <b>Must only be called from exactly one thread</b></p> 345 </td> 346 </tr> 347 348 <tr> 349 <td><code>f();</code></td> 350 351 <td><code>unsigned long</code></td> 352 353 <td>Has exactly the same semantics as <code>f( n );</code> 354 with <code>n == 0</code> (see above)</td> 355 </tr> 356 </table> 357 358 <h2><a name="ExceptionTranslator" id= 359 "ExceptionTranslator">ExceptionTranslator</a> concept</h2> 360 361 <p>An ExceptionTranslator type defines how C++ exceptions occurring during 362 state machine operation are translated to exception events.</p> 363 364 <p>For an ExceptionTranslator object <code>et</code>, a parameterless 365 function object <code>a</code> of arbitrary type returning <code><a href= 366 "#Classresult">result</a></code> and a function object <code>eh</code> of 367 arbitrary type taking a <code>const <a href= 368 "#Classevent_base">event_base</a> &</code> parameter and returning 369 <code><a href="#Classresult">result</a></code> the following expression 370 must be well-formed and have the indicated results:</p> 371 372 <table border="3" cellpadding="2" width="100%" summary= 373 "ExceptionTranslator concept"> 374 <tr> 375 <td><b>Expression</b></td> 376 377 <td><b>Type</b></td> 378 379 <td><b>Effects/Result</b></td> 380 </tr> 381 382 <tr> 383 <td><code>et( a, eh );</code></td> 384 385 <td><code>result</code></td> 386 387 <td> 388 <ol> 389 <li>Attempts to execute <code>return a();</code></li> 390 391 <li>If <code>a()</code> propagates an exception, the exception is 392 caught</li> 393 394 <li>Inside the catch block calls <code>eh</code>, passing a 395 suitable stack-allocated model of the <a href="#Event">Event</a> 396 concept</li> 397 398 <li>Returns the result returned by <code>eh</code></li> 399 </ol> 400 </td> 401 </tr> 402 </table> 403 404 <h2><a name="StateBase" id="StateBase">StateBase</a> concept</h2> 405 406 <p>A StateBase type is the common base of all states of a given state 407 machine type. <code>state_machine<>::state_base_type</code> is a 408 model of the StateBase concept.</p> 409 410 <p>For a StateBase type <code>S</code> and a <code>const</code> object 411 <code>cs</code> of that type the following expressions must be well-formed 412 and have the indicated results:</p> 413 414 <table border="3" cellpadding="2" width="100%" summary="StateBase concept"> 415 <tr> 416 <td><b>Expression</b></td> 417 418 <td><b>Type</b></td> 419 420 <td><b>Result</b></td> 421 </tr> 422 423 <tr> 424 <td><code>cs.outer_state_ptr()</code></td> 425 426 <td><code>const S *</code></td> 427 428 <td><code>0</code> if <code>cs</code> is an <a href= 429 "definitions.html#OutermostState">outermost state</a>, a pointer to the 430 direct outer state of <code>cs</code> otherwise</td> 431 </tr> 432 433 <tr> 434 <td><code>cs.dynamic_type()</code></td> 435 436 <td><code>S::id_type</code></td> 437 438 <td>A value unambiguously identifying the most-derived type 439 of <code>cs</code>. <code>S::id_type</code> values are comparable with 440 <code>operator==()</code> and <code>operator!=()</code>. An unspecified 441 collating order can be established with <code>std::less< S::id_type 442 ></code>. In contrast to <code>typeid( cs )</code>, this function is 443 available even on platforms that do not support C++ RTTI (or have been 444 configured to not support it)</td> 445 </tr> 446 447 <tr> 448 <td><code>cs.custom_dynamic_type_ptr<<br> 449 Type >()</code></td> 450 451 <td><code>const Type *</code></td> 452 453 <td>A pointer to the custom type identifier or 454 <code>0</code>. If <code>!= 0</code>, <code>Type</code> must match the 455 type of the previously set pointer. This function is only available if 456 <a href= 457 "configuration.html#ApplicationDefinedMacros">BOOST_STATECHART_USE_NATIVE_RTTI</a> 458 is not defined</td> 459 </tr> 460 </table> 461 462 <h2><a name="SimpleState" id="SimpleState">SimpleState</a> concept</h2> 463 464 <p>A SimpleState type defines one state of a particular state machine.</p> 465 466 <p>For a SimpleState type <code>S</code> and a pointer <code>pS</code> 467 pointing to an object of type <code>S</code> allocated with 468 <code>new</code> the following expressions/statements must be well-formed 469 and have the indicated effects/results:</p> 470 471 <table border="3" cellpadding="2" width="100%" summary= 472 "SimpleState concept"> 473 <tr> 474 <td><b>Expression/Statement</b></td> 475 476 <td><b>Type</b></td> 477 478 <td><b>Effects/Result/Notes</b></td> 479 </tr> 480 481 <tr> 482 <td><code><a href= 483 "#ClassTemplatesimple_state">simple_state</a><<br> 484 S, C, I, h > * pB =<br> 485 pS;</code></td> 486 487 <td> </td> 488 489 <td><code>simple_state< S, C, I, h ></code> must be 490 an unambiguous public base of <code>S</code>. See <code><a href= 491 "#ClassTemplatesimple_state">simple_state<></a></code> 492 documentation for the requirements and semantics of <code>C</code>, 493 <code>I</code> and <code>h</code></td> 494 </tr> 495 496 <tr> 497 <td><code>new S()</code></td> 498 499 <td><code>S *</code></td> 500 501 <td>Enters the state <code>S</code>. Certain functions must 502 not be called from <code>S::S()</code>, see <a href= 503 "#ClassTemplatesimple_state"><code>simple_state<></code></a> 504 documentation for more information</td> 505 </tr> 506 507 <tr> 508 <td><code>pS->exit();</code></td> 509 510 <td> </td> 511 512 <td>Exits the state <code>S</code> (first stage). The 513 definition of an <code>exit</code> member function within models of the 514 SimpleState concept is optional since <code>simple_state<></code> 515 already defines the following public member: <code>void exit() 516 {}</code>. <code>exit()</code> is not called when a state is exited 517 while an exception is pending, see <code><a href= 518 "#simple_state::terminate">simple_state<>::terminate()</a></code> 519 for more information</td> 520 </tr> 521 522 <tr> 523 <td><code>delete pS;</code></td> 524 525 <td> </td> 526 527 <td>Exits the state <code>S</code> (second stage)</td> 528 </tr> 529 530 <tr> 531 <td><code>S::reactions</code></td> 532 533 <td>An <code>mpl::list<></code> that is either empty 534 or contains instantiations of the <code><a href= 535 "#ClassTemplatecustom_reaction">custom_reaction</a></code>, 536 <code><a href= 537 "#ClassTemplatein_state_reaction">in_state_reaction</a></code>, 538 <code><a href="#ClassTemplatedeferral">deferral</a></code>, 539 <code><a href="#ClassTemplatetermination">termination</a></code> or 540 <code><a href="#ClassTemplatetransition">transition</a></code> class 541 templates. If there is only a single reaction then it can also be 542 <code>typedef</code>ed directly, without wrapping it into an 543 <code>mpl::list<></code></td> 544 545 <td>The declaration of a <code>reactions</code> member 546 <code>typedef</code> within models of the SimpleState concept is 547 optional since <code>simple_state<></code> already defines the 548 following public member: <code>typedef mpl::list<> 549 reactions;</code></td> 550 </tr> 551 </table> 552 553 <h2><a name="State" id="State">State</a> concept</h2> 554 555 <p>A State is a <b>refinement</b> of <a href="#SimpleState">SimpleState</a> 556 (that is, except for the default constructor a State type must also satisfy 557 SimpleState requirements). For a State type <code>S</code>, a pointer 558 <code>pS</code> of type <code>S *</code> pointing to an object of type 559 <code>S</code> allocated with <code>new</code>, and an object 560 <code>mc</code> of type <code>state< S, C, I, h 561 ></code><code>::my_context</code> the following expressions/statements 562 must be well-formed:</p> 563 564 <table border="3" cellpadding="2" width="100%" summary="State concept"> 565 <tr> 566 <td><b>Expression/Statement</b></td> 567 568 <td><b>Type</b></td> 569 570 <td><b>Effects/Result/Notes</b></td> 571 </tr> 572 573 <tr> 574 <td><code><a href="#ClassTemplatestate">state</a>< S, C, I, h > *<br> 575 pB = pS;</code></td> 576 577 <td> </td> 578 579 <td><code>state< S, C, I, h ></code> must be an 580 unambiguous public base of <code>S</code>. See <code><a href= 581 "#ClassTemplatestate">state<></a></code> documentation for the 582 requirements and semantics of <code>C</code>, <code>I</code> and 583 <code>h</code></td> 584 </tr> 585 586 <tr> 587 <td><code>new S( mc )</code></td> 588 589 <td><code>S *</code></td> 590 591 <td>Enters the state <code>S</code>. No restrictions exist 592 regarding the functions that can be called from <code>S::S()</code> (in 593 contrast to the constructors of models of the SimpleState concept). 594 <code>mc</code> must be forwarded to <code>state< S, C, I, h 595 >::state()</code></td> 596 </tr> 597 </table> 598 599 <h2><a name="Event" id="Event">Event</a> concept</h2> 600 601 <p>A Event type defines an event for which state machines can define 602 reactions.</p> 603 604 <p>For a Event type <code>E</code> and a pointer <code>pCE</code> of type 605 <code>const E *</code> pointing to an object of type <code>E</code> 606 allocated with <code>new</code> the following expressions/statements must 607 be well-formed and have the indicated effects/results:</p> 608 609 <table border="3" cellpadding="2" width="100%" summary="Event concept"> 610 <tr> 611 <td><b>Expression/Statement</b></td> 612 613 <td><b>Type</b></td> 614 615 <td><b>Effects/Result/Notes</b></td> 616 </tr> 617 618 <tr> 619 <td><code>const <a href="#ClassTemplateevent">event</a>< 620 E > * pCB = pCE;</code></td> 621 622 <td> </td> 623 624 <td><code>event< E ></code> must be an unambiguous 625 public base of <code>E</code></td> 626 </tr> 627 628 <tr> 629 <td><code>new E( *pCE )</code></td> 630 631 <td><code>E *</code></td> 632 633 <td>Makes a copy of <code>pE</code></td> 634 </tr> 635 </table> 636 637 <h1>Header <boost/statechart/<a name="state_machine.hpp" id= 638 "state_machine.hpp">state_machine.hpp</a>></h1> 639 640 <h2><a name="ClassTemplatestate_machine" id= 641 "ClassTemplatestate_machine">Class template 642 <code>state_machine</code></a></h2> 643 644 <p>This is the base class template of all synchronous state machines.</p> 645 646 <h3>Class template <code>state_machine</code> parameters</h3> 647 648 <table border="3" cellpadding="2" width="100%" summary= 649 "state_machine parameters"> 650 <tr> 651 <td><b>Template parameter</b></td> 652 653 <td><b>Requirements</b></td> 654 655 <td><b>Semantics</b></td> 656 657 <td><b>Default</b></td> 658 </tr> 659 660 <tr> 661 <td><code>MostDerived</code></td> 662 663 <td>The most-derived subtype of this class template</td> 664 665 <td> </td> 666 667 <td> </td> 668 </tr> 669 670 <tr> 671 <td><code>InitialState</code></td> 672 673 <td>A model of the <a href="#SimpleState">SimpleState</a> 674 or <a href="#State">State</a> concepts. The <code>Context</code> 675 argument passed to the <code><a href= 676 "#ClassTemplatesimple_state">simple_state<></a></code> or 677 <code><a href="#ClassTemplatestate">state<></a></code> base 678 of <code>InitialState</code> must be <code>MostDerived</code>. 679 That is, <code>InitialState</code> must be an <a href= 680 "definitions.html#OutermostState">outermost state</a> of this state 681 machine</td> 682 683 <td>The state that is entered when 684 <code>state_machine<><br> 685 ::initiate()</code> is called</td> 686 687 <td> </td> 688 </tr> 689 690 <tr> 691 <td><code>Allocator</code></td> 692 693 <td>A model of the standard Allocator concept</td> 694 695 <td><code>Allocator::rebind<>::other</code> is used 696 to allocate and deallocate all <code>simple_state</code> subtype 697 objects and internal objects of dynamic storage duration</td> 698 699 <td><code>std::allocator< void ></code></td> 700 </tr> 701 702 <tr> 703 <td><code>ExceptionTranslator</code></td> 704 705 <td>A model of the ExceptionTranslator concept</td> 706 707 <td>see <a href= 708 "#ExceptionTranslator">ExceptionTranslator</a> concept</td> 709 710 <td><code>null_exception_translator</code></td> 711 </tr> 712 </table> 713 714 <h3>Class template <code>state_machine</code> synopsis</h3> 715 <pre> 716namespace boost 717{ 718namespace statechart 719{ 720 template< 721 class MostDerived, 722 class InitialState, 723 class Allocator = std::allocator< void >, 724 class ExceptionTranslator = null_exception_translator > 725 class state_machine : noncopyable 726 { 727 public: 728 typedef MostDerived outermost_context_type; 729 730 void <a href="#initiate">initiate</a>(); 731 void <a href="#terminate">terminate</a>(); 732 bool <a href="#terminated">terminated</a>() const; 733 734 void <a href="#process_event">process_event</a>( const <a href= 735"#Classevent_base">event_base</a> & ); 736 737 template< class Target > 738 Target <a href="#state_cast">state_cast</a>() const; 739 template< class Target > 740 Target <a href="#state_downcast">state_downcast</a>() const; 741 742 // a model of the <a href="#StateBase">StateBase</a> concept 743 typedef <i>implementation-defined</i> state_base_type; 744 // a model of the standard Forward Iterator concept 745 typedef <i>implementation-defined</i> state_iterator; 746 747 state_iterator <a href="#state_begin">state_begin</a>() const; 748 state_iterator <a href="#state_end">state_end</a>() const; 749 750 void <a href="#unconsumed_event">unconsumed_event</a>( const <a href= 751"#Classevent_base">event_base</a> & ) {} 752 753 protected: 754 <a href="#state_machine">state_machine</a>(); 755 <a href="#state_machinedtor">~state_machine</a>(); 756 757 void <a href="#post_event2">post_event</a>( 758 const intrusive_ptr< const <a href= 759"#Classevent_base">event_base</a> > & ); 760 void <a href="#post_event3">post_event</a>( const <a href= 761"#Classevent_base">event_base</a> & ); 762 763 const event_base * <a href="#triggering_event1">triggering_event</a>() const; 764 }; 765} 766} 767</pre> 768 769 <h3>Class template <code>state_machine</code> constructor and 770 destructor</h3> 771 <pre> 772<a name="state_machine" id="state_machine">state_machine</a>(); 773</pre> 774 775 <p><b>Effects</b>: Constructs a non-running state machine</p> 776 <pre> 777<a name="state_machinedtor" id="state_machinedtor">~state_machine</a>(); 778</pre> 779 780 <p><b>Effects</b>: Destructs the currently active outermost state and all 781 its direct and indirect inner states. Innermost states are destructed 782 first. Other states are destructed as soon as all their direct and indirect 783 inner states have been destructed. The inner states of each state are 784 destructed according to the number of their orthogonal region. The state in 785 the orthogonal region with the highest number is always destructed first, 786 then the state in the region with the second-highest number and so on<br> 787 <b>Note</b>: Does not attempt to call any <code>exit</code> member 788 functions</p> 789 790 <h3>Class template <code>state_machine</code> modifier functions</h3> 791 <pre> 792void <a name="initiate" id="initiate">initiate</a>(); 793</pre> 794 795 <p><b>Effects</b>:</p> 796 797 <ol> 798 <li>Calls <code>terminate()</code></li> 799 800 <li>Constructs a function object <code>action</code> with a 801 parameter-less <code>operator()()</code> returning <code><a href= 802 "#Classresult">result</a></code> that 803 804 <ol type="a"> 805 <li>enters (constructs) the state specified with the 806 <code>InitialState</code> template parameter</li> 807 808 <li>enters the tree formed by the direct and indirect inner initial 809 states of <code>InitialState</code> depth first. The inner states of 810 each state are entered according to the number of their orthogonal 811 region. The state in orthogonal region 0 is always entered first, 812 then the state in region 1 and so on</li> 813 </ol> 814 </li> 815 816 <li>Constructs a function object <code>exceptionEventHandler</code> with 817 an <code>operator()()</code> returning <code>result</code> and accepting 818 an exception event parameter that processes the passed exception event, 819 with the following differences to the processing of normal events: 820 821 <ul type="disc"> 822 <li>From the moment when the exception has been thrown until right 823 after the execution of the exception event reaction, states that need 824 to be exited are only destructed but no <code>exit</code> member 825 functions are called</li> 826 827 <li><a href="definitions.html#Reaction">Reaction</a> search always 828 starts with the outermost <a href= 829 "definitions.html#UnstableState">unstable state</a></li> 830 831 <li>As for normal events, reaction search moves outward when the 832 current state cannot handle the event. However, if there is no outer 833 state (an <a href="definitions.html#OutermostState">outermost 834 state</a> has been reached) the reaction search is considered 835 unsuccessful. That is, exception events will never be dispatched to 836 orthogonal regions other than the one that caused the exception 837 event</li> 838 839 <li>Should an exception be thrown during exception event reaction 840 search or reaction execution then the exception is propagated out of 841 the <code>exceptionEventHandler</code> function object (that is, 842 <code>ExceptionTranslator</code> is <b>not</b> used to translate 843 exceptions thrown while processing an exception event)</li> 844 845 <li>If no reaction could be found for the exception event or if the 846 state machine is not stable after processing the exception event, the 847 original exception is rethrown. Otherwise, a <code><a href= 848 "#Classresult">result</a></code> object is returned equal to the one 849 returned by <code>simple_state<>::discard_event()</code></li> 850 </ul> 851 </li> 852 853 <li>Passes <code>action</code> and <code>exceptionEventHandler</code> to 854 <code>ExceptionTranslator::operator()()</code>. If 855 <code>ExceptionTranslator::operator()()</code> throws an exception, the 856 exception is propagated to the caller. If the caller catches the 857 exception, the currently active outermost state and all its direct and 858 indirect inner states are destructed. Innermost states are destructed 859 first. Other states are destructed as soon as all their direct and 860 indirect inner states have been destructed. The inner states of each 861 state are destructed according to the number of their orthogonal region. 862 The state in the orthogonal region with the highest number is always 863 destructed first, then the state in the region with the second-highest 864 number and so on. Continues with step 5 otherwise (the return value is 865 discarded)</li> 866 867 <li>Processes all posted events (see <code>process_event()</code>). 868 Returns to the caller if there are no more posted events</li> 869 </ol> 870 871 <p><b>Throws</b>: Any exceptions propagated from 872 <code>ExceptionTranslator::operator()()</code>. Exceptions never originate 873 in the library itself but only in code supplied through template 874 parameters:</p> 875 876 <ul> 877 <li><code>Allocator::rebind<>::other::allocate()</code></li> 878 879 <li>state constructors</li> 880 881 <li><code>react</code> member functions</li> 882 883 <li><code>exit</code> member functions</li> 884 885 <li>transition-actions</li> 886 </ul> 887 <pre> 888void <a name="terminate" id="terminate">terminate</a>(); 889</pre> 890 891 <p><b>Effects</b>:</p> 892 893 <ol> 894 <li>Constructs a function object <code>action</code> with a 895 parameter-less <code>operator()()</code> returning <code><a href= 896 "#Classresult">result</a></code> that <a href= 897 "#simple_state::terminate">terminates</a> the currently active outermost 898 state, discards all remaining events and clears all history 899 information</li> 900 901 <li>Constructs a function object <code>exceptionEventHandler</code> with 902 an <code>operator()()</code> returning <code><a href= 903 "#Classresult">result</a></code> and accepting an exception event 904 parameter that processes the passed exception event, with the following 905 differences to the processing of normal events: 906 907 <ul type="disc"> 908 <li>From the moment when the exception has been thrown until right 909 after the execution of the exception event reaction, states that need 910 to be exited are only destructed but no <code>exit</code> member 911 functions are called</li> 912 913 <li><a href="definitions.html#Reaction">Reaction</a> search always 914 starts with the outermost <a href= 915 "definitions.html#UnstableState">unstable state</a></li> 916 917 <li>As for normal events, reaction search moves outward when the 918 current state cannot handle the event. However, if there is no outer 919 state (an <a href="definitions.html#OutermostState">outermost 920 state</a> has been reached) the reaction search is considered 921 unsuccessful. That is, exception events will never be dispatched to 922 orthogonal regions other than the one that caused the exception 923 event</li> 924 925 <li>Should an exception be thrown during exception event reaction 926 search or reaction execution then the exception is propagated out of 927 the <code>exceptionEventHandler</code> function object (that is, 928 <code>ExceptionTranslator</code> is <b>not</b> used to translate 929 exceptions thrown while processing an exception event)</li> 930 931 <li>If no reaction could be found for the exception event or if the 932 state machine is not stable after processing the exception event, the 933 original exception is rethrown. Otherwise, a <code><a href= 934 "#Classresult">result</a></code> object is returned equal to the one 935 returned by <code>simple_state<>::discard_event()</code></li> 936 </ul> 937 </li> 938 939 <li>Passes <code>action</code> and <code>exceptionEventHandler</code> to 940 <code>ExceptionTranslator::operator()()</code>. If 941 <code>ExceptionTranslator::operator()()</code> throws an exception, the 942 exception is propagated to the caller. If the caller catches the 943 exception, the currently active outermost state and all its direct and 944 indirect inner states are destructed. Innermost states are destructed 945 first. Other states are destructed as soon as all their direct and 946 indirect inner states have been destructed. The inner states of each 947 state are destructed according to the number of their orthogonal region. 948 The state in the orthogonal region with the highest number is always 949 destructed first, then the state in the region with the second-highest 950 number and so on. Otherwise, returns to the caller</li> 951 </ol> 952 953 <p><b>Throws</b>: Any exceptions propagated from 954 <code>ExceptionTranslator::operator()</code>. Exceptions never originate in 955 the library itself but only in code supplied through template 956 parameters:</p> 957 958 <ul> 959 <li><code>Allocator::rebind<>::other::allocate()</code></li> 960 961 <li>state constructors</li> 962 963 <li><code>react</code> member functions</li> 964 965 <li><code>exit</code> member functions</li> 966 967 <li>transition-actions</li> 968 </ul> 969 <pre> 970void <a name="process_event" id= 971"process_event">process_event</a>( const <a href= 972"#Classevent_base">event_base</a> & ); 973</pre> 974 975 <p><b>Effects</b>:</p> 976 977 <ol> 978 <li>Selects the passed event as the current event (henceforth referred to 979 as <code>currentEvent</code>)</li> 980 981 <li>Starts a new <a href="definitions.html#Reaction">reaction</a> 982 search</li> 983 984 <li>Selects an arbitrary but in this reaction search not yet visited 985 state from all the currently active <a href= 986 "definitions.html#InnermostState">innermost states</a>. If no such state 987 exists then continues with step 10</li> 988 989 <li>Constructs a function object <code>action</code> with a 990 parameter-less <code>operator()()</code> returning <code><a href= 991 "#Classresult">result</a></code> that does the following: 992 993 <ol type="a"> 994 <li>Searches a reaction suitable for <code>currentEvent</code>, 995 starting with the current innermost state and moving outward until a 996 state defining a reaction for the event is found. Returns 997 <code>simple_state<>::forward_event()</code> if no reaction has 998 been found</li> 999 1000 <li>Executes the found reaction. If the reaction result is equal to 1001 the return value of 1002 <code>simple_state<>::forward_event()</code> then resumes the 1003 reaction search (step a). Returns the reaction result otherwise</li> 1004 </ol> 1005 </li> 1006 1007 <li>Constructs a function object <code>exceptionEventHandler</code> 1008 returning <code><a href="#Classresult">result</a></code> and accepting an 1009 exception event parameter that processes the passed exception event, with 1010 the following differences to the processing of normal events: 1011 1012 <ul type="disc"> 1013 <li>From the moment when the exception has been thrown until right 1014 after the execution of the exception event reaction, states that need 1015 to be exited are only destructed but no <code>exit</code> member 1016 functions are called</li> 1017 1018 <li>If the state machine is stable when the exception event is 1019 processed then exception event reaction search starts with the 1020 innermost state that was last visited during the last normal event 1021 reaction search (the exception event was generated as a result of 1022 this normal reaction search)</li> 1023 1024 <li>If the state machine is <a href= 1025 "definitions.html#UnstableStateMachine">unstable</a> when the 1026 exception event is processed then exception event reaction search 1027 starts with the outermost <a href= 1028 "definitions.html#UnstableState">unstable state</a></li> 1029 1030 <li>As for normal events, reaction search moves outward when the 1031 current state cannot handle the event. However, if there is no outer 1032 state (an <a href="definitions.html#OutermostState">outermost 1033 state</a> has been reached) the reaction search is considered 1034 unsuccessful. That is, exception events will never be dispatched to 1035 orthogonal regions other than the one that caused the exception 1036 event</li> 1037 1038 <li>Should an exception be thrown during exception event reaction 1039 search or reaction execution then the exception is propagated out of 1040 the <code>exceptionEventHandler</code> function object (that is, 1041 <code>ExceptionTranslator</code> is <b>not</b> used to translate 1042 exceptions thrown while processing an exception event)</li> 1043 1044 <li>If no reaction could be found for the exception event or if the 1045 state machine is not stable after processing the exception event, the 1046 original exception is rethrown. Otherwise, a <code><a href= 1047 "#Classresult">result</a></code> object is returned equal to the one 1048 returned by <code>simple_state<>::discard_event()</code></li> 1049 </ul> 1050 </li> 1051 1052 <li>Passes <code>action</code> and <code>exceptionEventHandler</code> to 1053 <code>ExceptionTranslator::operator()()</code>. If 1054 <code>ExceptionTranslator::operator()()</code> throws an exception, the 1055 exception is propagated to the caller. If the caller catches the 1056 exception, the currently active outermost state and all its direct and 1057 indirect inner states are destructed. Innermost states are destructed 1058 first. Other states are destructed as soon as all their direct and 1059 indirect inner states have been destructed. The inner states of each 1060 state are destructed according to the number of their orthogonal region. 1061 The state in the orthogonal region with the highest number is always 1062 destructed first, then the state in the region with the second-highest 1063 number and so on. Otherwise continues with step 7</li> 1064 1065 <li>If the return value of <code>ExceptionTranslator::operator()()</code> 1066 is equal to the one of <code>simple_state<>::forward_event()</code> 1067 then continues with step 3</li> 1068 1069 <li>If the return value of <code>ExceptionTranslator::operator()()</code> 1070 is equal to the one of <code>simple_state<>::defer_event()</code> 1071 then the return value of <code>currentEvent.<a href= 1072 "#intrusive_from_this">intrusive_from_this</a>()</code> is stored in the 1073 deferred events queue. Continues with step 11</li> 1074 1075 <li>If the return value of <code>ExceptionTranslator::operator()()</code> 1076 is equal to the one of <code>simple_state<>::discard_event()</code> 1077 then continues with step 11</li> 1078 1079 <li>Calls <code>static_cast< MostDerived * >( this 1080 )->unconsumed_event( currentEvent )</code>. If 1081 <code>unconsumed_event()</code> throws an exception, the exception is 1082 propagated to the caller. Such an exception never leads to the 1083 destruction of any states (in contrast to exceptions propagated from 1084 <code>ExceptionTranslator::operator()()</code>)</li> 1085 1086 <li>If the posted events queue is non-empty then dequeues the first 1087 event, selects it as <code>currentEvent</code> and continues with step 2. 1088 Returns to the caller otherwise</li> 1089 </ol> 1090 1091 <p><b>Throws</b>: Any exceptions propagated from 1092 <code>MostDerived::unconsumed_event()</code> or 1093 <code>ExceptionTranslator::operator()</code>. Exceptions never originate in 1094 the library itself but only in code supplied through template 1095 parameters:</p> 1096 1097 <ul> 1098 <li><code>Allocator::rebind<>::other::allocate()</code></li> 1099 1100 <li>state constructors</li> 1101 1102 <li><code>react</code> member functions</li> 1103 1104 <li><code>exit</code> member functions</li> 1105 1106 <li>transition-actions</li> 1107 1108 <li><code>MostDerived::unconsumed_event()</code></li> 1109 </ul> 1110 <pre> 1111void <a name="post_event2" id="post_event2">post_event</a>( 1112 const intrusive_ptr< const <a href= 1113"#Classevent_base">event_base</a> > & ); 1114</pre> 1115 1116 <p><b>Effects</b>: Pushes the passed event into the posted events queue<br> 1117 <b>Throws</b>: Any exceptions propagated from 1118 <code>Allocator::allocate()</code></p> 1119 <pre> 1120void <a name="post_event3" id="post_event3">post_event</a>( const <a href= 1121"#Classevent_base">event_base</a> & evt ); 1122</pre> 1123 1124 <p><b>Effects</b>: <code>post_event( evt.intrusive_from_this() 1125 );</code><br> 1126 <b>Throws</b>: Any exceptions propagated from 1127 <code>Allocator::allocate()</code></p> 1128 <pre> 1129void <a name="unconsumed_event" id= 1130"unconsumed_event">unconsumed_event</a>( const <a href= 1131"#Classevent_base">event_base</a> & evt ); 1132</pre> 1133 1134 <p><b>Effects</b>: None<br> 1135 <b>Note</b>: This function (or, if present, the equally named derived class 1136 member function) is called by <a href="#process_event">process_event</a>() 1137 whenever a dispatched event did not trigger a reaction, see <a href= 1138 "#process_event">process_event</a>() effects, point 10 for more 1139 information.</p> 1140 1141 <h3>Class template <code>state_machine</code> observer functions</h3> 1142 <pre> 1143bool <a name="terminated" id="terminated">terminated</a>() const; 1144</pre> 1145 1146 <p><b>Returns</b>: <code>true</code>, if the machine is terminated. Returns 1147 <code>false</code> otherwise<br> 1148 <b>Note</b>: Is equivalent to <code>state_begin() == state_end()</code></p> 1149 <pre> 1150template< class Target > 1151Target <a name="state_cast" id="state_cast">state_cast</a>() const; 1152</pre> 1153 1154 <p><b>Returns</b>: Depending on the form of <code>Target</code> either a 1155 reference or a pointer to <code>const</code> if at least one of the 1156 currently active states can successfully be <code>dynamic_cast</code> to 1157 <code>Target</code>. Returns <code>0</code> for pointer targets and throws 1158 <code>std::bad_cast</code> for reference targets otherwise. 1159 <code>Target</code> can take either of the following forms: <code>const 1160 Class *</code> or <code>const Class &</code><br> 1161 <b>Throws</b>: <code>std::bad_cast</code> if <code>Target</code> is a 1162 reference type and none of the active states can be 1163 <code>dynamic_cast</code> to Target<br> 1164 <b>Note</b>: The search sequence is the same as for <code><a href= 1165 "#process_event">process_event</a>()</code></p> 1166 <pre> 1167template< class Target > 1168Target <a name="state_downcast" id= 1169"state_downcast">state_downcast</a>() const; 1170</pre> 1171 1172 <p><b>Requires</b>: For reference targets the compiler must support partial 1173 specialization of class templates, otherwise a compile-time error will 1174 result. The type denoted by <code>Target</code> must be a model of the 1175 <a href="#SimpleState">SimpleState</a> or <a href="#State">State</a> 1176 concepts<br> 1177 <b>Returns</b>: Depending on the form of <code>Target</code> either a 1178 reference or a pointer to <code>const</code> if <code>Target</code> is 1179 equal to the most-derived type of a currently active state. Returns 1180 <code>0</code> for pointer targets and throws <code>std::bad_cast</code> 1181 for reference targets otherwise. <code>Target</code> can take either of the 1182 following forms: <code>const Class *</code> or <code>const Class 1183 &</code><br> 1184 <b>Throws</b>: <code>std::bad_cast</code> if <code>Target</code> is a 1185 reference type and none of the active states has a most derived type equal 1186 to <code>Target</code><br> 1187 <b>Note</b>: The search sequence is the same as for <code><a href= 1188 "#process_event">process_event</a>()</code></p> 1189 <pre> 1190state_iterator <a name="state_begin" id= 1191"state_begin">state_begin</a>() const; 1192</pre> 1193 <pre> 1194state_iterator <a name="state_end" id="state_end">state_end</a>() const; 1195</pre> 1196 1197 <p><b>Return</b>: Iterator objects, the range [<code>state_begin()</code>, 1198 <code>state_end()</code>) refers to all currently active <a href= 1199 "definitions.html#InnermostState">innermost states</a>. For an object 1200 <code>i</code> of type <code>state_iterator</code>, <code>*i</code> returns 1201 a <code>const state_base_type &</code> and 1202 <code>i.operator->()</code> returns a <code>const state_base_type 1203 *</code><br> 1204 <b>Note</b>: The position of a given innermost state in the range is 1205 arbitrary. It may change with each call to a modifier function. Moreover, 1206 all iterators are invalidated whenever a modifier function is called</p> 1207 <pre> 1208const event_base * <a name="triggering_event1" id="triggering_event1">triggering_event</a>(); 1209</pre> 1210 1211 <p><b>Returns</b>: A pointer to the event that triggered the reaction that is currently 1212 being executed. Returns <code>0</code> if no reaction is being executed or if the current 1213 reaction was triggered by either <code><a href="#initiate">initiate</a>()</code> or 1214 <code><a href="#terminate">terminate</a>()</code> 1215 </p> 1216 1217 <h1>Header <boost/statechart/<br> 1218 <a name="asynchronous_state_machine.hpp" id= 1219 "asynchronous_state_machine.hpp">asynchronous_state_machine.hpp</a>></h1> 1220 1221 <h2><a name="ClassTemplateasynchronous_state_machine" id= 1222 "ClassTemplateasynchronous_state_machine">Class template 1223 <code>asynchronous_state_machine</code></a></h2> 1224 1225 <p>This is the base class template of all asynchronous state machines.</p> 1226 1227 <h3>Class template <code>asynchronous_state_machine</code> parameters</h3> 1228 1229 <table border="3" cellpadding="2" width="100%" summary= 1230 "asynchronous_state_machine parameters"> 1231 <tr> 1232 <td><b>Template parameter</b></td> 1233 1234 <td><b>Requirements</b></td> 1235 1236 <td><b>Semantics</b></td> 1237 1238 <td><b>Default</b></td> 1239 </tr> 1240 1241 <tr> 1242 <td><code>MostDerived</code></td> 1243 1244 <td>The most-derived subtype of this class template</td> 1245 1246 <td> </td> 1247 1248 <td> </td> 1249 </tr> 1250 1251 <tr> 1252 <td><code>InitialState</code></td> 1253 1254 <td>A model of the <a href="#SimpleState">SimpleState</a> 1255 or <a href="#State">State</a> concepts. The <code>Context</code> 1256 argument passed to the <code><a href= 1257 "#ClassTemplatesimple_state">simple_state<></a></code> or 1258 <code><a href="#ClassTemplatestate">state<></a></code> base of 1259 <code>InitialState</code> must be <code>MostDerived</code>. That is, 1260 <code>InitialState</code> must be an <a href= 1261 "definitions.html#OutermostState">outermost state</a> of this state 1262 machine</td> 1263 1264 <td>The state that is entered when the state machine is 1265 initiated through the <code>Scheduler</code> object</td> 1266 1267 <td> </td> 1268 </tr> 1269 1270 <tr> 1271 <td><code>Scheduler</code></td> 1272 1273 <td>A model of the Scheduler concept</td> 1274 1275 <td>see <a href="#Scheduler">Scheduler</a> concept</td> 1276 1277 <td><code>fifo_scheduler<></code></td> 1278 </tr> 1279 1280 <tr> 1281 <td><code>Allocator</code></td> 1282 1283 <td>A model of the standard Allocator concept</td> 1284 1285 <td> </td> 1286 1287 <td><code>std::allocator< void ></code></td> 1288 </tr> 1289 1290 <tr> 1291 <td><code>ExceptionTranslator</code></td> 1292 1293 <td>A model of the ExceptionTranslator concept</td> 1294 1295 <td>see <a href= 1296 "#ExceptionTranslator">ExceptionTranslator</a> concept</td> 1297 1298 <td><code>null_exception_translator</code></td> 1299 </tr> 1300 </table> 1301 1302 <h3>Class template <code>asynchronous_state_machine</code> synopsis</h3> 1303 <pre> 1304namespace boost 1305{ 1306namespace statechart 1307{ 1308 template< 1309 class MostDerived, 1310 class InitialState, 1311 class Scheduler = fifo_scheduler<>, 1312 class Allocator = std::allocator< void >, 1313 class ExceptionTranslator = null_exception_translator > 1314 class asynchronous_state_machine : 1315 public state_machine< 1316 MostDerived, InitialState, Allocator, ExceptionTranslator >, 1317 public event_processor< Scheduler > 1318 { 1319 protected: 1320 typedef asynchronous_state_machine my_base; 1321 1322 asynchronous_state_machine( 1323 typename event_processor< Scheduler >::my_context ctx ); 1324 ~asynchronous_state_machine(); 1325 }; 1326} 1327} 1328</pre> 1329 1330 <h3>Class template <code>asynchronous_state_machine</code> constructor and 1331 destructor</h3> 1332 <pre> 1333asynchronous_state_machine( 1334 typename event_processor< Scheduler >::my_context ctx ); 1335</pre> 1336 1337 <p><b>Effects</b>: Constructs a non-running asynchronous state machine<br> 1338 <b>Note</b>: Users cannot create 1339 <code>asynchronous_state_machine<></code> subtype objects directly. 1340 This can only be done through an object of the <code>Scheduler</code> 1341 class</p> 1342 <pre> 1343~asynchronous_state_machine(); 1344</pre> 1345 1346 <p><b>Effects</b>: Destructs the state machine<br> 1347 <b>Note</b>: Users cannot destruct 1348 <code>asynchronous_state_machine<></code> subtype objects directly. 1349 This can only be done through an object of the <code>Scheduler</code> 1350 class</p> 1351 1352 <h1>Header <boost/statechart/<a name="event_processor.hpp" id= 1353 "event_processor.hpp">event_processor.hpp</a>></h1> 1354 1355 <h2><a name="ClassTemplateevent_processor" id= 1356 "ClassTemplateevent_processor">Class template 1357 <code>event_processor</code></a></h2> 1358 1359 <p>This is the base class template of all types that process events. 1360 <code>asynchronous_state_machine<></code> is just one possible event 1361 processor implementation.</p> 1362 1363 <h3>Class template <code>event_processor</code> parameters</h3> 1364 1365 <table border="3" cellpadding="2" width="100%" summary= 1366 "event_processor parameters"> 1367 <tr> 1368 <td><b>Template parameter</b></td> 1369 1370 <td><b>Requirements</b></td> 1371 1372 <td><b>Semantics</b></td> 1373 </tr> 1374 1375 <tr> 1376 <td><code>Scheduler</code></td> 1377 1378 <td>A model of the Scheduler concept</td> 1379 1380 <td>see <a href="#Scheduler">Scheduler</a> concept</td> 1381 </tr> 1382 </table> 1383 1384 <h3>Class template <code>event_processor</code> synopsis</h3> 1385 <pre> 1386namespace boost 1387{ 1388namespace statechart 1389{ 1390 template< class Scheduler > 1391 class event_processor 1392 { 1393 public: 1394 virtual <a href="#event_processordtor">~event_processor</a>(); 1395 1396 Scheduler & <a href="#my_scheduler">my_scheduler</a>() const; 1397 1398 typedef typename Scheduler::processor_handle 1399 processor_handle; 1400 processor_handle <a href="#my_handle">my_handle</a>() const; 1401 1402 void <a href="#event_processor::initiate">initiate</a>(); 1403 void <a href= 1404"#event_processor::process_event">process_event</a>( const event_base & evt ); 1405 void <a href="#event_processor::terminate">terminate</a>(); 1406 1407 protected: 1408 typedef const typename Scheduler::processor_context & 1409 my_context; 1410 <a href="#event_processor">event_processor</a>( my_context ctx ); 1411 1412 private: 1413 virtual void initiate_impl() = 0; 1414 virtual void process_event_impl( 1415 const event_base & evt ) = 0; 1416 virtual void terminate_impl() = 0; 1417 }; 1418} 1419} 1420</pre> 1421 1422 <h3>Class template <code>event_processor</code> constructor and 1423 destructor</h3> 1424 <pre> 1425<a name="event_processor" id= 1426"event_processor">event_processor</a>( my_context ctx ); 1427</pre> 1428 1429 <p><b>Effects</b>: Constructs an event processor object and stores copies 1430 of the reference returned by <code>myContext.my_scheduler()</code> and the 1431 object returned by <code>myContext.my_handle()</code><br> 1432 <b>Note</b>: Users cannot create <code>event_processor<></code> 1433 subtype objects directly. This can only be done through an object of the 1434 <code>Scheduler</code> class</p> 1435 <pre> 1436virtual <a name="event_processordtor" id= 1437"event_processordtor">~event_processor</a>(); 1438</pre> 1439 1440 <p><b>Effects</b>: Destructs an event processor object<br> 1441 <b>Note</b>: Users cannot destruct <code>event_processor<></code> 1442 subtype objects directly. This can only be done through an object of the 1443 <code>Scheduler</code> class</p> 1444 1445 <h3>Class template <code>event_processor</code> modifier functions</h3> 1446 <pre> 1447void <a name="event_processor::initiate" id= 1448"event_processor::initiate">initiate</a>(); 1449</pre> 1450 1451 <p><b>Effects</b>: <code>initiate_impl();<br></code><b>Throws</b>: Any 1452 exceptions propagated from the implementation of 1453 <code>initiate_impl()</code></p> 1454 <pre> 1455void <a name="event_processor::process_event" id= 1456"event_processor::process_event">process_event</a>( const event_base & evt ); 1457</pre> 1458 1459 <p><b>Effects</b>: <code>process_event_impl( evt 1460 );<br></code><b>Throws</b>: Any exceptions propagated from the 1461 implementation of <code>process_event_impl()</code></p> 1462 <pre> 1463void <a name="event_processor::terminate" id= 1464"event_processor::terminate">terminate</a>(); 1465</pre> 1466 1467 <p><b>Effects</b>: <code>terminate_impl();<br></code><b>Throws</b>: Any 1468 exceptions propagated from the implementation of 1469 <code>terminate_impl()</code></p> 1470 1471 <h3>Class template <code>event_processor</code> observer functions</h3> 1472 <pre> 1473Scheduler & <a name="my_scheduler" id= 1474"my_scheduler">my_scheduler</a>() const; 1475</pre> 1476 1477 <p><b>Returns</b>: The <code>Scheduler</code> reference obtained in the 1478 constructor</p> 1479 <pre> 1480processor_handle <a name="my_handle" id="my_handle">my_handle</a>() const; 1481</pre> 1482 1483 <p><b>Returns</b>: The <code>processor_handle</code> object obtained in the 1484 constructor</p> 1485 1486 <h1>Header <boost/statechart/<a name="fifo_scheduler.hpp" id= 1487 "fifo_scheduler.hpp">fifo_scheduler.hpp</a>></h1> 1488 1489 <h2><a name="ClassTemplatefifo_scheduler" id= 1490 "ClassTemplatefifo_scheduler">Class template 1491 <code>fifo_scheduler</code></a></h2> 1492 1493 <p>This class template is a model of the <a href="#Scheduler">Scheduler</a> 1494 concept.</p> 1495 1496 <h3>Class template <code>fifo_scheduler</code> parameters</h3> 1497 1498 <table border="3" cellpadding="2" width="100%" summary= 1499 "fifo_scheduler parameters"> 1500 <tr> 1501 <td><b>Template parameter</b></td> 1502 1503 <td><b>Requirements</b></td> 1504 1505 <td><b>Semantics</b></td> 1506 1507 <td><b>Default</b></td> 1508 </tr> 1509 1510 <tr> 1511 <td><code>FifoWorker</code></td> 1512 1513 <td>A model of the FifoWorker concept</td> 1514 1515 <td>see <a href="#FifoWorker">FifoWorker</a> concept</td> 1516 1517 <td><code>fifo_worker<></code></td> 1518 </tr> 1519 1520 <tr> 1521 <td><code>Allocator</code></td> 1522 1523 <td>A model of the standard Allocator concept</td> 1524 1525 <td> </td> 1526 1527 <td><code>std::allocator< void ></code></td> 1528 </tr> 1529 </table> 1530 1531 <h3>Class template <code>fifo_scheduler</code> synopsis</h3> 1532 <pre> 1533namespace boost 1534{ 1535namespace statechart 1536{ 1537 template< 1538 class FifoWorker = fifo_worker<>, 1539 class Allocator = std::allocator< void > > 1540 class fifo_scheduler : noncopyable 1541 { 1542 public: 1543 <a href= 1544"#fifo_scheduler::fifo_scheduler">fifo_scheduler</a>( bool waitOnEmptyQueue = false ); 1545 1546 typedef <i>implementation-defined</i> processor_handle; 1547 1548 class processor_context : noncopyable 1549 { 1550 processor_context( 1551 fifo_scheduler & scheduler, 1552 const processor_handle & theHandle ); 1553 1554 fifo_scheduler & my_scheduler() const; 1555 const processor_handle & my_handle() const; 1556 1557 friend class fifo_scheduler; 1558 friend class event_processor< fifo_scheduler >; 1559 }; 1560 1561 template< class Processor > 1562 processor_handle <a href="#create_processor">create_processor</a>(); 1563 template< class Processor, typename Param1 > 1564 processor_handle <a href= 1565"#create_processor1">create_processor</a>( Param1 param1 ); 1566 1567 // More create_processor overloads 1568 1569 void <a href= 1570"#destroy_processor">destroy_processor</a>( processor_handle processor ); 1571 1572 void <a href= 1573"#initiate_processor">initiate_processor</a>( processor_handle processor ); 1574 void <a href= 1575"#terminate_processor">terminate_processor</a>( processor_handle processor ); 1576 1577 typedef intrusive_ptr< const event_base > event_ptr_type; 1578 1579 void <a href="#queue_event">queue_event</a>( 1580 const processor_handle & processor, 1581 const event_ptr_type & pEvent ); 1582 1583 typedef typename FifoWorker::work_item work_item; 1584 1585 void <a href= 1586"#queue_work_item">queue_work_item</a>( const work_item & item ); 1587 1588 void <a href="#fifo_scheduler::terminate">terminate</a>(); 1589 bool <a href="#fifo_scheduler::terminated">terminated</a>() const; 1590 1591 unsigned long <a href="#operatorfuncall">operator()</a>( 1592 unsigned long maxEventCount = 0 ); 1593 }; 1594} 1595} 1596</pre> 1597 1598 <h3>Class template <code>fifo_scheduler</code> constructor</h3> 1599 <pre> 1600<a name="fifo_scheduler::fifo_scheduler" id= 1601"fifo_scheduler::fifo_scheduler">fifo_scheduler</a>( bool waitOnEmptyQueue = false ); 1602</pre> 1603 1604 <p><b>Effects</b>: Constructs a <code>fifo_scheduler<></code> object. 1605 In multi-threaded builds, <code>waitOnEmptyQueue</code> is forwarded to the 1606 constructor of a data member of type <code>FifoWorker</code>. In 1607 single-threaded builds, the <code>FifoWorker</code> data member is 1608 default-constructed<br> 1609 <b>Note</b>: In single-threaded builds the 1610 <code>fifo_scheduler<></code> constructor does not accept any 1611 parameters and <code>operator()()</code> thus always returns to the caller 1612 when the event queue is empty</p> 1613 1614 <h3>Class template <code>fifo_scheduler</code> modifier functions</h3> 1615 <pre> 1616template< class Processor > 1617processor_handle <a name="create_processor" id= 1618"create_processor">create_processor</a>(); 1619</pre> 1620 1621 <p><b>Requires</b>: The <code>Processor</code> type must be a direct or 1622 indirect subtype of the <a href= 1623 "#ClassTemplateevent_processor"><code>event_processor</code></a> class 1624 template<br> 1625 <b>Effects</b>: Creates and passes to 1626 <code>FifoWorker::queue_work_item()</code> an object of type 1627 <code>FifoWorker::work_item</code> that, when later executed in 1628 <code>FifoWorker::operator()()</code>, leads to a call to the constructor 1629 of <code>Processor</code>, passing an appropriate 1630 <code>processor_context</code> object as the only argument<br> 1631 <b>Returns</b>: A <code>processor_handle</code> object that henceforth 1632 identifies the created event processor object<br> 1633 <b>Throws</b>: Any exceptions propagated from 1634 <code>FifoWorker::work_item()</code> and 1635 <code>FifoWorker::queue_work_item()</code><br> 1636 <b>Caution</b>: The current implementation of this function makes an 1637 (indirect) call to global <code>operator new()</code>. Unless global 1638 <code>operator new()</code> is replaced, care must be taken when to call 1639 this function in applications with hard real-time requirements</p> 1640 <pre> 1641template< class Processor, typename Param1 > 1642processor_handle <a name="create_processor1" id= 1643"create_processor1">create_processor( Param1 param1 )</a>; 1644</pre> 1645 1646 <p><b>Requires</b>: The <code>Processor</code> type must be a direct or 1647 indirect subtype of the <a href= 1648 "#ClassTemplateevent_processor"><code>event_processor</code></a> class 1649 template<br> 1650 <b>Effects</b>: Creates and passes to 1651 <code>FifoWorker::queue_work_item()</code> an object of type 1652 <code>FifoWorker::work_item</code> that, when later executed in 1653 <code>FifoWorker::operator()()</code>, leads to a call to the constructor 1654 of <code>Processor</code>, passing an appropriate 1655 <code>processor_context</code> object and <code>param1</code> as 1656 arguments<br> 1657 <b>Returns</b>: A <code>processor_handle</code> object that henceforth 1658 identifies the created event processor object<br> 1659 <b>Throws</b>: Any exceptions propagated from 1660 <code>FifoWorker::work_item()</code> and 1661 <code>FifoWorker::queue_work_item()</code><b><br> 1662 Note</b>: <code>boost::ref()</code> and <code>boost::cref()</code> can be 1663 used to pass arguments by reference rather than by copy. 1664 <code>fifo_scheduler<></code> has 5 additional 1665 <code>create_processor<></code> overloads, allowing to pass up to 6 1666 custom arguments to the constructors of event processors<br> 1667 <b>Caution</b>: The current implementation of this and all other overloads 1668 make (indirect) calls to global <code>operator new()</code>. Unless global 1669 <code>operator new()</code> is replaced, care must be taken when to call 1670 these overloads in applications with hard real-time requirements</p> 1671 <pre> 1672void <a name="destroy_processor" id= 1673"destroy_processor">destroy_processor</a>( processor_handle processor ); 1674</pre> 1675 1676 <p><b>Requires</b>: <code>processor</code> was obtained from a call to one 1677 of the <code>create_processor<>()</code> overloads on the same 1678 <code>fifo_scheduler<></code> object<br> 1679 <b>Effects</b>: Creates and passes to 1680 <code>FifoWorker::queue_work_item()</code> an object of type 1681 <code>FifoWorker::work_item</code> that, when later executed in 1682 <code>FifoWorker::operator()()</code>, leads to a call to the destructor of 1683 the event processor object associated with <code>processor</code>. The 1684 object is silently discarded if the event processor object has been 1685 destructed before<br> 1686 <b>Throws</b>: Any exceptions propagated from 1687 <code>FifoWorker::work_item()</code> and 1688 <code>FifoWorker::queue_work_item()</code><br> 1689 <b>Caution</b>: The current implementation of this function leads to an 1690 (indirect) call to global <code>operator delete()</code> (the call is made 1691 when the last <code>processor_handle</code> object associated with the 1692 event processor object is destructed). Unless global <code>operator 1693 delete()</code> is replaced, care must be taken when to call this function 1694 in applications with hard real-time requirements</p> 1695 <pre> 1696void <a name="initiate_processor" id= 1697"initiate_processor">initiate_processor</a>( processor_handle processor ); 1698</pre> 1699 1700 <p><b>Requires</b>: <code>processor</code> was obtained from a call to one 1701 of the <code>create_processor()</code> overloads on the same 1702 <code>fifo_scheduler<></code> object<br> 1703 <b>Effects</b>: Creates and passes to 1704 <code>FifoWorker::queue_work_item()</code> an object of type 1705 <code>FifoWorker::work_item</code> that, when later executed in 1706 <code>FifoWorker::operator()()</code>, leads to a call to <code><a href= 1707 "#event_processor::initiate">initiate</a>()</code> on the event processor 1708 object associated with <code>processor</code>. The object is silently 1709 discarded if the event processor object has been destructed before<br> 1710 <b>Throws</b>: Any exceptions propagated from 1711 <code>FifoWorker::work_item()</code> and 1712 <code>FifoWorker::queue_work_item()</code></p> 1713 <pre> 1714void <a name="terminate_processor" id= 1715"terminate_processor">terminate_processor</a>( processor_handle processor ); 1716</pre> 1717 1718 <p><b>Requires</b>: <code>processor</code> was obtained from a call to one 1719 of the <code>create_processor<>()</code> overloads on the same 1720 <code>fifo_scheduler<></code> object<br> 1721 <b>Effects</b>: Creates and passes to 1722 <code>FifoWorker::queue_work_item()</code> an object of type 1723 <code>FifoWorker::work_item</code> that, when later executed in 1724 <code>FifoWorker::operator()()</code>, leads to a call to <code><a href= 1725 "#event_processor::terminate">terminate</a>()</code> on the event processor 1726 object associated with <code>processor</code>. The object is silently 1727 discarded if the event processor object has been destructed before<br> 1728 <b>Throws</b>: Any exceptions propagated from 1729 <code>FifoWorker::work_item()</code> and 1730 <code>FifoWorker::queue_work_item()</code></p> 1731 <pre> 1732void <a name="queue_event" id="queue_event">queue_event</a>( 1733 const processor_handle & processor, 1734 const event_ptr_type & pEvent ); 1735</pre> 1736 1737 <p><b>Requires</b>: <code>pEvent.get() != 0</code> and 1738 <code>processor</code> was obtained from a call to one of the 1739 <code>create_processor<>()</code> overloads on the same 1740 <code>fifo_scheduler<></code> object<br> 1741 <b>Effects</b>: Creates and passes to 1742 <code>FifoWorker::queue_work_item()</code> an object of type 1743 <code>FifoWorker::work_item</code> that, when later executed in 1744 <code>FifoWorker::operator()()</code>, leads to a call to <code><a href= 1745 "#event_processor::process_event">process_event</a>( *pEvent )</code> on 1746 the event processor object associated with <code>processor</code>. The 1747 object is silently discarded if the event processor object has been 1748 destructed before<br> 1749 <b>Throws</b>: Any exceptions propagated from 1750 <code>FifoWorker::work_item()</code> and 1751 <code>FifoWorker::queue_work_item()</code></p> 1752 <pre> 1753void <a name="queue_work_item" id= 1754"queue_work_item">queue_work_item</a>( const work_item & item ); 1755</pre> 1756 1757 <p><b>Effects</b>: <code>FifoWorker::queue_work_item( item );</code><br> 1758 <b>Throws</b>: Any exceptions propagated from the above call</p> 1759 <pre> 1760void <a name="fifo_scheduler::terminate" id= 1761"fifo_scheduler::terminate">terminate</a>(); 1762</pre> 1763 1764 <p><b>Effects</b>: <code>FifoWorker::terminate()</code><br> 1765 <b>Throws</b>: Any exceptions propagated from the above call</p> 1766 <pre> 1767unsigned long <a name="operatorfuncall" id= 1768"operatorfuncall">operator()</a>( unsigned long maxEventCount = 0 ); 1769</pre> 1770 1771 <p><b>Requires</b>: Must only be called from exactly one thread<b><br> 1772 Effects</b>: <code>FifoWorker::operator()( maxEventCount )</code><br> 1773 <b>Returns</b>: The return value of the above call<br> 1774 <b>Throws</b>: Any exceptions propagated from the above call</p> 1775 1776 <h3>Class template <code>fifo_scheduler</code> observer functions</h3> 1777 <pre> 1778bool <a name="fifo_scheduler::terminated" id= 1779"fifo_scheduler::terminated">terminated</a>() const; 1780</pre> 1781 1782 <p><b>Requires</b>: Must only be called from the thread that also calls 1783 <code>operator()()</code><br> 1784 <b>Returns</b>: <code>FifoWorker::terminated();</code></p> 1785 1786 <h1>Header <boost/statechart/<a name="exception_translator.hpp" id= 1787 "exception_translator.hpp">exception_translator.hpp</a>></h1> 1788 1789 <h2><a name="ClassTemplateexception_translator" id= 1790 "ClassTemplateexception_translator">Class template 1791 <code>exception_translator</code></a></h2> 1792 1793 <p>This class template is a model of the <a href= 1794 "#ExceptionTranslator">ExceptionTranslator</a> concept.</p> 1795 1796 <h3>Class template <code>exception_translator</code> parameters</h3> 1797 1798 <table border="3" cellpadding="2" width="100%" summary= 1799 "exception_translator parameters"> 1800 <tr> 1801 <td><b>Template parameter</b></td> 1802 1803 <td><b>Requirements</b></td> 1804 1805 <td><b>Semantics</b></td> 1806 1807 <td><b>Default</b></td> 1808 </tr> 1809 1810 <tr> 1811 <td><code>ExceptionEvent</code></td> 1812 1813 <td>A model of the <a href="#Event">Event</a> concept</td> 1814 1815 <td>The type of event that is dispatched when an exception 1816 is propagated into the framework</td> 1817 1818 <td><code>exception_thrown</code></td> 1819 </tr> 1820 </table> 1821 1822 <h3>Class template <code>exception_translator</code> synopsis & 1823 semantics</h3> 1824 <pre> 1825namespace boost 1826{ 1827namespace statechart 1828{ 1829 class exception_thrown : public event< exception_thrown > {}; 1830 1831 template< class ExceptionEvent = exception_thrown > 1832 class exception_translator 1833 { 1834 public: 1835 template< class Action, class ExceptionEventHandler > 1836 result operator()( 1837 Action action, 1838 ExceptionEventHandler eventHandler ) 1839 { 1840 try 1841 { 1842 return action(); 1843 } 1844 catch( ... ) 1845 { 1846 return eventHandler( ExceptionEvent() ); 1847 } 1848 } 1849 }; 1850} 1851} 1852</pre> 1853 1854 <h1>Header <boost/statechart/<br> 1855 <a name="null_exception_translator.hpp" id= 1856 "null_exception_translator.hpp">null_exception_translator.hpp</a>></h1> 1857 1858 <h2><a name="Classnull_exception_translator" id= 1859 "Classnull_exception_translator">Class 1860 <code>null_exception_translator</code></a></h2> 1861 1862 <p>This class is a model of the <a href= 1863 "#ExceptionTranslator">ExceptionTranslator</a> concept.</p> 1864 1865 <h3>Class <code>null_exception_translator</code> synopsis & 1866 semantics</h3> 1867 <pre> 1868namespace boost 1869{ 1870namespace statechart 1871{ 1872 class null_exception_translator 1873 { 1874 public: 1875 template< class Action, class ExceptionEventHandler > 1876 result operator()( 1877 Action action, ExceptionEventHandler ) 1878 { 1879 return action(); 1880 } 1881 }; 1882} 1883} 1884</pre> 1885 1886 <h1>Header <boost/statechart/<a name="simple_state.hpp" id= 1887 "simple_state.hpp">simple_state.hpp</a>></h1> 1888 1889 <h2><a name="Enumhistory_mode" id="Enumhistory_mode">Enum 1890 <code>history_mode</code></a></h2> 1891 1892 <p>Defines the history type of a state.</p> 1893 <pre> 1894namespace boost 1895{ 1896namespace statechart 1897{ 1898 enum history_mode 1899 { 1900 has_no_history, 1901 has_shallow_history, 1902 has_deep_history, 1903 has_full_history // shallow & deep 1904 }; 1905} 1906} 1907</pre> 1908 1909 <h2><a name="ClassTemplatesimple_state" id= 1910 "ClassTemplatesimple_state">Class template 1911 <code>simple_state</code></a></h2> 1912 1913 <p>This is the base class template for all models of the <a href= 1914 "#SimpleState">SimpleState</a> concept. Such models must not call any of 1915 the following <code>simple_state<></code> member functions from their 1916 constructors:</p> 1917 <pre> 1918void <b>post_event</b>( 1919 const intrusive_ptr< const event_base > & ); 1920void <b>post_event</b>( const event_base & ); 1921 1922template< 1923 class HistoryContext, 1924 <i>implementation-defined-unsigned-integer-type 1925</i> orthogonalPosition > 1926void <b>clear_shallow_history</b>(); 1927template< 1928 class HistoryContext, 1929 <i>implementation-defined-unsigned-integer-type 1930</i> orthogonalPosition > 1931void <b>clear_deep_history</b>(); 1932 1933outermost_context_type & <b>outermost_context</b>(); 1934const outermost_context_type & <b>outermost_context</b>() const; 1935 1936template< class OtherContext > 1937OtherContext & <b>context</b>(); 1938template< class OtherContext > 1939const OtherContext & <b>context</b>() const; 1940 1941template< class Target > 1942Target <b>state_cast</b>() const; 1943template< class Target > 1944Target <b>state_downcast</b>() const; 1945 1946state_iterator <b>state_begin</b>() const; 1947state_iterator <b>state_end</b>() const; 1948 1949const event_base * <b>triggering_event</b>() const; 1950</pre> 1951 1952 <p>States that need to call any of these member functions from their 1953 constructors must derive from the <code><a href= 1954 "#ClassTemplatestate">state</a></code> class template.</p> 1955 1956 <h3>Class template <code>simple_state</code> parameters</h3> 1957 1958 <table border="3" cellpadding="2" width="100%" summary= 1959 "simple_state parameters"> 1960 <tr> 1961 <td><b>Template parameter</b></td> 1962 1963 <td><b>Requirements</b></td> 1964 1965 <td><b>Semantics</b></td> 1966 1967 <td><b>Default</b></td> 1968 </tr> 1969 1970 <tr> 1971 <td><code>MostDerived</code></td> 1972 1973 <td>The most-derived subtype of this class template</td> 1974 1975 <td> </td> 1976 1977 <td> </td> 1978 </tr> 1979 1980 <tr> 1981 <td><code>Context</code></td> 1982 1983 <td>A most-derived direct or indirect subtype of the 1984 <code><a href="#ClassTemplatestate_machine">state_machine</a></code> or 1985 <code><a href= 1986 "#ClassTemplateasynchronous_state_machine">asynchronous_state_machine</a></code> 1987 class templates or a model of the <a href= 1988 "#SimpleState">SimpleState</a> or <a href="#State">State</a> concepts 1989 or an instantiation of the <code><a href= 1990 "#ClassTemplatesimple_state">simple_state<>::orthogonal</a></code> 1991 class template. Must be a complete type</td> 1992 1993 <td>Defines the states' position in the state 1994 hierarchy</td> 1995 1996 <td> </td> 1997 </tr> 1998 1999 <tr> 2000 <td><code>InnerInitial</code></td> 2001 2002 <td>An <code>mpl::list<></code> containing models of 2003 the <a href="#SimpleState">SimpleState</a> or <a href= 2004 "#State">State</a> concepts or instantiations of the <code><a href= 2005 "#ClassTemplateshallow_history">shallow_history</a></code> or 2006 <code><a href="#ClassTemplatedeep_history">deep_history</a></code> 2007 class templates. If there is only a single inner initial state that is 2008 not a template instantiation then it can also be passed directly, 2009 without wrapping it into an <code>mpl::list<></code>. The 2010 <code>Context</code> argument passed to the <code><a href= 2011 "#ClassTemplatesimple_state">simple_state<></a></code> or 2012 <code><a href="#ClassTemplatestate">state<></a></code> base 2013 of each state in the list must correspond to the orthogonal region 2014 it belongs to. That is, the first state in the list must pass 2015 <code>MostDerived::orthogonal< 0 ></code>, the second 2016 <code>MostDerived::orthogonal< 1 ></code> and so forth. 2017 <code>MostDerived::orthogonal< 0 ></code> and 2018 <code>MostDerived</code> are synonymous</td> 2019 2020 <td>Defines the inner initial state for each orthogonal 2021 region. By default, a state does not have inner states</td> 2022 2023 <td><i><code>unspecified</code></i></td> 2024 </tr> 2025 2026 <tr> 2027 <td><code>historyMode</code></td> 2028 2029 <td>One of the values defined in the <code><a href= 2030 "#Enumhistory_mode">history_mode</a></code> enumeration</td> 2031 2032 <td>Defines whether the state saves shallow, deep or both 2033 histories upon exit</td> 2034 2035 <td><code>has_no_history</code></td> 2036 </tr> 2037 </table> 2038 2039 <h3>Class template <code>simple_state</code> synopsis</h3> 2040 <pre> 2041namespace boost 2042{ 2043namespace statechart 2044{ 2045 template< 2046 class MostDerived, 2047 class Context, 2048 class InnerInitial = <i>unspecified</i>, 2049 history_mode historyMode = has_no_history > 2050 class simple_state : <i>implementation-defined</i> 2051 { 2052 public: 2053 // by default, a state has no reactions 2054 typedef mpl::list<> reactions; 2055 2056 // see template parameters 2057 template< <i>implementation-defined-unsigned-integer-type 2058</i> innerOrthogonalPosition > 2059 struct orthogonal 2060 { 2061 // <i>implementation-defined</i> 2062 }; 2063 2064 typedef typename Context::outermost_context_type 2065 outermost_context_type; 2066 2067 outermost_context_type & <a href= 2068"#outermost_context">outermost_context</a>(); 2069 const outermost_context_type & <a href= 2070"#outermost_contextconst">outermost_context</a>() const; 2071 2072 template< class OtherContext > 2073 OtherContext & <a href="#context">context</a>(); 2074 template< class OtherContext > 2075 const OtherContext & <a href="#contextconst">context</a>() const; 2076 2077 template< class Target > 2078 Target <a href="#simple_state::state_cast">state_cast</a>() const; 2079 template< class Target > 2080 Target <a href= 2081"#simple_state::state_downcast">state_downcast</a>() const; 2082 2083 // a model of the StateBase concept 2084 typedef <i>implementation-defined</i> state_base_type; 2085 // a model of the standard Forward Iterator concept 2086 typedef <i>implementation-defined</i> state_iterator; 2087 2088 state_iterator <a href= 2089"#simple_state::state_begin">state_begin</a>() const; 2090 state_iterator <a href= 2091"#simple_state::state_end">state_end</a>() const; 2092 2093 const event_base * <a href="#triggering_event0">triggering_event</a>() const; 2094 2095 void <a href="#post_event0">post_event</a>( 2096 const intrusive_ptr< const <a href= 2097"#Classevent_base">event_base</a> > & ); 2098 void <a href="#post_event1">post_event</a>( const <a href= 2099"#Classevent_base">event_base</a> & ); 2100 2101 <a href="#Classresult">result</a> <a href= 2102"#discard_event">discard_event</a>(); 2103 <a href="#Classresult">result</a> <a href= 2104"#forward_event">forward_event</a>(); 2105 <a href="#Classresult">result</a> <a href= 2106"#defer_event">defer_event</a>(); 2107 template< class DestinationState > 2108 <a href="#Classresult">result</a> <a href="#transit1">transit</a>(); 2109 template< 2110 class DestinationState, 2111 class TransitionContext, 2112 class Event > 2113 <a href="#Classresult">result</a> <a href="#transit2">transit</a>( 2114 void ( TransitionContext::* )( const Event & ), 2115 const Event & ); 2116 <a href="#Classresult">result</a> <a href= 2117"#simple_state::terminate">terminate</a>(); 2118 2119 template< 2120 class HistoryContext, 2121 <i>implementation-defined-unsigned-integer-type 2122</i> orthogonalPosition > 2123 void <a href="#clear_shallow_history">clear_shallow_history</a>(); 2124 template< 2125 class HistoryContext, 2126 <i>implementation-defined-unsigned-integer-type 2127</i> orthogonalPosition > 2128 void <a href="#clear_deep_history">clear_deep_history</a>(); 2129 2130 static id_type <a href="#static_type">static_type</a>(); 2131 2132 template< class CustomId > 2133 static const CustomId * <a href= 2134"#custom_static_type_ptr">custom_static_type_ptr</a>(); 2135 2136 template< class CustomId > 2137 static void <a href= 2138"#custom_static_type_ptr1">custom_static_type_ptr</a>( const CustomId * ); 2139 2140 // see <a href="#transit1">transit</a>() or <a href= 2141"#simple_state::terminate">terminate</a>() effects 2142 void exit() {} 2143 2144 protected: 2145 <a href="#simple_state">simple_state</a>(); 2146 <a href="#simple_statedtor">~simple_state</a>(); 2147 }; 2148} 2149} 2150</pre> 2151 2152 <h3>Class template <code>simple_state</code> constructor and 2153 destructor</h3> 2154 <pre> 2155<a name="simple_state" id="simple_state">simple_state</a>(); 2156</pre> 2157 2158 <p><b>Effects</b>: Constructs a state object</p> 2159 <pre> 2160<a name="simple_statedtor" id="simple_statedtor">~simple_state</a>(); 2161</pre> 2162 2163 <p><b>Effects</b>: If the state has deferral reactions of which at least 2164 one has been triggered during the lifetime of the state then the contents 2165 of the deferred events queue is moved to the front of the posted events 2166 queue.</p> 2167 2168 <h3>Class template <code>simple_state</code> modifier functions</h3> 2169 <pre> 2170void <a name="post_event0" id="post_event0">post_event</a>( 2171 const intrusive_ptr< const <a href= 2172"#Classevent_base">event_base</a> > & pEvt ); 2173</pre> 2174 2175 <p><b>Requires</b>: If called from a constructor of a direct or indirect 2176 subtype then the most-derived type must directly or indirectly derive from 2177 the <code>state</code> class template<b>.</b> All direct and indirect 2178 callers must be exception-neutral<b><br> 2179 Effects</b>: <a href= 2180 "#outermost_context"><code>outermost_context</code></a><code>().<a href= 2181 "#post_event2">post_event</a>( pEvt );</code><br> 2182 <b>Throws</b>: Whatever the above call throws</p> 2183 <pre> 2184void <a name="post_event1" id="post_event1">post_event</a>( const <a href= 2185"#Classevent_base">event_base</a> & evt ); 2186</pre> 2187 2188 <p><b>Requires</b>: If called from a constructor of a direct or indirect 2189 subtype then the most-derived type must directly or indirectly derive from 2190 the <code>state</code> class template<b>.</b> All direct and indirect 2191 callers must be exception-neutral<b><br> 2192 Effects</b>: <a href= 2193 "#outermost_context"><code>outermost_context</code></a><code>().<a href= 2194 "#post_event3">post_event</a>( evt );</code><br> 2195 <b>Throws</b>: Whatever the above call throws</p> 2196 <pre> 2197<a href="#Classresult">result</a> <a name="discard_event" id= 2198"discard_event">discard_event</a>(); 2199</pre> 2200 2201 <p><b>Requires</b>: Must only be called from within <code>react</code> 2202 member functions, which are called by <code><a href= 2203 "#ClassTemplatecustom_reaction">custom_reaction<></a></code> 2204 instantiations. All direct and indirect callers must be 2205 exception-neutral<br> 2206 <b>Effects</b>: Instructs the state machine to discard the current event 2207 and to continue with the processing of the remaining events (see 2208 <code><a href= 2209 "#process_event">state_machine<>::process_event</a>()</code> for 2210 details)<br> 2211 <b>Returns</b>: A <code><a href="#Classresult">result</a></code> object. 2212 The user-supplied <code>react</code> member function must return this 2213 object to its caller</p> 2214 <pre> 2215<a href="#Classresult">result</a> <a name="forward_event" id= 2216"forward_event">forward_event</a>(); 2217</pre> 2218 2219 <p><b>Requires</b>: Must only be called from within <code>react</code> 2220 member functions, which are called by <code><a href= 2221 "#ClassTemplatecustom_reaction">custom_reaction<></a></code> 2222 instantiations. All direct and indirect callers must be 2223 exception-neutral<br> 2224 <b>Effects</b>: Instructs the state machine to forward the current event to 2225 the next state (see <code><a href= 2226 "#process_event">state_machine<>::process_event</a>()</code> for 2227 details)<br> 2228 <b>Returns</b>: A <code><a href="#Classresult">result</a></code> object. 2229 The user-supplied <code>react</code> member function must return this 2230 object to its caller</p> 2231 <pre> 2232<a href="#Classresult">result</a> <a name="defer_event" id= 2233"defer_event">defer_event</a>(); 2234</pre> 2235 2236 <p><b>Requires</b>: Must only be called from within <code>react</code> 2237 member functions, which are called by <code><a href= 2238 "#ClassTemplatecustom_reaction">custom_reaction<></a></code> 2239 instantiations. All direct and indirect callers must be 2240 exception-neutral<br> 2241 <b>Effects</b>: Instructs the state machine to defer the current event and 2242 to continue with the processing of the remaining events (see <code><a href= 2243 "#process_event">state_machine<>::process_event</a>()</code> for 2244 details)<br> 2245 <b>Returns</b>: A <code><a href="#Classresult">result</a></code> object. 2246 The user-supplied <code>react</code> member function must return this 2247 object to its caller<br> 2248 <b>Throws</b>: Any exceptions propagated from 2249 <code>Allocator::rebind<>::other::allocate()</code> (the template 2250 parameter passed to the base class of 2251 <code>outermost_context_type</code>)</p> 2252 <pre> 2253template< class DestinationState > 2254<a href="#Classresult">result</a> <a name="transit1" id= 2255"transit1">transit</a>(); 2256</pre> 2257 2258 <p><b>Requires</b>: Must only be called from within <code>react</code> 2259 member functions, which are called by <code><a href= 2260 "#ClassTemplatecustom_reaction">custom_reaction<></a></code> 2261 instantiations. All direct and indirect callers must be 2262 exception-neutral<br> 2263 <b>Effects</b>:</p> 2264 2265 <ol> 2266 <li>Exits all currently active direct and indirect inner states of the 2267 innermost common context of this state and <code>DestinationState</code>. 2268 Innermost states are exited first. Other states are exited as soon as all 2269 their direct and indirect inner states have been exited. The inner states 2270 of each state are exited according to the number of their orthogonal 2271 region. The state in the orthogonal region with the highest number is 2272 always exited first, then the state in the region with the second-highest 2273 number and so on.<br> 2274 The process of exiting a state consists of the following steps: 2275 2276 <ol> 2277 <li>If there is an exception pending that has not yet been handled 2278 successfully then only step 5 is executed</li> 2279 2280 <li>Calls the <code>exit</code> member function (see <a href= 2281 "#ClassTemplatesimple_state">synopsis</a>) of the most-derived state 2282 object. If <code>exit()</code> throws then steps 3 and 4 are not 2283 executed</li> 2284 2285 <li>If the state has shallow history then shallow history information 2286 is saved</li> 2287 2288 <li>If the state is an innermost state then deep history information 2289 is saved for all direct and indirect outer states that have deep 2290 history</li> 2291 2292 <li>The state object is destructed</li> 2293 </ol> 2294 </li> 2295 2296 <li>Enters (constructs) the state that is both a direct inner state of 2297 the innermost common context and either the <code>DestinationState</code> 2298 itself or a direct or indirect outer state of 2299 <code>DestinationState</code></li> 2300 2301 <li>Enters (constructs) the tree formed by the direct and indirect inner 2302 states of the previously entered state down to the 2303 <code>DestinationState</code> and beyond depth first. The inner states of 2304 each state are entered according to the number of their orthogonal 2305 region. The state in orthogonal region 0 is always entered first, then 2306 the state in region 1 and so on</li> 2307 2308 <li>Instructs the state machine to discard the current event and to 2309 continue with the processing of the remaining events (see <code><a href= 2310 "#process_event">state_machine<>::process_event</a>()</code> for 2311 details)</li> 2312 </ol> 2313 2314 <p><b>Returns</b>: A <code><a href="#Classresult">result</a></code> object. 2315 The user-supplied <code>react</code> member function must return this 2316 object to its caller<br> 2317 <b>Throws</b>: Any exceptions propagated from:</p> 2318 2319 <ul> 2320 <li><code>Allocator::rebind<>::other::allocate()</code> (the 2321 template parameter passed to the base class of 2322 <code>outermost_context_type</code>)</li> 2323 2324 <li>state constructors</li> 2325 2326 <li><code>exit</code> member functions</li> 2327 </ul> 2328 2329 <p><b>Caution</b>: Inevitably destructs this state before returning to the 2330 calling <code>react</code> member function, which must therefore not 2331 attempt to access anything except stack objects before returning to its 2332 caller</p> 2333 <pre> 2334template< 2335 class DestinationState, 2336 class TransitionContext, 2337 class Event > 2338<a href="#Classresult">result</a> <a name="transit2" id= 2339"transit2">transit</a>( 2340 void ( TransitionContext::* )( const Event & ), 2341 const Event & ); 2342</pre> 2343 2344 <p><b>Requires</b>: Must only be called from within <code>react</code> 2345 member functions, which are called by <code><a href= 2346 "#ClassTemplatecustom_reaction">custom_reaction<></a></code> 2347 instantiations. All direct and indirect callers must be 2348 exception-neutral<br> 2349 <b>Effects</b>:</p> 2350 2351 <ol> 2352 <li>Exits all currently active direct and indirect inner states of the 2353 innermost common context of this state and <code>DestinationState</code>. 2354 Innermost states are exited first. Other states are exited as soon as all 2355 their direct and indirect inner states have been exited. The inner states 2356 of each state are exited according to the number of their orthogonal 2357 region. The state in the orthogonal region with the highest number is 2358 always exited first, then the state in the region with the second-highest 2359 number and so on.<br> 2360 The process of exiting a state consists of the following steps: 2361 2362 <ol> 2363 <li>If there is an exception pending that has not yet been handled 2364 successfully then only step 5 is executed</li> 2365 2366 <li>Calls the <code>exit</code> member function (see <a href= 2367 "#ClassTemplatesimple_state">synopsis</a>) of the most-derived state 2368 object. If <code>exit()</code> throws then steps 3 and 4 are not 2369 executed</li> 2370 2371 <li>If the state has shallow history then shallow history information 2372 is saved</li> 2373 2374 <li>If the state is an innermost state then deep history information 2375 is saved for all direct and indirect outer states that have deep 2376 history</li> 2377 2378 <li>The state object is destructed</li> 2379 </ol> 2380 </li> 2381 2382 <li>Executes the passed transition action, forwarding the passed 2383 event</li> 2384 2385 <li>Enters (constructs) the state that is both a direct inner state of 2386 the innermost common context and either the <code>DestinationState</code> 2387 itself or a direct or indirect outer state of 2388 <code>DestinationState</code></li> 2389 2390 <li>Enters (constructs) the tree formed by the direct and indirect inner 2391 states of the previously entered state down to the 2392 <code>DestinationState</code> and beyond depth first. The inner states of 2393 each state are entered according to the number of their orthogonal 2394 region. The state in orthogonal region 0 is always entered first, then 2395 the state in region 1 and so on</li> 2396 2397 <li>Instructs the state machine to discard the current event and to 2398 continue with the processing of the remaining events (see <code><a href= 2399 "#process_event">state_machine<>::process_event</a>()</code> for 2400 details)</li> 2401 </ol> 2402 2403 <p><b>Returns</b>: A <code><a href="#Classresult">result</a></code> object. 2404 The user-supplied <code>react</code> member function must return this 2405 object to its caller<br> 2406 <b>Throws</b>: Any exceptions propagated from:</p> 2407 2408 <ul> 2409 <li><code>Allocator::rebind<>::other::allocate()</code> (the 2410 template parameter passed to the base class of 2411 <code>outermost_context_type</code>)</li> 2412 2413 <li>state constructors</li> 2414 2415 <li><code>exit</code> member functions</li> 2416 2417 <li>the transition action</li> 2418 </ul> 2419 2420 <p><b>Caution</b>: Inevitably destructs this state before returning to the 2421 calling <code>react</code> member function, which must therefore not 2422 attempt to access anything except stack objects before returning to its 2423 caller</p> 2424 <pre> 2425<a href="#Classresult">result</a> <a name="simple_state::terminate" id= 2426"simple_state::terminate">terminate</a>(); 2427</pre> 2428 2429 <p><b>Requires</b>: Must only be called from within <code>react</code> 2430 member functions, which are called by <code><a href= 2431 "#ClassTemplatecustom_reaction">custom_reaction<></a></code> 2432 instantiations. All direct and indirect callers must be 2433 exception-neutral<br> 2434 <b>Effects</b>: Exits this state and all its direct and indirect inner 2435 states. Innermost states are exited first. Other states are exited as soon 2436 as all their direct and indirect inner states have been exited. The inner 2437 states of each state are exited according to the number of their orthogonal 2438 region. The state in the orthogonal region with the highest number is 2439 always exited first, then the state in the region with the second-highest 2440 number and so on.<br> 2441 The process of exiting a state consists of the following steps:</p> 2442 2443 <ol> 2444 <li>If there is an exception pending that has not yet been handled 2445 successfully then only step 5 is executed</li> 2446 2447 <li>Calls the <code>exit</code> member function (see <a href= 2448 "#ClassTemplatesimple_state">synopsis</a>) of the most-derived state 2449 object. If <code>exit()</code> throws then steps 3 and 4 are not 2450 executed</li> 2451 2452 <li>If the state has shallow history then shallow history information is 2453 saved</li> 2454 2455 <li>If the state is an innermost state then deep history information is 2456 saved for all direct and indirect outer states that have deep 2457 history</li> 2458 2459 <li>The state object is destructed</li> 2460 </ol> 2461 2462 <p>Also instructs the state machine to discard the current event and to 2463 continue with the processing of the remaining events (see <code><a href= 2464 "#process_event">state_machine<>::process_event</a>()</code> for 2465 details)<br> 2466 <b>Returns</b>: A <code><a href="#Classresult">result</a></code> object. 2467 The user-supplied <code>react</code> member function must return this 2468 object to its caller<br> 2469 <b>Throws</b>: Any exceptions propagated from:</p> 2470 2471 <ul> 2472 <li><code>Allocator::rebind<>::other::allocate()</code> (the 2473 template parameter passed to the base class of 2474 <code>outermost_context_type</code>, used to allocate space to save 2475 history)</li> 2476 2477 <li><code>exit</code> member functions</li> 2478 </ul> 2479 2480 <p><b>Note</b>: If this state is the only currently active inner state of 2481 its direct outer state then the direct outer state is terminated also. The 2482 same applies recursively for all indirect outer states<br> 2483 <b>Caution</b>: Inevitably destructs this state before returning to the 2484 calling <code>react</code> member function, which must therefore not 2485 attempt to access anything except stack objects before returning to its 2486 caller</p> 2487 <pre> 2488template< 2489 class HistoryContext, 2490 <i>implementation-defined-unsigned-integer-type 2491</i> orthogonalPosition > 2492void <a name="clear_shallow_history" id= 2493"clear_shallow_history">clear_shallow_history</a>(); 2494</pre> 2495 2496 <p><b>Requires</b>: If called from a constructor of a direct or indirect 2497 subtype then the most-derived type must directly or indirectly derive from 2498 the <code>state</code> class template. The <code>historyMode</code> 2499 argument passed to the <code><a href= 2500 "#ClassTemplatesimple_state">simple_state<></a></code> or 2501 <code><a href="#ClassTemplatestate">state<></a></code> base 2502 of <code>HistoryContext</code> must be equal to 2503 <code>has_shallow_history</code> or <code>has_full_history</code><br> 2504 <b>Effects</b>: Clears the shallow history of the orthogonal region 2505 specified by <code>orthogonalPosition</code> of the state specified by 2506 <code>HistoryContext</code><br> 2507 <b>Throws</b>: Any exceptions propagated from 2508 <code>Allocator::rebind<>::other::allocate()</code> (the template 2509 parameter passed to the base class of 2510 <code>outermost_context_type</code>)</p> 2511 <pre> 2512template< 2513 class HistoryContext, 2514 <i>implementation-defined-unsigned-integer-type 2515</i> orthogonalPosition > 2516void <a name="clear_deep_history" id= 2517"clear_deep_history">clear_deep_history</a>(); 2518</pre> 2519 2520 <p><b>Requires</b>: If called from a constructor of a direct or indirect 2521 subtype then the most-derived type must directly or indirectly derive from 2522 the <code>state</code> class template. The <code>historyMode</code> 2523 argument passed to the <code><a href= 2524 "#ClassTemplatesimple_state">simple_state<></a></code> or 2525 <code><a href="#ClassTemplatestate">state<></a></code> base 2526 of <code>HistoryContext</code> must be equal to 2527 <code>has_deep_history</code> or <code>has_full_history</code><br> 2528 <b>Effects</b>: Clears the deep history of the orthogonal region specified 2529 by <code>orthogonalPosition</code> of the state specified by 2530 <code>HistoryContext</code><br> 2531 <b>Throws</b>: Any exceptions propagated from 2532 <code>Allocator::rebind<>::other::allocate()</code> (the template 2533 parameter passed to the base class of 2534 <code>outermost_context_type</code>)</p> 2535 2536 <h3>Class template <code>simple_state</code> observer functions</h3> 2537 <pre> 2538outermost_context_type & <a name="outermost_context" id= 2539"outermost_context">outermost_context</a>(); 2540</pre> 2541 2542 <p><b>Requires</b>: If called from a constructor of a direct or indirect 2543 subtype then the most-derived type must directly or indirectly derive from 2544 the <code>state</code> class template. If called from a destructor of a 2545 direct or indirect subtype then the <code>state_machine<></code> subclass 2546 portion must still exist<br> 2547 <b>Returns</b>: A reference to the outermost context, which is always the 2548 state machine this state belongs to<br></p> 2549 <pre> 2550const outermost_context_type & <a name="outermost_contextconst" id= 2551"outermost_contextconst">outermost_context() const</a>; 2552</pre> 2553 2554 <p><b>Requires</b>: If called from a constructor of a direct or indirect 2555 subtype then the most-derived type must directly or indirectly derive from 2556 the <code>state</code> class template. If called from a destructor of a 2557 direct or indirect subtype then the <code>state_machine<></code> subclass 2558 portion must still exist<br> 2559 <b>Returns</b>: A reference to the const outermost context, which is always 2560 the state machine this state belongs to</p> 2561 <pre> 2562template< class OtherContext > 2563OtherContext & <a name="context" id="context">context</a>(); 2564</pre> 2565 2566 <p><b>Requires</b>: If called from a constructor of a direct or indirect 2567 subtype then the most-derived type must directly or indirectly derive from 2568 the <code>state</code> class template. If called from a destructor of a 2569 direct or indirect subtype with a <code>state_machine<></code> subtype as 2570 argument then the <code>state_machine<></code> subclass portion must still 2571 exist<br> 2572 <b>Returns</b>: A reference to a direct or indirect context or any public base 2573 type of the contexts</p> 2574 <pre> 2575template< class OtherContext > 2576const OtherContext & <a name="contextconst" id= 2577"contextconst">context() const</a>; 2578</pre> 2579 2580 <p><b>Requires</b>: If called from a constructor of a direct or indirect 2581 subtype then the most-derived type must directly or indirectly derive from 2582 the <code>state</code> class template. If called from a destructor of a 2583 direct or indirect subtype with a <code>state_machine<></code> subtype as 2584 argument then the <code>state_machine<></code> subclass portion must still 2585 exist<br> 2586 <b>Returns</b>: A reference to a const direct or indirect context or any public 2587 base type of the contexts</p> 2588 <pre> 2589template< class Target > 2590Target <a name="simple_state::state_cast" id= 2591"simple_state::state_cast">state_cast</a>() const; 2592</pre> 2593 2594 <p><b>Requires</b>: If called from a constructor of a direct or indirect 2595 subtype then the most-derived type must directly or indirectly derive from 2596 the <code>state</code> class template<b><br> 2597 Returns</b>: Has exactly the same semantics as <code><a href= 2598 "#state_cast">state_machine<>::state_cast</a><>()</code><br> 2599 <b>Throws</b>: Has exactly the same semantics as <code><a href= 2600 "#state_cast">state_machine<>::state_cast</a><>()</code><b><br> 2601 Note</b>: The result is <b>unspecified</b> if this function is called when 2602 the machine is <a href= 2603 "definitions.html#UnstableStateMachine">unstable</a></p> 2604 <pre> 2605template< class Target > 2606Target <a name="simple_state::state_downcast" id= 2607"simple_state::state_downcast">state_downcast</a>() const; 2608</pre> 2609 2610 <p><b>Requires</b>: If called from a constructor of a direct or indirect 2611 subtype then the most-derived type must directly or indirectly derive from 2612 the <code>state</code> class template. Moreover, <code><a href= 2613 "#state_downcast">state_machine<>::state_downcast</a><>()</code> 2614 requirements also apply<br> 2615 <b>Returns</b>: Has exactly the same semantics as <code><a href= 2616 "#state_downcast">state_machine<>::state_downcast</a><>()</code><br> 2617 2618 <b>Throws</b>: Has exactly the same semantics as <code><a href= 2619 "#state_downcast">state_machine<>::state_downcast</a><>()</code><b><br> 2620 2621 Note</b>: The result is <b>unspecified</b> if this function is called when 2622 the machine is <a href= 2623 "definitions.html#UnstableStateMachine">unstable</a></p> 2624 <pre> 2625state_iterator <a name="simple_state::state_begin" id= 2626"simple_state::state_begin">state_begin</a>() const; 2627</pre> 2628 <pre> 2629state_iterator <a name="simple_state::state_end" id= 2630"simple_state::state_end">state_end</a>() const; 2631</pre> 2632 2633 <p><b>Require</b>: If called from a constructor of a direct or indirect 2634 subtype then the most-derived type must directly or indirectly derive from 2635 the <code>state</code> class template<b><br> 2636 Return</b>: Have exactly the same semantics as <code><a href= 2637 "#state_begin">state_machine<>::state_begin</a>()</code> and 2638 <code><a href= 2639 "#state_end">state_machine<>::state_end</a>()</code><br> 2640 <b>Note</b>: The result is <b>unspecified</b> if these functions are called 2641 when the machine is <a href= 2642 "definitions.html#UnstableStateMachine">unstable</a></p> 2643 <pre> 2644const event_base * <a name="triggering_event0" id="triggering_event0">triggering_event</a>(); 2645</pre> 2646 2647 <p><b>Returns</b>: Has exactly the same semantics as 2648 <code><a href="#triggering_event1">state_machine<>::triggering_event</a>()</code></p> 2649 2650 <h3>Class template <code>simple_state</code> static functions</h3> 2651 <pre> 2652static id_type <a name="static_type" id="static_type">static_type</a>(); 2653</pre> 2654 2655 <p><b>Returns</b>: A value unambiguously identifying the type of 2656 <code>MostDerived</code><br> 2657 <b>Note</b>: <code>id_type</code> values are comparable with 2658 <code>operator==()</code> and <code>operator!=()</code>. An unspecified 2659 collating order can be established with <code>std::less< id_type 2660 ></code></p> 2661 <pre> 2662template< class CustomId > 2663static const CustomId * <a name="custom_static_type_ptr" id= 2664"custom_static_type_ptr">custom_static_type_ptr</a>(); 2665</pre> 2666 2667 <p><b>Requires</b>: If a custom type identifier has been set then 2668 <code>CustomId</code> must match the type of the previously set 2669 pointer<b><br> 2670 Returns</b>: The pointer to the custom type identifier for 2671 <code>MostDerived</code> or <code>0</code><br> 2672 <b>Note</b>: This function is not available if <a href= 2673 "configuration.html#ApplicationDefinedMacros"><code>BOOST_STATECHART_USE_NATIVE_RTTI</code></a> 2674 is defined</p> 2675 <pre> 2676template< class CustomId > 2677static void <a name="custom_static_type_ptr1" id= 2678"custom_static_type_ptr1">custom_static_type_ptr( const CustomId * )</a>; 2679</pre> 2680 2681 <p><b>Effects</b>: Sets the pointer to the custom type identifier for 2682 <code>MostDerived</code><br> 2683 <b>Note</b>: This function is not available if <a href= 2684 "configuration.html#ApplicationDefinedMacros"><code>BOOST_STATECHART_USE_NATIVE_RTTI</code></a> 2685 is defined</p> 2686 2687 <h1>Header <boost/statechart/<a name="state.hpp" id= 2688 "state.hpp">state.hpp</a>></h1> 2689 2690 <h2><a name="ClassTemplatestate" id="ClassTemplatestate">Class template 2691 <code>state</code></a></h2> 2692 2693 <p>This is the base class template for all models of the <a href= 2694 "#State">State</a> concept. Such models typically need to call at least one 2695 of the following <code><a href= 2696 "#ClassTemplatesimple_state">simple_state<></a></code> member 2697 functions from their constructors:</p> 2698 <pre> 2699void <b>post_event</b>( 2700 const intrusive_ptr< const event_base > & ); 2701void <b>post_event</b>( const event_base & ); 2702 2703template< 2704 class HistoryContext, 2705 <i>implementation-defined-unsigned-integer-type 2706</i> orthogonalPosition > 2707void <b>clear_shallow_history</b>(); 2708template< 2709 class HistoryContext, 2710 <i>implementation-defined-unsigned-integer-type 2711</i> orthogonalPosition > 2712void <b>clear_deep_history</b>(); 2713 2714outermost_context_type & <b>outermost_context</b>(); 2715const outermost_context_type & <b>outermost_context</b>() const; 2716 2717template< class OtherContext > 2718OtherContext & <b>context</b>(); 2719template< class OtherContext > 2720const OtherContext & <b>context</b>() const; 2721 2722template< class Target > 2723Target <b>state_cast</b>() const; 2724template< class Target > 2725Target <b>state_downcast</b>() const; 2726 2727state_iterator <b>state_begin</b>() const; 2728state_iterator <b>state_end</b>() const; 2729const event_base * <b>triggering_event</b>() const; 2730</pre> 2731 2732 <p>States that do not need to call any of these member functions from their 2733 constructors should rather derive from the <code><a href= 2734 "#ClassTemplatesimple_state">simple_state</a></code> class template, what 2735 saves the implementation of the forwarding constructor.</p> 2736 2737 <h3>Class template <code>state</code> synopsis</h3> 2738 <pre> 2739namespace boost 2740{ 2741namespace statechart 2742{ 2743 template< 2744 class MostDerived, 2745 class Context, 2746 class InnerInitial = <i>unspecified</i>, 2747 history_mode historyMode = has_no_history > 2748 class state : public simple_state< 2749 MostDerived, Context, InnerInitial, historyMode > 2750 { 2751 protected: 2752 struct my_context 2753 { 2754 // <i>implementation-defined</i> 2755 }; 2756 2757 typedef state my_base; 2758 2759 state( my_context ctx ); 2760 ~state(); 2761 }; 2762} 2763} 2764</pre> 2765 2766 <p>Direct and indirect subtypes of <code>state<></code> must provide 2767 a constructor with the same signature as the <code>state<></code> 2768 constructor, forwarding the context parameter.</p> 2769 2770 <h1>Header <boost/statechart/<a name="shallow_history.hpp" id= 2771 "shallow_history.hpp">shallow_history.hpp</a>></h1> 2772 2773 <h2><a name="ClassTemplateshallow_history" id= 2774 "ClassTemplateshallow_history">Class template 2775 <code>shallow_history</code></a></h2> 2776 2777 <p>This class template is used to specify a shallow history transition 2778 target or a shallow history inner initial state.</p> 2779 2780 <h3>Class template <code>shallow_history</code> parameters</h3> 2781 2782 <table border="3" cellpadding="2" width="100%" summary= 2783 "shallow_history parameters"> 2784 <tr> 2785 <td><b>Template parameter</b></td> 2786 2787 <td><b>Requirements</b></td> 2788 2789 <td><b>Semantics</b></td> 2790 </tr> 2791 2792 <tr> 2793 <td><code>DefaultState</code></td> 2794 2795 <td>A model of the <a href="#SimpleState">SimpleState</a> 2796 or <a href="#State">State</a> concepts. The type passed as 2797 <code>Context</code> argument to the <code><a href= 2798 "#ClassTemplatesimple_state">simple_state<></a></code> or 2799 <code><a href="#ClassTemplatestate">state<></a></code> base 2800 of <code>DefaultState</code> must itself pass 2801 <code>has_shallow_history</code> or <code>has_full_history</code> as 2802 <code>historyMode</code> argument to its <code><a href= 2803 "#ClassTemplatesimple_state">simple_state<></a></code> or 2804 <code><a href="#ClassTemplatestate">state<></a></code> base</td> 2805 2806 <td>The state that is entered if shallow history is not available</td> 2807 </tr> 2808 </table> 2809 2810 <h3>Class template <code>shallow_history</code> synopsis</h3> 2811 <pre> 2812namespace boost 2813{ 2814namespace statechart 2815{ 2816 template< class DefaultState > 2817 class shallow_history 2818 { 2819 // <i>implementation-defined</i> 2820 }; 2821} 2822} 2823</pre> 2824 2825 <h1>Header <boost/statechart/<a name="deep_history.hpp" id= 2826 "deep_history.hpp">deep_history.hpp</a>></h1> 2827 2828 <h2><a name="ClassTemplatedeep_history" id= 2829 "ClassTemplatedeep_history">Class template 2830 <code>deep_history</code></a></h2> 2831 2832 <p>This class template is used to specify a deep history transition target 2833 or a deep history inner initial state. The current deep history 2834 implementation has some <a href= 2835 "rationale.html#Limitations">limitations</a>.</p> 2836 2837 <h3>Class template <code>deep_history</code> parameters</h3> 2838 2839 <table border="3" cellpadding="2" width="100%" summary= 2840 "deep_history parameters"> 2841 <tr> 2842 <td><b>Template parameter</b></td> 2843 2844 <td><b>Requirements</b></td> 2845 2846 <td><b>Semantics</b></td> 2847 </tr> 2848 2849 <tr> 2850 <td><code>DefaultState</code></td> 2851 2852 <td>A model of the <a href="#SimpleState">SimpleState</a> 2853 or <a href="#State">State</a> concepts. The type passed as 2854 <code>Context</code> argument to the <code><a href= 2855 "#ClassTemplatesimple_state">simple_state<></a></code> or 2856 <code><a href="#ClassTemplatestate">state<></a></code> base 2857 of <code>DefaultState</code> must itself pass 2858 <code>has_deep_history</code> or <code>has_full_history</code> as 2859 <code>historyMode</code> argument to its <code><a href= 2860 "#ClassTemplatesimple_state">simple_state<></a></code> or 2861 <code><a href="#ClassTemplatestate">state<></a></code> base</td> 2862 2863 <td>The state that is entered if deep history is not available</td> 2864 </tr> 2865 </table> 2866 2867 <h3>Class template <code>deep_history</code> synopsis</h3> 2868 <pre> 2869namespace boost 2870{ 2871namespace statechart 2872{ 2873 template< class DefaultState > 2874 class deep_history 2875 { 2876 // <i>implementation-defined</i> 2877 }; 2878} 2879} 2880</pre> 2881 2882 <h1>Header <boost/statechart/<a name="event_base.hpp" id= 2883 "event_base.hpp">event_base.hpp</a>></h1> 2884 2885 <h2><a name="Classevent_base" id="Classevent_base">Class 2886 <code>event_base</code></a></h2> 2887 2888 <p>This is the common base of all events.</p> 2889 2890 <h3>Class <code>event_base</code> synopsis</h3> 2891 <pre> 2892namespace boost 2893{ 2894namespace statechart 2895{ 2896 class event_base 2897 { 2898 public: 2899 intrusive_ptr< const event_base > 2900 <a href="#intrusive_from_this">intrusive_from_this</a>() const; 2901 2902 typedef <i>implementation-defined</i> id_type; 2903 2904 id_type <a href="#event_base::dynamic_type">dynamic_type</a>() const; 2905 2906 template< typename CustomId > 2907 const CustomId * <a href= 2908"#event_base::custom_dynamic_type_ptr">custom_dynamic_type_ptr</a>() const; 2909 2910 protected: 2911 <a href="#event_base">event_base</a>( <i>unspecified-parameter </i>); 2912 virtual <a href="#event_basedtor">~event_base</a>(); 2913 }; 2914} 2915} 2916</pre> 2917 2918 <h3>Class <code>event_base</code> constructor and destructor</h3> 2919 <pre> 2920<a name="event_base" id= 2921"event_base">event_base</a>( <i>unspecified-parameter </i>); 2922</pre> 2923 2924 <p><b>Effects</b>: Constructs the common base portion of an event</p> 2925 <pre> 2926virtual <a name="event_basedtor" id="event_basedtor">~event_base</a>(); 2927</pre> 2928 2929 <p><b>Effects</b>: Destructs the common base portion of an event</p> 2930 2931 <h3>Class <code>event_base</code> observer functions</h3> 2932 <pre> 2933intrusive_ptr< const event_base > <a name="intrusive_from_this" id= 2934"intrusive_from_this">intrusive_from_this</a>() const; 2935</pre> 2936 2937 <p><b>Returns</b>: Another <code>intrusive_ptr< const event_base 2938 ></code> referencing <code>this</code> <b>if</b> <code>this</code> is 2939 already referenced by an <code>intrusive_ptr<></code>. Otherwise, 2940 returns an <code>intrusive_ptr< const event_base ></code> referencing 2941 a newly created copy of the most-derived object</p> 2942 <pre> 2943id_type <a name="event_base::dynamic_type" id= 2944"event_base::dynamic_type">dynamic_type</a>() const; 2945</pre> 2946 2947 <p><b>Returns</b>: A value unambiguously identifying the most-derived 2948 type<br> 2949 <b>Note</b>: <code>id_type</code> values are comparable with 2950 <code>operator==()</code> and <code>operator!=()</code>. An unspecified 2951 collating order can be established with <code>std::less< id_type 2952 ></code>. In contrast to <code>typeid( cs )</code>, this function is 2953 available even on platforms that do not support C++ RTTI (or have been 2954 configured to not support it)</p> 2955 <pre> 2956template< typename CustomId > 2957const CustomId * <a name="event_base::custom_dynamic_type_ptr" id= 2958"event_base::custom_dynamic_type_ptr">custom_dynamic_type_ptr</a>() const; 2959</pre> 2960 2961 <p><b>Requires</b>: If a custom type identifier has been set then 2962 <code>CustomId</code> must match the type of the previously set 2963 pointer<b><br> 2964 Returns</b>: A pointer to the custom type identifier or <code>0</code><br> 2965 <b>Note</b>: This function is not available if <a href= 2966 "configuration.html#ApplicationDefinedMacros"><code>BOOST_STATECHART_USE_NATIVE_RTTI</code></a> 2967 is defined</p> 2968 2969 <h1>Header <boost/statechart/<a name="event.hpp" id= 2970 "event.hpp">event.hpp</a>></h1> 2971 2972 <h2><a name="ClassTemplateevent" id="ClassTemplateevent">Class template 2973 <code>event</code></a></h2> 2974 2975 <p>This is the base class template of all events.</p> 2976 2977 <h3>Class template <code>event</code> parameters</h3> 2978 2979 <table border="3" cellpadding="2" width="100%" summary="event parameters"> 2980 <tr> 2981 <td><b>Template parameter</b></td> 2982 2983 <td><b>Requirements</b></td> 2984 2985 <td><b>Semantics</b></td> 2986 2987 <td><b>Default</b></td> 2988 </tr> 2989 2990 <tr> 2991 <td><code>MostDerived</code></td> 2992 2993 <td>The most-derived subtype of this class template</td> 2994 2995 <td> </td> 2996 2997 <td> </td> 2998 </tr> 2999 3000 <tr> 3001 <td><code>Allocator</code></td> 3002 3003 <td>A model of the standard Allocator concept</td> 3004 3005 <td><code>Allocator::rebind< MostDerived 3006 >::other</code> is used to allocate and deallocate all event subtype 3007 objects of dynamic storage duration, see <code><a href= 3008 "#event::operatornew">operator new</a></code></td> 3009 3010 <td><code>std::allocator< void ></code></td> 3011 </tr> 3012 </table> 3013 3014 <h3>Class template <code>event</code> synopsis</h3> 3015 <pre> 3016namespace boost 3017{ 3018namespace statechart 3019{ 3020 template< class MostDerived, class Allocator = std::allocator< void > > 3021 class event : <i>implementation-defined</i> 3022 { 3023 public: 3024 static void * <a href= 3025"#event::operatornew">operator new</a>( std::size_t size ); 3026 static void * <a href= 3027"#event::operatornew2">operator new</a>( std::size_t size, void * p ); 3028 static void <a href= 3029"#event::operatordelete">operator delete</a>( void * pEvent ); 3030 3031 static id_type <a href="#event::static_type">static_type</a>(); 3032 3033 template< class CustomId > 3034 static const CustomId * <a href= 3035"#event::custom_static_type_ptr">custom_static_type_ptr</a>(); 3036 3037 template< class CustomId > 3038 static void <a href= 3039"#event::custom_static_type_ptr1">custom_static_type_ptr</a>( const CustomId * ); 3040 3041 protected: 3042 <a href="#event::event">event</a>(); 3043 virtual <a href="#eventdtor">~event</a>(); 3044 }; 3045} 3046} 3047</pre> 3048 3049 <h3>Class template <code>event</code> constructor and destructor</h3> 3050 <pre> 3051<a name="event::event" id="event::event">event</a>(); 3052</pre> 3053 3054 <p><b>Effects</b>: Constructs an event</p> 3055 <pre> 3056virtual <a name="eventdtor" id="eventdtor">~event</a>(); 3057</pre> 3058 3059 <p><b>Effects</b>: Destructs an event</p> 3060 3061 <h3>Class template <code>event</code> static functions</h3> 3062 <pre> 3063static void * <a name="event::operatornew" id= 3064"event::operatornew">operator new</a>( std::size_t size ); 3065</pre> 3066 3067 <p><b>Effects</b>: <code>Allocator::rebind< MostDerived 3068 >::other().allocate( 1, static_cast< MostDerived * >( 0 ) 3069 );</code><br> 3070 <b>Returns</b>: The return value of the above call<br> 3071 <b>Throws</b>: Whatever the above call throws</p> 3072 <pre> 3073static void * <a name="event::operatornew2" id= 3074"event::operatornew2">operator new</a>( std::size_t size, void * p ); 3075</pre> 3076 3077 <p><b>Effects</b>: None<br> 3078 <b>Returns</b>: <code>p</code></p> 3079 <pre> 3080static void <a name="event::operatordelete" id= 3081"event::operatordelete">operator delete</a>( void * pEvent ); 3082</pre> 3083 3084 <p><b>Effects</b>: <code>Allocator::rebind< MostDerived 3085 >::other().deallocate( static_cast< MostDerived * >( pEvent ), 1 3086 );</code></p> 3087 <pre> 3088static id_type <a name="event::static_type" id= 3089"event::static_type">static_type</a>(); 3090</pre> 3091 3092 <p><b>Returns</b>: A value unambiguously identifying the type of 3093 <code>MostDerived</code><br> 3094 <b>Note</b>: <code>id_type</code> values are comparable with 3095 <code>operator==()</code> and <code>operator!=()</code>. An unspecified 3096 collating order can be established with <code>std::less< id_type 3097 ></code></p> 3098 <pre> 3099template< class CustomId > 3100static const CustomId * <a name="event::custom_static_type_ptr" id= 3101"event::custom_static_type_ptr">custom_static_type_ptr</a>(); 3102</pre> 3103 3104 <p><b>Requires</b>: If a custom type identifier has been set then 3105 <code>CustomId</code> must match the type of the previously set 3106 pointer<b><br> 3107 Returns</b>: The pointer to the custom type identifier for 3108 <code>MostDerived</code> or <code>0</code><br> 3109 <b>Note</b>: This function is not available if <a href= 3110 "configuration.html#ApplicationDefinedMacros"><code>BOOST_STATECHART_USE_NATIVE_RTTI</code></a> 3111 is defined</p> 3112 <pre> 3113template< class CustomId > 3114static void <a name="event::custom_static_type_ptr1" id= 3115"event::custom_static_type_ptr1">custom_static_type_ptr( const CustomId * )</a>; 3116</pre> 3117 3118 <p><b>Effects</b>: Sets the pointer to the custom type identifier for 3119 <code>MostDerived</code><br> 3120 <b>Note</b>: This function is not available if <a href= 3121 "configuration.html#ApplicationDefinedMacros"><code>BOOST_STATECHART_USE_NATIVE_RTTI</code></a> 3122 is defined</p> 3123 3124 <h1>Header <boost/statechart/<a name="transition.hpp" id= 3125 "transition.hpp">transition.hpp</a>></h1> 3126 3127 <h2><a name="ClassTemplatetransition" id="ClassTemplatetransition">Class 3128 template <code>transition</code></a></h2> 3129 3130 <p>This class template is used to specify a transition reaction. 3131 Instantiations of this template can appear in the <code>reactions</code> 3132 member <code>typedef</code> in models of the <a href= 3133 "#SimpleState">SimpleState</a> and <a href="#State">State</a> concepts.</p> 3134 3135 <h3>Class template <code>transition</code> parameters</h3> 3136 3137 <table border="3" cellpadding="2" width="100%" summary= 3138 "transition parameters"> 3139 <tr> 3140 <td><b>Template parameter</b></td> 3141 3142 <td><b>Requirements</b></td> 3143 3144 <td><b>Semantics</b></td> 3145 3146 <td><b>Default</b></td> 3147 </tr> 3148 3149 <tr> 3150 <td><code>Event</code></td> 3151 3152 <td>A model of the <a href="#Event">Event</a> concept or 3153 the class <code><a href="#Classevent_base">event_base</a></code></td> 3154 3155 <td>The event triggering the transition. If <code><a href= 3156 "#Classevent_base">event_base</a></code> is specified, the transition 3157 is triggered by all models of the <a href="#Event">Event</a> 3158 concept</td> 3159 3160 <td> </td> 3161 </tr> 3162 3163 <tr> 3164 <td><code>Destination</code></td> 3165 3166 <td>A model of the <a href="#SimpleState">SimpleState</a> 3167 or <a href="#State">State</a> concepts, any of their public base types or an instantiation of the 3168 <code><a href= 3169 "#ClassTemplateshallow_history">shallow_history</a></code> or 3170 <code><a href="#ClassTemplatedeep_history">deep_history</a></code> 3171 class templates. The source state (the state for which this transition 3172 is defined) and <code>Destination</code> must have a common direct or 3173 indirect context</td> 3174 3175 <td>The destination state to make a transition to</td> 3176 3177 <td> </td> 3178 </tr> 3179 3180 <tr> 3181 <td><code>TransitionContext</code></td> 3182 3183 <td>A common context of the source and 3184 <code>Destination</code> state</td> 3185 3186 <td>The state of which the transition action is a 3187 member</td> 3188 3189 <td><i><code>unspecified</code></i></td> 3190 </tr> 3191 3192 <tr> 3193 <td><code>pTransitionAction</code></td> 3194 3195 <td>A pointer to a member function of 3196 <code>TransitionContext</code>. The member function must accept a 3197 <code>const Event &</code> parameter and return 3198 <code>void</code></td> 3199 3200 <td>The transition action that is executed during the 3201 transition. By default no transition action is executed</td> 3202 3203 <td><i><code>unspecified</code></i></td> 3204 </tr> 3205 </table> 3206 3207 <h3>Class template <code>transition</code> synopsis</h3> 3208 <pre> 3209namespace boost 3210{ 3211namespace statechart 3212{ 3213 template< 3214 class Event, 3215 class Destination, 3216 class TransitionContext = <i>unspecified</i>, 3217 void ( TransitionContext::*pTransitionAction )( 3218 const Event & ) = <i>unspecified</i> > 3219 class transition 3220 { 3221 // <i>implementation-defined</i> 3222 }; 3223} 3224} 3225</pre> 3226 3227 <h3>Class template <code>transition</code> semantics</h3> 3228 3229 <p>When executed, one of the following calls to a member function of the 3230 state for which the reaction was defined is made:</p> 3231 3232 <ul> 3233 <li><code><a href="#transit1">transit< Destination >()</a></code>, 3234 if no transition action was specified</li> 3235 3236 <li><code><a href="#transit2">transit< Destination >( 3237 pTransitionAction, <i>currentEvent</i> )</a></code>, if a transition 3238 action was specified</li> 3239 </ul> 3240 3241 <h1>Header <boost/statechart/<a name="in_state_reaction.hpp" id= 3242 "in_state_reaction.hpp">in_state_reaction.hpp</a>></h1> 3243 3244 <h2><a name="ClassTemplatein_state_reaction" id= 3245 "ClassTemplatein_state_reaction">Class template 3246 <code>in_state_reaction</code></a></h2> 3247 3248 <p>This class template is used to specify an in-state reaction. 3249 Instantiations of this template can appear in the <code>reactions</code> 3250 member <code>typedef</code> in models of the <a href= 3251 "#SimpleState">SimpleState</a> and <a href="#State">State</a> concepts.</p> 3252 3253 <h3>Class template <code>in_state_reaction</code> parameters</h3> 3254 3255 <table border="3" cellpadding="2" width="100%" summary= 3256 "in_state_reaction parameters"> 3257 <tr> 3258 <td><b>Template parameter</b></td> 3259 3260 <td><b>Requirements</b></td> 3261 3262 <td><b>Semantics</b></td> 3263 3264 <td><b>Default</b></td> 3265 </tr> 3266 3267 <tr> 3268 <td><code>Event</code></td> 3269 3270 <td>A model of the <a href="#Event">Event</a> concept or 3271 the class <code><a href="#Classevent_base">event_base</a></code></td> 3272 3273 <td>The event triggering the in-state reaction. If 3274 <code><a href="#Classevent_base">event_base</a></code> is specified, 3275 the in-state reaction is triggered by all models of the <a href= 3276 "#Event">Event</a> concept</td> 3277 3278 <td> </td> 3279 </tr> 3280 3281 <tr> 3282 <td><code>ReactionContext</code></td> 3283 3284 <td>Either the state defining the in-state reaction itself, one of its direct or indirect contexts 3285 or any of their public base types</td> 3286 3287 <td>The state of which the action is a member</td> 3288 3289 <td><i><code>unspecified</code></i></td> 3290 </tr> 3291 3292 <tr> 3293 <td><code>pAction</code></td> 3294 3295 <td>A pointer to a member function of 3296 <code>ReactionContext</code>. The member function must accept a 3297 <code>const Event &</code> parameter and return 3298 <code>void</code></td> 3299 3300 <td>The action that is executed during the in-state 3301 reaction</td> 3302 3303 <td><i><code>unspecified</code></i></td> 3304 </tr> 3305 </table> 3306 3307 <h3>Class template <code>in_state_reaction</code> synopsis</h3> 3308 <pre> 3309namespace boost 3310{ 3311namespace statechart 3312{ 3313 template< 3314 class Event, 3315 class ReactionContext = <i>unspecified</i>, 3316 void ( ReactionContext::*pAction )( 3317 const Event & ) = <i>unspecified</i> > 3318 class in_state_reaction 3319 { 3320 // <i>implementation-defined</i> 3321 }; 3322} 3323} 3324</pre> 3325 3326 <h3>Class template <code>in_state_reaction</code> semantics</h3> 3327 3328 <p>When executed then the following happens:</p> 3329 <ol> 3330 <li>If an action was specified, <code>pAction</code> is called, passing 3331 the triggering event as the only argument</li> 3332 <li>A call is made to the <code><a href="#discard_event">discard_event</a> 3333 </code> member function of the state for which the reaction was defined 3334 </li> 3335 </ol> 3336 3337 <h1>Header <boost/statechart/<a name="termination.hpp" id= 3338 "termination.hpp">termination.hpp</a>></h1> 3339 3340 <h2><a name="ClassTemplatetermination" id="ClassTemplatetermination">Class 3341 template <code>termination</code></a></h2> 3342 3343 <p>This class template is used to specify a termination reaction. 3344 Instantiations of this template can appear in the <code>reactions</code> 3345 member <code>typedef</code> in models of the <a href= 3346 "#SimpleState">SimpleState</a> and <a href="#State">State</a> concepts.</p> 3347 3348 <h3>Class template <code>termination</code> parameters</h3> 3349 3350 <table border="3" cellpadding="2" width="100%" summary= 3351 "termination parameters"> 3352 <tr> 3353 <td><b>Template parameter</b></td> 3354 3355 <td><b>Requirements</b></td> 3356 3357 <td><b>Semantics</b></td> 3358 </tr> 3359 3360 <tr> 3361 <td><code>Event</code></td> 3362 3363 <td>A model of the <a href="#Event">Event</a> concept or 3364 the class <code><a href="#Classevent_base">event_base</a></code></td> 3365 3366 <td>The event triggering the termination. If <code><a href= 3367 "#Classevent_base">event_base</a></code> is specified, the termination 3368 is triggered by all models of the <a href="#Event">Event</a> 3369 concept</td> 3370 </tr> 3371 </table> 3372 3373 <h3>Class template <code>termination</code> synopsis</h3> 3374 <pre> 3375namespace boost 3376{ 3377namespace statechart 3378{ 3379 template< class Event > 3380 class termination 3381 { 3382 // <i>implementation-defined</i> 3383 }; 3384} 3385} 3386</pre> 3387 3388 <h3>Class template <code>termination</code> semantics</h3> 3389 3390 <p>When executed, a call is made to the <code><a href= 3391 "#simple_state::terminate">terminate</a></code> member function of the 3392 state for which the reaction was defined.</p> 3393 3394 <h1>Header <boost/statechart/<a name="deferral.hpp" id= 3395 "deferral.hpp">deferral.hpp</a>></h1> 3396 3397 <h2><a name="ClassTemplatedeferral" id="ClassTemplatedeferral">Class 3398 template <code>deferral</code></a></h2> 3399 3400 <p>This class template is used to specify a deferral reaction. 3401 Instantiations of this template can appear in the <code>reactions</code> 3402 member <code>typedef</code> in models of the <a href= 3403 "#SimpleState">SimpleState</a> and <a href="#State">State</a> concepts.</p> 3404 3405 <h3>Class template <code>deferral</code> parameters</h3> 3406 3407 <table border="3" cellpadding="2" width="100%" summary= 3408 "deferral parameters"> 3409 <tr> 3410 <td><b>Template parameter</b></td> 3411 3412 <td><b>Requirements</b></td> 3413 3414 <td><b>Semantics</b></td> 3415 </tr> 3416 3417 <tr> 3418 <td><code>Event</code></td> 3419 3420 <td>A model of the <a href="#Event">Event</a> concept or 3421 the class <code><a href="#Classevent_base">event_base</a></code></td> 3422 3423 <td>The event triggering the deferral. If <code><a href= 3424 "#Classevent_base">event_base</a></code> is specified, the deferral is 3425 triggered by all models of the <a href="#Event">Event</a> concept</td> 3426 </tr> 3427 </table> 3428 3429 <h3>Class template <code>deferral</code> synopsis</h3> 3430 <pre> 3431namespace boost 3432{ 3433namespace statechart 3434{ 3435 template< class Event > 3436 class deferral 3437 { 3438 // <i>implementation-defined</i> 3439 }; 3440} 3441} 3442</pre> 3443 3444 <h3>Class template <code>deferral</code> semantics</h3> 3445 3446 <p>When executed, a call is made to the <a href= 3447 "#defer_event"><code>defer_event</code></a> member function of the state 3448 for which the reaction was defined.</p> 3449 3450 <h1>Header <boost/statechart/<a name="custom_reaction.hpp" id= 3451 "custom_reaction.hpp">custom_reaction.hpp</a>></h1> 3452 3453 <h2><a name="ClassTemplatecustom_reaction" id= 3454 "ClassTemplatecustom_reaction">Class template 3455 <code>custom_reaction</code></a></h2> 3456 3457 <p>This class template is used to specify a custom reaction. Instantiations 3458 of this template can appear in the <code>reactions</code> member 3459 <code>typedef</code> in models of the <a href= 3460 "#SimpleState">SimpleState</a> and <a href="#State">State</a> concepts.</p> 3461 3462 <h3>Class template <code>custom_reaction</code> parameters</h3> 3463 3464 <table border="3" cellpadding="2" width="100%" summary= 3465 "custom_reaction parameters"> 3466 <tr> 3467 <td><b>Template parameter</b></td> 3468 3469 <td><b>Requirements</b></td> 3470 3471 <td><b>Semantics</b></td> 3472 </tr> 3473 3474 <tr> 3475 <td><code>Event</code></td> 3476 3477 <td>A model of the <a href="#Event">Event</a> concept or 3478 the class <code><a href="#Classevent_base">event_base</a></code></td> 3479 3480 <td>The event triggering the custom reaction. If 3481 <code><a href="#Classevent_base">event_base</a></code> is specified, 3482 the custom reaction is triggered by all models of the <a href= 3483 "#Event">Event</a> concept</td> 3484 </tr> 3485 </table> 3486 3487 <h3>Class template <code>custom_reaction</code> synopsis</h3> 3488 <pre> 3489namespace boost 3490{ 3491namespace statechart 3492{ 3493 template< class Event > 3494 class custom_reaction 3495 { 3496 // <i>implementation-defined</i> 3497 }; 3498} 3499} 3500</pre> 3501 3502 <h3>Class template <code>custom_reaction</code> semantics</h3> 3503 3504 <p>When executed, a call is made to the user-supplied <code>react</code> 3505 member function of the state for which the reaction was defined. The 3506 <code>react</code> member function must have the following signature:</p> 3507 <pre> 3508<a href="#Classresult">result</a> react( const Event & ); 3509</pre> 3510 3511 <p>and must call exactly one of the following reaction functions and return 3512 the obtained <code><a href="#Classresult">result</a></code> object:</p> 3513 <pre> 3514<a href="#Classresult">result</a> <a href= 3515"#discard_event">discard_event</a>(); 3516<a href="#Classresult">result</a> <a href= 3517"#forward_event">forward_event</a>(); 3518<a href="#Classresult">result</a> <a href="#defer_event">defer_event</a>(); 3519template< class DestinationState > 3520<a href="#Classresult">result</a> <a href="#transit1">transit</a>(); 3521template< 3522 class DestinationState, 3523 class TransitionContext, 3524 class Event > 3525<a href="#Classresult">result</a> <a href="#transit2">transit</a>( 3526 void ( TransitionContext::* )( const Event & ), 3527 const Event & ); 3528<a href="#Classresult">result</a> <a href= 3529"#simple_state::terminate">terminate</a>(); 3530</pre> 3531 3532 <h1>Header <boost/statechart/<a name="result.hpp" id= 3533 "result.hpp">result.hpp</a>></h1> 3534 3535 <h2><a name="Classresult" id="Classresult">Class 3536 <code>result</code></a></h2> 3537 3538 <p>Defines the nature of the reaction taken in a user-supplied 3539 <code>react</code> member function (called when a <code><a href= 3540 "#ClassTemplatecustom_reaction">custom_reaction</a></code> is executed). 3541 Objects of this type are always obtained by calling one of the reaction 3542 functions and must be returned from the <code>react</code> member function 3543 immediately.</p> 3544 <pre> 3545namespace boost 3546{ 3547namespace statechart 3548{ 3549 class result 3550 { 3551 public: 3552 <a href="#result0">result</a>( const result & other ); 3553 <a href="#resultdtor">~result</a>(); 3554 3555 private: 3556 // Result objects are not assignable 3557 result & operator=( const result & other ); 3558 }; 3559} 3560} 3561</pre> 3562 3563 <h3>Class <code>result</code> constructor and destructor</h3> 3564 <pre> 3565<a name="result0" id="result0">result</a>( const result & other ); 3566</pre> 3567 3568 <p><b>Requires</b>: <code>other</code> is <b>not</b> consumed<br> 3569 <b>Effects</b>: Copy-constructs a new <code>result</code> object and marks 3570 <code>other</code> as consumed. That is, <code>result</code> has 3571 destructive copy semantics</p> 3572 <pre> 3573<a name="resultdtor" id="resultdtor">~result</a>(); 3574</pre> 3575 3576 <p><b>Requires</b>: <code>this</code> is marked as consumed<br> 3577 <b>Effects</b>: Destructs the result object</p> 3578 <hr> 3579 3580 <p><a href="http://validator.w3.org/check?uri=referer"><img border="0" src= 3581 "../../../doc/images/valid-html401.png" alt="Valid HTML 4.01 Transitional" 3582 height="31" width="88"></a></p> 3583 3584 <p>Revised 06 November, 2010</p> 3585 3586 <p><i>Copyright © 2003-2010 <a href="contact.html">Andreas Huber 3587 Dönni</a></i></p> 3588 3589 <p><i>Distributed under the Boost Software License, Version 1.0. (See 3590 accompanying file <a href="../../../LICENSE_1_0.txt">LICENSE_1_0.txt</a> or 3591 copy at <a href= 3592 "http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</a>)</i></p> 3593</body> 3594</html> 3595
