123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977978979980981982983984985986987988989990991992993994995996997998999100010011002100310041005100610071008100910101011101210131014101510161017101810191020102110221023102410251026102710281029103010311032103310341035103610371038103910401041104210431044104510461047104810491050105110521053105410551056105710581059106010611062106310641065106610671068106910701071107210731074107510761077107810791080108110821083108410851086108710881089109010911092109310941095109610971098109911001101110211031104110511061107110811091110111111121113111411151116111711181119112011211122112311241125112611271128112911301131113211331134113511361137113811391140114111421143114411451146114711481149115011511152115311541155115611571158115911601161116211631164116511661167116811691170117111721173117411751176117711781179118011811182118311841185118611871188118911901191119211931194119511961197119811991200120112021203120412051206120712081209121012111212121312141215121612171218121912201221122212231224122512261227122812291230123112321233123412351236123712381239124012411242124312441245124612471248124912501251125212531254125512561257125812591260126112621263126412651266126712681269127012711272127312741275127612771278127912801281128212831284128512861287128812891290129112921293129412951296129712981299130013011302130313041305130613071308130913101311131213131314131513161317131813191320132113221323132413251326132713281329133013311332133313341335133613371338133913401341134213431344134513461347134813491350135113521353135413551356135713581359136013611362136313641365136613671368136913701371137213731374137513761377137813791380138113821383138413851386138713881389139013911392139313941395139613971398139914001401140214031404140514061407140814091410141114121413141414151416141714181419142014211422142314241425142614271428142914301431143214331434143514361437143814391440144114421443144414451446144714481449145014511452145314541455145614571458145914601461146214631464146514661467146814691470147114721473147414751476147714781479148014811482148314841485148614871488148914901491149214931494149514961497149814991500150115021503150415051506150715081509151015111512151315141515151615171518151915201521152215231524152515261527152815291530153115321533153415351536153715381539154015411542154315441545154615471548154915501551155215531554155515561557155815591560156115621563156415651566156715681569157015711572157315741575157615771578157915801581158215831584158515861587158815891590159115921593159415951596159715981599160016011602160316041605160616071608160916101611161216131614161516161617161816191620162116221623162416251626162716281629163016311632163316341635163616371638163916401641164216431644164516461647164816491650165116521653165416551656165716581659166016611662166316641665166616671668166916701671167216731674167516761677167816791680168116821683168416851686168716881689169016911692169316941695169616971698169917001701170217031704170517061707170817091710171117121713171417151716171717181719172017211722172317241725172617271728172917301731173217331734173517361737173817391740174117421743174417451746174717481749175017511752175317541755175617571758175917601761176217631764176517661767176817691770177117721773177417751776177717781779178017811782178317841785178617871788178917901791179217931794179517961797179817991800180118021803180418051806180718081809181018111812181318141815181618171818181918201821182218231824182518261827182818291830183118321833183418351836183718381839184018411842184318441845184618471848184918501851185218531854185518561857185818591860186118621863186418651866186718681869187018711872187318741875187618771878187918801881188218831884188518861887188818891890189118921893189418951896189718981899190019011902190319041905190619071908190919101911191219131914191519161917191819191920192119221923192419251926192719281929193019311932193319341935193619371938193919401941194219431944194519461947194819491950195119521953195419551956195719581959196019611962196319641965196619671968196919701971197219731974197519761977197819791980198119821983198419851986198719881989199019911992199319941995199619971998199920002001200220032004200520062007200820092010201120122013201420152016201720182019202020212022202320242025202620272028202920302031203220332034203520362037203820392040204120422043204420452046204720482049205020512052205320542055205620572058205920602061206220632064206520662067206820692070207120722073207420752076207720782079208020812082208320842085208620872088208920902091209220932094209520962097209820992100210121022103210421052106210721082109211021112112211321142115211621172118211921202121212221232124212521262127212821292130213121322133213421352136213721382139214021412142214321442145214621472148214921502151215221532154215521562157215821592160216121622163216421652166216721682169217021712172217321742175217621772178217921802181218221832184218521862187218821892190219121922193219421952196219721982199220022012202220322042205220622072208220922102211221222132214221522162217221822192220222122222223222422252226222722282229223022312232223322342235223622372238223922402241224222432244224522462247224822492250225122522253225422552256225722582259226022612262226322642265226622672268226922702271227222732274227522762277227822792280228122822283228422852286228722882289229022912292229322942295229622972298229923002301230223032304230523062307230823092310231123122313231423152316231723182319232023212322232323242325232623272328232923302331233223332334233523362337233823392340234123422343234423452346234723482349235023512352235323542355235623572358235923602361236223632364236523662367236823692370237123722373237423752376237723782379238023812382238323842385238623872388238923902391239223932394239523962397239823992400240124022403240424052406240724082409241024112412241324142415241624172418241924202421242224232424242524262427242824292430243124322433243424352436243724382439244024412442244324442445244624472448244924502451245224532454245524562457245824592460246124622463246424652466246724682469247024712472247324742475247624772478247924802481248224832484248524862487248824892490249124922493249424952496249724982499250025012502250325042505250625072508250925102511251225132514251525162517251825192520252125222523252425252526252725282529253025312532253325342535253625372538253925402541254225432544254525462547254825492550255125522553255425552556255725582559256025612562256325642565256625672568256925702571257225732574257525762577257825792580258125822583258425852586258725882589259025912592259325942595259625972598259926002601260226032604260526062607260826092610261126122613261426152616261726182619262026212622262326242625262626272628262926302631263226332634263526362637263826392640264126422643264426452646264726482649265026512652265326542655265626572658265926602661266226632664266526662667266826692670267126722673267426752676267726782679268026812682268326842685268626872688268926902691269226932694269526962697269826992700270127022703270427052706270727082709271027112712271327142715271627172718271927202721272227232724272527262727272827292730273127322733273427352736273727382739274027412742274327442745274627472748274927502751275227532754275527562757275827592760276127622763276427652766276727682769277027712772277327742775277627772778277927802781278227832784278527862787278827892790279127922793279427952796279727982799280028012802280328042805280628072808280928102811281228132814281528162817281828192820282128222823282428252826282728282829283028312832283328342835283628372838283928402841284228432844284528462847284828492850285128522853285428552856285728582859286028612862286328642865286628672868286928702871287228732874287528762877287828792880288128822883288428852886288728882889289028912892289328942895289628972898289929002901290229032904290529062907290829092910291129122913291429152916291729182919292029212922292329242925292629272928292929302931293229332934293529362937293829392940294129422943294429452946294729482949295029512952295329542955295629572958295929602961296229632964296529662967296829692970297129722973297429752976297729782979298029812982298329842985298629872988298929902991299229932994299529962997299829993000300130023003300430053006300730083009301030113012301330143015301630173018301930203021302230233024302530263027302830293030303130323033303430353036303730383039304030413042304330443045304630473048304930503051305230533054305530563057305830593060306130623063306430653066306730683069307030713072307330743075307630773078307930803081308230833084308530863087308830893090309130923093309430953096309730983099310031013102310331043105310631073108310931103111311231133114311531163117311831193120312131223123312431253126312731283129313031313132313331343135313631373138313931403141314231433144314531463147314831493150315131523153315431553156315731583159316031613162316331643165316631673168316931703171317231733174317531763177317831793180318131823183318431853186318731883189319031913192319331943195319631973198319932003201320232033204320532063207320832093210321132123213321432153216321732183219322032213222322332243225322632273228322932303231323232333234323532363237323832393240324132423243324432453246324732483249325032513252325332543255325632573258325932603261326232633264326532663267326832693270327132723273327432753276327732783279328032813282328332843285328632873288328932903291329232933294329532963297329832993300330133023303330433053306330733083309331033113312331333143315331633173318331933203321332233233324332533263327332833293330333133323333333433353336333733383339334033413342334333443345334633473348334933503351335233533354335533563357335833593360336133623363336433653366336733683369337033713372337333743375337633773378337933803381338233833384338533863387338833893390339133923393339433953396339733983399340034013402340334043405340634073408340934103411341234133414341534163417341834193420342134223423342434253426342734283429343034313432343334343435343634373438343934403441344234433444344534463447344834493450345134523453345434553456345734583459346034613462346334643465346634673468346934703471347234733474347534763477347834793480348134823483348434853486348734883489349034913492349334943495349634973498349935003501350235033504350535063507350835093510351135123513351435153516351735183519352035213522352335243525352635273528352935303531353235333534353535363537353835393540354135423543354435453546354735483549355035513552355335543555355635573558355935603561356235633564356535663567356835693570357135723573357435753576357735783579358035813582358335843585358635873588358935903591359235933594 |
- <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
- <html>
- <head>
- <meta http-equiv="Content-Language" content="en-us">
- <meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
- <meta name="GENERATOR" content="Microsoft FrontPage 12.0">
- <meta name="ProgId" content="FrontPage.Editor.Document">
- <link rel="stylesheet" type="text/css" href="../../../boost.css">
- <title>The Boost Statechart Library - Reference</title>
- <style type="text/css">
- .style1
- {
- width: 45%;
- }
- </style>
- </head>
- <body link="#0000FF" vlink="#800080">
- <table border="0" cellpadding="7" cellspacing="0" width="100%" summary=
- "header">
- <tr>
- <td valign="top" width="300">
- <h3><a href="../../../index.htm"><img alt="C++ Boost" src=
- "../../../boost.png" border="0" width="277" height="86"></a></h3>
- </td>
- <td valign="top">
- <h1 align="center">The Boost Statechart Library</h1>
- <h2 align="center">Reference</h2>
- </td>
- </tr>
- </table>
- <hr>
- <h2>Contents</h2>
- <dl class="page-index">
- <dt><a href="#Concepts">Concepts</a></dt>
- <dd><a href="#Scheduler">Scheduler</a></dd>
- <dd><a href="#FifoWorker">FifoWorker</a></dd>
- <dd><a href="#ExceptionTranslator">ExceptionTranslator</a></dd>
- <dd><a href="#StateBase">StateBase</a></dd>
- <dd><a href="#SimpleState">SimpleState</a></dd>
- <dd><a href="#State">State</a></dd>
- <dd><a href="#Event">Event</a></dd>
- <dt><a href="#state_machine.hpp">state_machine.hpp</a></dt>
- <dd><a href="#ClassTemplatestate_machine">Class template
- <code>state_machine</code></a></dd>
- <dt><a href=
- "#asynchronous_state_machine.hpp">asynchronous_state_machine.hpp</a></dt>
- <dd><a href="#ClassTemplateasynchronous_state_machine">Class template
- <code>asynchronous_state_machine</code></a></dd>
- <dt><a href="#event_processor.hpp">event_processor.hpp</a></dt>
- <dd><a href="#ClassTemplateevent_processor">Class template
- <code>event_processor</code></a></dd>
- <dt><a href="#fifo_scheduler.hpp">fifo_scheduler.hpp</a></dt>
- <dd><a href="#ClassTemplatefifo_scheduler">Class template
- <code>fifo_scheduler</code></a></dd>
- <dt><a href="#exception_translator.hpp">exception_translator.hpp</a></dt>
- <dd><a href="#ClassTemplateexception_translator">Class template
- <code>exception_translator</code></a></dd>
- <dt><a href=
- "#null_exception_translator.hpp">null_exception_translator.hpp</a></dt>
- <dd><a href="#Classnull_exception_translator">Class
- <code>null_exception_translator</code></a></dd>
- <dt> </dt>
- <dt><a href="#simple_state.hpp">simple_state.hpp</a></dt>
- <dd><a href="#Enumhistory_mode">Enum <code>history_mode</code></a></dd>
- <dd><a href="#ClassTemplatesimple_state">Class template
- <code>simple_state</code></a></dd>
- <dt><a href="#state.hpp">state.hpp</a></dt>
- <dd><a href="#ClassTemplatestate">Class template
- <code>state</code></a></dd>
- <dt><a href="#shallow_history.hpp">shallow_history.hpp</a></dt>
- <dd><a href="#ClassTemplateshallow_history">Class template
- <code>shallow_history</code></a></dd>
- <dt><a href="#deep_history.hpp">deep_history.hpp</a></dt>
- <dd><a href="#ClassTemplatedeep_history">Class template
- <code>deep_history</code></a></dd>
- <dt> </dt>
- <dt><a href="#event_base.hpp">event_base.hpp</a></dt>
- <dd><a href="#Classevent_base">Class <code>event_base</code></a></dd>
- <dt><a href="#event.hpp">event.hpp</a></dt>
- <dd><a href="#ClassTemplateevent">Class template
- <code>event</code></a></dd>
- <dt> </dt>
- <dt><a href="#transition.hpp">transition.hpp</a></dt>
- <dd><a href="#ClassTemplatetransition">Class template
- <code>transition</code></a></dd>
- <dt><a href="#in_state_reaction.hpp">in_state_reaction.hpp</a></dt>
- <dd><a href="#ClassTemplatein_state_reaction">Class template
- in_state_reaction</a></dd>
- <dt><a href="#termination.hpp">termination.hpp</a></dt>
- <dd><a href="#ClassTemplatetermination">Class template
- <code>termination</code></a></dd>
- <dt><a href="#deferral.hpp">deferral.hpp</a></dt>
- <dd><a href="#ClassTemplatedeferral">Class template
- <code>deferral</code></a></dd>
- <dt><a href="#custom_reaction.hpp">custom_reaction.hpp</a></dt>
- <dd><a href="#ClassTemplatecustom_reaction">Class template
- <code>custom_reaction</code></a></dd>
- <dt><a href="#result.hpp">result.hpp</a></dt>
- <dd><a href="#Classresult">Class <code>result</code></a></dd>
- </dl>
- <hr>
- <h1><a name="Concepts" id="Concepts">Concepts</a></h1>
- <h2><a name="Scheduler" id="Scheduler">Scheduler</a> concept</h2>
- <p>A Scheduler type defines the following:</p>
- <ul>
- <li>What is passed to the constructors of <code><a href=
- "#ClassTemplateevent_processor">event_processor<></a></code>
- subtypes and how the lifetime of such objects is managed</li>
- <li>Whether or not multiple <code>event_processor<></code> subtype
- objects can share the same queue and scheduler thread</li>
- <li>How events are added to the schedulers' queue</li>
- <li>Whether and how to wait for new events when the schedulers' queue
- runs empty</li>
- <li>Whether and what type of locking is used to ensure thread-safety</li>
- <li>Whether it is possible to queue events for no longer existing
- <code>event_processor<></code> subtype objects and what happens
- when such an event is processed</li>
- <li>What happens when one of the serviced
- <code>event_processor<></code> subtype objects propagates an
- exception</li>
- </ul>
- <p>For a Scheduler type <code>S</code> and an object <code>cpc</code> of
- type <code>const S::processor_context</code> the following expressions must
- be well-formed and have the indicated results:</p>
- <table border="3" cellpadding="2" width="100%" summary="Scheduler concept">
- <tr>
- <td><b>Expression</b></td>
- <td><b>Type</b></td>
- <td><b>Result</b></td>
- </tr>
- <tr>
- <td><code>cpc.my_scheduler()</code></td>
- <td><code>S &</code></td>
- <td>A reference to the scheduler</td>
- </tr>
- <tr>
- <td><code>cpc.my_handle()</code></td>
- <td><code>S::processor_handle</code></td>
- <td>The handle identifying the
- <code>event_processor<></code> subtype object</td>
- </tr>
- </table>
- <p>To protect against abuse, all members of
- <code>S::processor_context</code> should be declared private. As a result,
- <code>event_processor<></code> must be a friend of
- <code>S::processor_context</code>.</p>
- <h2><a name="FifoWorker" id="FifoWorker">FifoWorker</a> concept</h2>
- <p>A FifoWorker type defines the following:</p>
- <ul>
- <li>Whether and how to wait for new work items when the internal work
- queue runs empty</li>
- <li>Whether and what type of locking is used to ensure thread-safety</li>
- </ul>
- <p>For a FifoWorker type <code>F</code>, an object <code>f</code> of that
- type, a <code>const</code> object <code>cf</code> of that type, a
- parameterless function object <code>w</code> of arbitrary type and an
- <code>unsigned long</code> value <code>n</code> the following
- expressions/statements must be well-formed and have the indicated
- results:</p>
- <table border="3" cellpadding="2" width="100%" summary=
- "FifoWorker concept">
- <tr>
- <td><b>Expression/Statement</b></td>
- <td><b>Type</b></td>
- <td><b>Effects/Result</b></td>
- </tr>
- <tr>
- <td><code>F::work_item</code></td>
- <td><code>boost::function0< void ></code></td>
- <td> </td>
- </tr>
- <tr>
- <td><code>F()</code> or <code>F( false )</code></td>
- <td><code>F</code></td>
- <td>Constructs a <b>non-blocking</b> (see below) object of
- the FifoWorker type. In single-threaded builds the second expression is
- not well-formed</td>
- </tr>
- <tr>
- <td><code>F( true )</code></td>
- <td><code>F</code></td>
- <td>Constructs a <b>blocking</b> (see below) object of the
- FifoWorker type. Not well-formed in single-threaded builds</td>
- </tr>
- <tr>
- <td><code>f.queue_work_item( w );</code></td>
- <td> </td>
- <td>Constructs and queues an object of type
- <code>F::work_item</code>, passing <code>w</code> as the only
- argument</td>
- </tr>
- <tr>
- <td><code>f.terminate();</code></td>
- <td> </td>
- <td>Creates and queues an object of type
- <code>F::work_item</code> that, when later executed in
- <code>operator()()</code>, leads to a modification of internal state so
- that <code>terminated()</code> henceforth returns
- <code>true</code></td>
- </tr>
- <tr>
- <td><code>cf.terminated();</code></td>
- <td><code>bool</code></td>
- <td><code>true</code> if <code>terminate()</code> has been
- called and the resulting work item has been executed in
- <code>operator()()</code>. Returns <code>false</code> otherwise<br>
- <br>
- <b>Must only be called from the thread that also calls
- <code>operator()()</code></b></td>
- </tr>
- <tr>
- <td><code>f( n );</code></td>
- <td><code>unsigned long</code></td>
- <td>
- Enters a loop that, with each cycle, dequeues and calls
- <code>operator()()</code> on the oldest work item in the queue.
- <p>The loop is left and the number of executed work items returned if
- one or more of the following conditions are met:</p>
- <ul>
- <li><code>f.terminated() == true</code></li>
- <li>The application is single-threaded and the internal queue is
- empty</li>
- <li>The application is multi-threaded and the internal queue is
- empty and the worker was created as non-blocking</li>
- <li><code>n != 0</code> and the number of work items that have been
- processed since <code>operator()()</code> was called equals
- <code>n</code></li>
- </ul>
- <p>If the queue is empty and none of the above conditions are met
- then the thread calling <code>operator()()</code> is put into a wait
- state until <code>f.queue_work_item()</code> is called from another
- thread.<br>
- <br>
- <b>Must only be called from exactly one thread</b></p>
- </td>
- </tr>
- <tr>
- <td><code>f();</code></td>
- <td><code>unsigned long</code></td>
- <td>Has exactly the same semantics as <code>f( n );</code>
- with <code>n == 0</code> (see above)</td>
- </tr>
- </table>
- <h2><a name="ExceptionTranslator" id=
- "ExceptionTranslator">ExceptionTranslator</a> concept</h2>
- <p>An ExceptionTranslator type defines how C++ exceptions occurring during
- state machine operation are translated to exception events.</p>
- <p>For an ExceptionTranslator object <code>et</code>, a parameterless
- function object <code>a</code> of arbitrary type returning <code><a href=
- "#Classresult">result</a></code> and a function object <code>eh</code> of
- arbitrary type taking a <code>const <a href=
- "#Classevent_base">event_base</a> &</code> parameter and returning
- <code><a href="#Classresult">result</a></code> the following expression
- must be well-formed and have the indicated results:</p>
- <table border="3" cellpadding="2" width="100%" summary=
- "ExceptionTranslator concept">
- <tr>
- <td><b>Expression</b></td>
- <td><b>Type</b></td>
- <td><b>Effects/Result</b></td>
- </tr>
- <tr>
- <td><code>et( a, eh );</code></td>
- <td><code>result</code></td>
- <td>
- <ol>
- <li>Attempts to execute <code>return a();</code></li>
- <li>If <code>a()</code> propagates an exception, the exception is
- caught</li>
- <li>Inside the catch block calls <code>eh</code>, passing a
- suitable stack-allocated model of the <a href="#Event">Event</a>
- concept</li>
- <li>Returns the result returned by <code>eh</code></li>
- </ol>
- </td>
- </tr>
- </table>
- <h2><a name="StateBase" id="StateBase">StateBase</a> concept</h2>
- <p>A StateBase type is the common base of all states of a given state
- machine type. <code>state_machine<>::state_base_type</code> is a
- model of the StateBase concept.</p>
- <p>For a StateBase type <code>S</code> and a <code>const</code> object
- <code>cs</code> of that type the following expressions must be well-formed
- and have the indicated results:</p>
- <table border="3" cellpadding="2" width="100%" summary="StateBase concept">
- <tr>
- <td><b>Expression</b></td>
- <td><b>Type</b></td>
- <td><b>Result</b></td>
- </tr>
- <tr>
- <td><code>cs.outer_state_ptr()</code></td>
- <td><code>const S *</code></td>
- <td><code>0</code> if <code>cs</code> is an <a href=
- "definitions.html#OutermostState">outermost state</a>, a pointer to the
- direct outer state of <code>cs</code> otherwise</td>
- </tr>
- <tr>
- <td><code>cs.dynamic_type()</code></td>
- <td><code>S::id_type</code></td>
- <td>A value unambiguously identifying the most-derived type
- of <code>cs</code>. <code>S::id_type</code> values are comparable with
- <code>operator==()</code> and <code>operator!=()</code>. An unspecified
- collating order can be established with <code>std::less< S::id_type
- ></code>. In contrast to <code>typeid( cs )</code>, this function is
- available even on platforms that do not support C++ RTTI (or have been
- configured to not support it)</td>
- </tr>
- <tr>
- <td><code>cs.custom_dynamic_type_ptr<<br>
- Type >()</code></td>
- <td><code>const Type *</code></td>
- <td>A pointer to the custom type identifier or
- <code>0</code>. If <code>!= 0</code>, <code>Type</code> must match the
- type of the previously set pointer. This function is only available if
- <a href=
- "configuration.html#ApplicationDefinedMacros">BOOST_STATECHART_USE_NATIVE_RTTI</a>
- is not defined</td>
- </tr>
- </table>
- <h2><a name="SimpleState" id="SimpleState">SimpleState</a> concept</h2>
- <p>A SimpleState type defines one state of a particular state machine.</p>
- <p>For a SimpleState type <code>S</code> and a pointer <code>pS</code>
- pointing to an object of type <code>S</code> allocated with
- <code>new</code> the following expressions/statements must be well-formed
- and have the indicated effects/results:</p>
- <table border="3" cellpadding="2" width="100%" summary=
- "SimpleState concept">
- <tr>
- <td><b>Expression/Statement</b></td>
- <td><b>Type</b></td>
- <td><b>Effects/Result/Notes</b></td>
- </tr>
- <tr>
- <td><code><a href=
- "#ClassTemplatesimple_state">simple_state</a><<br>
- S, C, I, h > * pB =<br>
- pS;</code></td>
- <td> </td>
- <td><code>simple_state< S, C, I, h ></code> must be
- an unambiguous public base of <code>S</code>. See <code><a href=
- "#ClassTemplatesimple_state">simple_state<></a></code>
- documentation for the requirements and semantics of <code>C</code>,
- <code>I</code> and <code>h</code></td>
- </tr>
- <tr>
- <td><code>new S()</code></td>
- <td><code>S *</code></td>
- <td>Enters the state <code>S</code>. Certain functions must
- not be called from <code>S::S()</code>, see <a href=
- "#ClassTemplatesimple_state"><code>simple_state<></code></a>
- documentation for more information</td>
- </tr>
- <tr>
- <td><code>pS->exit();</code></td>
- <td> </td>
- <td>Exits the state <code>S</code> (first stage). The
- definition of an <code>exit</code> member function within models of the
- SimpleState concept is optional since <code>simple_state<></code>
- already defines the following public member: <code>void exit()
- {}</code>. <code>exit()</code> is not called when a state is exited
- while an exception is pending, see <code><a href=
- "#simple_state::terminate">simple_state<>::terminate()</a></code>
- for more information</td>
- </tr>
- <tr>
- <td><code>delete pS;</code></td>
- <td> </td>
- <td>Exits the state <code>S</code> (second stage)</td>
- </tr>
- <tr>
- <td><code>S::reactions</code></td>
- <td>An <code>mpl::list<></code> that is either empty
- or contains instantiations of the <code><a href=
- "#ClassTemplatecustom_reaction">custom_reaction</a></code>,
- <code><a href=
- "#ClassTemplatein_state_reaction">in_state_reaction</a></code>,
- <code><a href="#ClassTemplatedeferral">deferral</a></code>,
- <code><a href="#ClassTemplatetermination">termination</a></code> or
- <code><a href="#ClassTemplatetransition">transition</a></code> class
- templates. If there is only a single reaction then it can also be
- <code>typedef</code>ed directly, without wrapping it into an
- <code>mpl::list<></code></td>
- <td>The declaration of a <code>reactions</code> member
- <code>typedef</code> within models of the SimpleState concept is
- optional since <code>simple_state<></code> already defines the
- following public member: <code>typedef mpl::list<>
- reactions;</code></td>
- </tr>
- </table>
- <h2><a name="State" id="State">State</a> concept</h2>
- <p>A State is a <b>refinement</b> of <a href="#SimpleState">SimpleState</a>
- (that is, except for the default constructor a State type must also satisfy
- SimpleState requirements). For a State type <code>S</code>, a pointer
- <code>pS</code> of type <code>S *</code> pointing to an object of type
- <code>S</code> allocated with <code>new</code>, and an object
- <code>mc</code> of type <code>state< S, C, I, h
- ></code><code>::my_context</code> the following expressions/statements
- must be well-formed:</p>
- <table border="3" cellpadding="2" width="100%" summary="State concept">
- <tr>
- <td><b>Expression/Statement</b></td>
- <td><b>Type</b></td>
- <td><b>Effects/Result/Notes</b></td>
- </tr>
- <tr>
- <td><code><a href="#ClassTemplatestate">state</a>< S, C, I, h > *<br>
- pB = pS;</code></td>
- <td> </td>
- <td><code>state< S, C, I, h ></code> must be an
- unambiguous public base of <code>S</code>. See <code><a href=
- "#ClassTemplatestate">state<></a></code> documentation for the
- requirements and semantics of <code>C</code>, <code>I</code> and
- <code>h</code></td>
- </tr>
- <tr>
- <td><code>new S( mc )</code></td>
- <td><code>S *</code></td>
- <td>Enters the state <code>S</code>. No restrictions exist
- regarding the functions that can be called from <code>S::S()</code> (in
- contrast to the constructors of models of the SimpleState concept).
- <code>mc</code> must be forwarded to <code>state< S, C, I, h
- >::state()</code></td>
- </tr>
- </table>
- <h2><a name="Event" id="Event">Event</a> concept</h2>
- <p>A Event type defines an event for which state machines can define
- reactions.</p>
- <p>For a Event type <code>E</code> and a pointer <code>pCE</code> of type
- <code>const E *</code> pointing to an object of type <code>E</code>
- allocated with <code>new</code> the following expressions/statements must
- be well-formed and have the indicated effects/results:</p>
- <table border="3" cellpadding="2" width="100%" summary="Event concept">
- <tr>
- <td><b>Expression/Statement</b></td>
- <td><b>Type</b></td>
- <td><b>Effects/Result/Notes</b></td>
- </tr>
- <tr>
- <td><code>const <a href="#ClassTemplateevent">event</a><
- E > * pCB = pCE;</code></td>
- <td> </td>
- <td><code>event< E ></code> must be an unambiguous
- public base of <code>E</code></td>
- </tr>
- <tr>
- <td><code>new E( *pCE )</code></td>
- <td><code>E *</code></td>
- <td>Makes a copy of <code>pE</code></td>
- </tr>
- </table>
- <h1>Header <boost/statechart/<a name="state_machine.hpp" id=
- "state_machine.hpp">state_machine.hpp</a>></h1>
- <h2><a name="ClassTemplatestate_machine" id=
- "ClassTemplatestate_machine">Class template
- <code>state_machine</code></a></h2>
- <p>This is the base class template of all synchronous state machines.</p>
- <h3>Class template <code>state_machine</code> parameters</h3>
- <table border="3" cellpadding="2" width="100%" summary=
- "state_machine parameters">
- <tr>
- <td><b>Template parameter</b></td>
- <td><b>Requirements</b></td>
- <td><b>Semantics</b></td>
- <td><b>Default</b></td>
- </tr>
- <tr>
- <td><code>MostDerived</code></td>
- <td>The most-derived subtype of this class template</td>
- <td> </td>
- <td> </td>
- </tr>
- <tr>
- <td><code>InitialState</code></td>
- <td>A model of the <a href="#SimpleState">SimpleState</a>
- or <a href="#State">State</a> concepts. The <code>Context</code>
- argument passed to the <code><a href=
- "#ClassTemplatesimple_state">simple_state<></a></code> or
- <code><a href="#ClassTemplatestate">state<></a></code> base
- of <code>InitialState</code> must be <code>MostDerived</code>.
- That is, <code>InitialState</code> must be an <a href=
- "definitions.html#OutermostState">outermost state</a> of this state
- machine</td>
- <td>The state that is entered when
- <code>state_machine<><br>
- ::initiate()</code> is called</td>
- <td> </td>
- </tr>
- <tr>
- <td><code>Allocator</code></td>
- <td>A model of the standard Allocator concept</td>
- <td><code>Allocator::rebind<>::other</code> is used
- to allocate and deallocate all <code>simple_state</code> subtype
- objects and internal objects of dynamic storage duration</td>
- <td><code>std::allocator< void ></code></td>
- </tr>
- <tr>
- <td><code>ExceptionTranslator</code></td>
- <td>A model of the ExceptionTranslator concept</td>
- <td>see <a href=
- "#ExceptionTranslator">ExceptionTranslator</a> concept</td>
- <td><code>null_exception_translator</code></td>
- </tr>
- </table>
- <h3>Class template <code>state_machine</code> synopsis</h3>
- <pre>
- namespace boost
- {
- namespace statechart
- {
- template<
- class MostDerived,
- class InitialState,
- class Allocator = std::allocator< void >,
- class ExceptionTranslator = null_exception_translator >
- class state_machine : noncopyable
- {
- public:
- typedef MostDerived outermost_context_type;
- void <a href="#initiate">initiate</a>();
- void <a href="#terminate">terminate</a>();
- bool <a href="#terminated">terminated</a>() const;
- void <a href="#process_event">process_event</a>( const <a href=
- "#Classevent_base">event_base</a> & );
- template< class Target >
- Target <a href="#state_cast">state_cast</a>() const;
- template< class Target >
- Target <a href="#state_downcast">state_downcast</a>() const;
- // a model of the <a href="#StateBase">StateBase</a> concept
- typedef <i>implementation-defined</i> state_base_type;
- // a model of the standard Forward Iterator concept
- typedef <i>implementation-defined</i> state_iterator;
- state_iterator <a href="#state_begin">state_begin</a>() const;
- state_iterator <a href="#state_end">state_end</a>() const;
- void <a href="#unconsumed_event">unconsumed_event</a>( const <a href=
- "#Classevent_base">event_base</a> & ) {}
- protected:
- <a href="#state_machine">state_machine</a>();
- <a href="#state_machinedtor">~state_machine</a>();
- void <a href="#post_event2">post_event</a>(
- const intrusive_ptr< const <a href=
- "#Classevent_base">event_base</a> > & );
- void <a href="#post_event3">post_event</a>( const <a href=
- "#Classevent_base">event_base</a> & );
- const event_base * <a href="#triggering_event1">triggering_event</a>() const;
- };
- }
- }
- </pre>
- <h3>Class template <code>state_machine</code> constructor and
- destructor</h3>
- <pre>
- <a name="state_machine" id="state_machine">state_machine</a>();
- </pre>
- <p><b>Effects</b>: Constructs a non-running state machine</p>
- <pre>
- <a name="state_machinedtor" id="state_machinedtor">~state_machine</a>();
- </pre>
- <p><b>Effects</b>: Destructs the currently active outermost state and all
- its direct and indirect inner states. Innermost states are destructed
- first. Other states are destructed as soon as all their direct and indirect
- inner states have been destructed. The inner states of each state are
- destructed according to the number of their orthogonal region. The state in
- the orthogonal region with the highest number is always destructed first,
- then the state in the region with the second-highest number and so on<br>
- <b>Note</b>: Does not attempt to call any <code>exit</code> member
- functions</p>
- <h3>Class template <code>state_machine</code> modifier functions</h3>
- <pre>
- void <a name="initiate" id="initiate">initiate</a>();
- </pre>
- <p><b>Effects</b>:</p>
- <ol>
- <li>Calls <code>terminate()</code></li>
- <li>Constructs a function object <code>action</code> with a
- parameter-less <code>operator()()</code> returning <code><a href=
- "#Classresult">result</a></code> that
- <ol type="a">
- <li>enters (constructs) the state specified with the
- <code>InitialState</code> template parameter</li>
- <li>enters the tree formed by the direct and indirect inner initial
- states of <code>InitialState</code> depth first. The inner states of
- each state are entered according to the number of their orthogonal
- region. The state in orthogonal region 0 is always entered first,
- then the state in region 1 and so on</li>
- </ol>
- </li>
- <li>Constructs a function object <code>exceptionEventHandler</code> with
- an <code>operator()()</code> returning <code>result</code> and accepting
- an exception event parameter that processes the passed exception event,
- with the following differences to the processing of normal events:
- <ul type="disc">
- <li>From the moment when the exception has been thrown until right
- after the execution of the exception event reaction, states that need
- to be exited are only destructed but no <code>exit</code> member
- functions are called</li>
- <li><a href="definitions.html#Reaction">Reaction</a> search always
- starts with the outermost <a href=
- "definitions.html#UnstableState">unstable state</a></li>
- <li>As for normal events, reaction search moves outward when the
- current state cannot handle the event. However, if there is no outer
- state (an <a href="definitions.html#OutermostState">outermost
- state</a> has been reached) the reaction search is considered
- unsuccessful. That is, exception events will never be dispatched to
- orthogonal regions other than the one that caused the exception
- event</li>
- <li>Should an exception be thrown during exception event reaction
- search or reaction execution then the exception is propagated out of
- the <code>exceptionEventHandler</code> function object (that is,
- <code>ExceptionTranslator</code> is <b>not</b> used to translate
- exceptions thrown while processing an exception event)</li>
- <li>If no reaction could be found for the exception event or if the
- state machine is not stable after processing the exception event, the
- original exception is rethrown. Otherwise, a <code><a href=
- "#Classresult">result</a></code> object is returned equal to the one
- returned by <code>simple_state<>::discard_event()</code></li>
- </ul>
- </li>
- <li>Passes <code>action</code> and <code>exceptionEventHandler</code> to
- <code>ExceptionTranslator::operator()()</code>. If
- <code>ExceptionTranslator::operator()()</code> throws an exception, the
- exception is propagated to the caller. If the caller catches the
- exception, the currently active outermost state and all its direct and
- indirect inner states are destructed. Innermost states are destructed
- first. Other states are destructed as soon as all their direct and
- indirect inner states have been destructed. The inner states of each
- state are destructed according to the number of their orthogonal region.
- The state in the orthogonal region with the highest number is always
- destructed first, then the state in the region with the second-highest
- number and so on. Continues with step 5 otherwise (the return value is
- discarded)</li>
- <li>Processes all posted events (see <code>process_event()</code>).
- Returns to the caller if there are no more posted events</li>
- </ol>
- <p><b>Throws</b>: Any exceptions propagated from
- <code>ExceptionTranslator::operator()()</code>. Exceptions never originate
- in the library itself but only in code supplied through template
- parameters:</p>
- <ul>
- <li><code>Allocator::rebind<>::other::allocate()</code></li>
- <li>state constructors</li>
- <li><code>react</code> member functions</li>
- <li><code>exit</code> member functions</li>
- <li>transition-actions</li>
- </ul>
- <pre>
- void <a name="terminate" id="terminate">terminate</a>();
- </pre>
- <p><b>Effects</b>:</p>
- <ol>
- <li>Constructs a function object <code>action</code> with a
- parameter-less <code>operator()()</code> returning <code><a href=
- "#Classresult">result</a></code> that <a href=
- "#simple_state::terminate">terminates</a> the currently active outermost
- state, discards all remaining events and clears all history
- information</li>
- <li>Constructs a function object <code>exceptionEventHandler</code> with
- an <code>operator()()</code> returning <code><a href=
- "#Classresult">result</a></code> and accepting an exception event
- parameter that processes the passed exception event, with the following
- differences to the processing of normal events:
- <ul type="disc">
- <li>From the moment when the exception has been thrown until right
- after the execution of the exception event reaction, states that need
- to be exited are only destructed but no <code>exit</code> member
- functions are called</li>
- <li><a href="definitions.html#Reaction">Reaction</a> search always
- starts with the outermost <a href=
- "definitions.html#UnstableState">unstable state</a></li>
- <li>As for normal events, reaction search moves outward when the
- current state cannot handle the event. However, if there is no outer
- state (an <a href="definitions.html#OutermostState">outermost
- state</a> has been reached) the reaction search is considered
- unsuccessful. That is, exception events will never be dispatched to
- orthogonal regions other than the one that caused the exception
- event</li>
- <li>Should an exception be thrown during exception event reaction
- search or reaction execution then the exception is propagated out of
- the <code>exceptionEventHandler</code> function object (that is,
- <code>ExceptionTranslator</code> is <b>not</b> used to translate
- exceptions thrown while processing an exception event)</li>
- <li>If no reaction could be found for the exception event or if the
- state machine is not stable after processing the exception event, the
- original exception is rethrown. Otherwise, a <code><a href=
- "#Classresult">result</a></code> object is returned equal to the one
- returned by <code>simple_state<>::discard_event()</code></li>
- </ul>
- </li>
- <li>Passes <code>action</code> and <code>exceptionEventHandler</code> to
- <code>ExceptionTranslator::operator()()</code>. If
- <code>ExceptionTranslator::operator()()</code> throws an exception, the
- exception is propagated to the caller. If the caller catches the
- exception, the currently active outermost state and all its direct and
- indirect inner states are destructed. Innermost states are destructed
- first. Other states are destructed as soon as all their direct and
- indirect inner states have been destructed. The inner states of each
- state are destructed according to the number of their orthogonal region.
- The state in the orthogonal region with the highest number is always
- destructed first, then the state in the region with the second-highest
- number and so on. Otherwise, returns to the caller</li>
- </ol>
- <p><b>Throws</b>: Any exceptions propagated from
- <code>ExceptionTranslator::operator()</code>. Exceptions never originate in
- the library itself but only in code supplied through template
- parameters:</p>
- <ul>
- <li><code>Allocator::rebind<>::other::allocate()</code></li>
- <li>state constructors</li>
- <li><code>react</code> member functions</li>
- <li><code>exit</code> member functions</li>
- <li>transition-actions</li>
- </ul>
- <pre>
- void <a name="process_event" id=
- "process_event">process_event</a>( const <a href=
- "#Classevent_base">event_base</a> & );
- </pre>
- <p><b>Effects</b>:</p>
- <ol>
- <li>Selects the passed event as the current event (henceforth referred to
- as <code>currentEvent</code>)</li>
- <li>Starts a new <a href="definitions.html#Reaction">reaction</a>
- search</li>
- <li>Selects an arbitrary but in this reaction search not yet visited
- state from all the currently active <a href=
- "definitions.html#InnermostState">innermost states</a>. If no such state
- exists then continues with step 10</li>
- <li>Constructs a function object <code>action</code> with a
- parameter-less <code>operator()()</code> returning <code><a href=
- "#Classresult">result</a></code> that does the following:
- <ol type="a">
- <li>Searches a reaction suitable for <code>currentEvent</code>,
- starting with the current innermost state and moving outward until a
- state defining a reaction for the event is found. Returns
- <code>simple_state<>::forward_event()</code> if no reaction has
- been found</li>
- <li>Executes the found reaction. If the reaction result is equal to
- the return value of
- <code>simple_state<>::forward_event()</code> then resumes the
- reaction search (step a). Returns the reaction result otherwise</li>
- </ol>
- </li>
- <li>Constructs a function object <code>exceptionEventHandler</code>
- returning <code><a href="#Classresult">result</a></code> and accepting an
- exception event parameter that processes the passed exception event, with
- the following differences to the processing of normal events:
- <ul type="disc">
- <li>From the moment when the exception has been thrown until right
- after the execution of the exception event reaction, states that need
- to be exited are only destructed but no <code>exit</code> member
- functions are called</li>
- <li>If the state machine is stable when the exception event is
- processed then exception event reaction search starts with the
- innermost state that was last visited during the last normal event
- reaction search (the exception event was generated as a result of
- this normal reaction search)</li>
- <li>If the state machine is <a href=
- "definitions.html#UnstableStateMachine">unstable</a> when the
- exception event is processed then exception event reaction search
- starts with the outermost <a href=
- "definitions.html#UnstableState">unstable state</a></li>
- <li>As for normal events, reaction search moves outward when the
- current state cannot handle the event. However, if there is no outer
- state (an <a href="definitions.html#OutermostState">outermost
- state</a> has been reached) the reaction search is considered
- unsuccessful. That is, exception events will never be dispatched to
- orthogonal regions other than the one that caused the exception
- event</li>
- <li>Should an exception be thrown during exception event reaction
- search or reaction execution then the exception is propagated out of
- the <code>exceptionEventHandler</code> function object (that is,
- <code>ExceptionTranslator</code> is <b>not</b> used to translate
- exceptions thrown while processing an exception event)</li>
- <li>If no reaction could be found for the exception event or if the
- state machine is not stable after processing the exception event, the
- original exception is rethrown. Otherwise, a <code><a href=
- "#Classresult">result</a></code> object is returned equal to the one
- returned by <code>simple_state<>::discard_event()</code></li>
- </ul>
- </li>
- <li>Passes <code>action</code> and <code>exceptionEventHandler</code> to
- <code>ExceptionTranslator::operator()()</code>. If
- <code>ExceptionTranslator::operator()()</code> throws an exception, the
- exception is propagated to the caller. If the caller catches the
- exception, the currently active outermost state and all its direct and
- indirect inner states are destructed. Innermost states are destructed
- first. Other states are destructed as soon as all their direct and
- indirect inner states have been destructed. The inner states of each
- state are destructed according to the number of their orthogonal region.
- The state in the orthogonal region with the highest number is always
- destructed first, then the state in the region with the second-highest
- number and so on. Otherwise continues with step 7</li>
- <li>If the return value of <code>ExceptionTranslator::operator()()</code>
- is equal to the one of <code>simple_state<>::forward_event()</code>
- then continues with step 3</li>
- <li>If the return value of <code>ExceptionTranslator::operator()()</code>
- is equal to the one of <code>simple_state<>::defer_event()</code>
- then the return value of <code>currentEvent.<a href=
- "#intrusive_from_this">intrusive_from_this</a>()</code> is stored in the
- deferred events queue. Continues with step 11</li>
- <li>If the return value of <code>ExceptionTranslator::operator()()</code>
- is equal to the one of <code>simple_state<>::discard_event()</code>
- then continues with step 11</li>
- <li>Calls <code>static_cast< MostDerived * >( this
- )->unconsumed_event( currentEvent )</code>. If
- <code>unconsumed_event()</code> throws an exception, the exception is
- propagated to the caller. Such an exception never leads to the
- destruction of any states (in contrast to exceptions propagated from
- <code>ExceptionTranslator::operator()()</code>)</li>
- <li>If the posted events queue is non-empty then dequeues the first
- event, selects it as <code>currentEvent</code> and continues with step 2.
- Returns to the caller otherwise</li>
- </ol>
- <p><b>Throws</b>: Any exceptions propagated from
- <code>MostDerived::unconsumed_event()</code> or
- <code>ExceptionTranslator::operator()</code>. Exceptions never originate in
- the library itself but only in code supplied through template
- parameters:</p>
- <ul>
- <li><code>Allocator::rebind<>::other::allocate()</code></li>
- <li>state constructors</li>
- <li><code>react</code> member functions</li>
- <li><code>exit</code> member functions</li>
- <li>transition-actions</li>
- <li><code>MostDerived::unconsumed_event()</code></li>
- </ul>
- <pre>
- void <a name="post_event2" id="post_event2">post_event</a>(
- const intrusive_ptr< const <a href=
- "#Classevent_base">event_base</a> > & );
- </pre>
- <p><b>Effects</b>: Pushes the passed event into the posted events queue<br>
- <b>Throws</b>: Any exceptions propagated from
- <code>Allocator::allocate()</code></p>
- <pre>
- void <a name="post_event3" id="post_event3">post_event</a>( const <a href=
- "#Classevent_base">event_base</a> & evt );
- </pre>
- <p><b>Effects</b>: <code>post_event( evt.intrusive_from_this()
- );</code><br>
- <b>Throws</b>: Any exceptions propagated from
- <code>Allocator::allocate()</code></p>
- <pre>
- void <a name="unconsumed_event" id=
- "unconsumed_event">unconsumed_event</a>( const <a href=
- "#Classevent_base">event_base</a> & evt );
- </pre>
- <p><b>Effects</b>: None<br>
- <b>Note</b>: This function (or, if present, the equally named derived class
- member function) is called by <a href="#process_event">process_event</a>()
- whenever a dispatched event did not trigger a reaction, see <a href=
- "#process_event">process_event</a>() effects, point 10 for more
- information.</p>
- <h3>Class template <code>state_machine</code> observer functions</h3>
- <pre>
- bool <a name="terminated" id="terminated">terminated</a>() const;
- </pre>
- <p><b>Returns</b>: <code>true</code>, if the machine is terminated. Returns
- <code>false</code> otherwise<br>
- <b>Note</b>: Is equivalent to <code>state_begin() == state_end()</code></p>
- <pre>
- template< class Target >
- Target <a name="state_cast" id="state_cast">state_cast</a>() const;
- </pre>
- <p><b>Returns</b>: Depending on the form of <code>Target</code> either a
- reference or a pointer to <code>const</code> if at least one of the
- currently active states can successfully be <code>dynamic_cast</code> to
- <code>Target</code>. Returns <code>0</code> for pointer targets and throws
- <code>std::bad_cast</code> for reference targets otherwise.
- <code>Target</code> can take either of the following forms: <code>const
- Class *</code> or <code>const Class &</code><br>
- <b>Throws</b>: <code>std::bad_cast</code> if <code>Target</code> is a
- reference type and none of the active states can be
- <code>dynamic_cast</code> to Target<br>
- <b>Note</b>: The search sequence is the same as for <code><a href=
- "#process_event">process_event</a>()</code></p>
- <pre>
- template< class Target >
- Target <a name="state_downcast" id=
- "state_downcast">state_downcast</a>() const;
- </pre>
- <p><b>Requires</b>: For reference targets the compiler must support partial
- specialization of class templates, otherwise a compile-time error will
- result. The type denoted by <code>Target</code> must be a model of the
- <a href="#SimpleState">SimpleState</a> or <a href="#State">State</a>
- concepts<br>
- <b>Returns</b>: Depending on the form of <code>Target</code> either a
- reference or a pointer to <code>const</code> if <code>Target</code> is
- equal to the most-derived type of a currently active state. Returns
- <code>0</code> for pointer targets and throws <code>std::bad_cast</code>
- for reference targets otherwise. <code>Target</code> can take either of the
- following forms: <code>const Class *</code> or <code>const Class
- &</code><br>
- <b>Throws</b>: <code>std::bad_cast</code> if <code>Target</code> is a
- reference type and none of the active states has a most derived type equal
- to <code>Target</code><br>
- <b>Note</b>: The search sequence is the same as for <code><a href=
- "#process_event">process_event</a>()</code></p>
- <pre>
- state_iterator <a name="state_begin" id=
- "state_begin">state_begin</a>() const;
- </pre>
- <pre>
- state_iterator <a name="state_end" id="state_end">state_end</a>() const;
- </pre>
- <p><b>Return</b>: Iterator objects, the range [<code>state_begin()</code>,
- <code>state_end()</code>) refers to all currently active <a href=
- "definitions.html#InnermostState">innermost states</a>. For an object
- <code>i</code> of type <code>state_iterator</code>, <code>*i</code> returns
- a <code>const state_base_type &</code> and
- <code>i.operator->()</code> returns a <code>const state_base_type
- *</code><br>
- <b>Note</b>: The position of a given innermost state in the range is
- arbitrary. It may change with each call to a modifier function. Moreover,
- all iterators are invalidated whenever a modifier function is called</p>
- <pre>
- const event_base * <a name="triggering_event1" id="triggering_event1">triggering_event</a>();
- </pre>
- <p><b>Returns</b>: A pointer to the event that triggered the reaction that is currently
- being executed. Returns <code>0</code> if no reaction is being executed or if the current
- reaction was triggered by either <code><a href="#initiate">initiate</a>()</code> or
- <code><a href="#terminate">terminate</a>()</code>
- </p>
- <h1>Header <boost/statechart/<br>
- <a name="asynchronous_state_machine.hpp" id=
- "asynchronous_state_machine.hpp">asynchronous_state_machine.hpp</a>></h1>
- <h2><a name="ClassTemplateasynchronous_state_machine" id=
- "ClassTemplateasynchronous_state_machine">Class template
- <code>asynchronous_state_machine</code></a></h2>
- <p>This is the base class template of all asynchronous state machines.</p>
- <h3>Class template <code>asynchronous_state_machine</code> parameters</h3>
- <table border="3" cellpadding="2" width="100%" summary=
- "asynchronous_state_machine parameters">
- <tr>
- <td><b>Template parameter</b></td>
- <td><b>Requirements</b></td>
- <td><b>Semantics</b></td>
- <td><b>Default</b></td>
- </tr>
- <tr>
- <td><code>MostDerived</code></td>
- <td>The most-derived subtype of this class template</td>
- <td> </td>
- <td> </td>
- </tr>
- <tr>
- <td><code>InitialState</code></td>
- <td>A model of the <a href="#SimpleState">SimpleState</a>
- or <a href="#State">State</a> concepts. The <code>Context</code>
- argument passed to the <code><a href=
- "#ClassTemplatesimple_state">simple_state<></a></code> or
- <code><a href="#ClassTemplatestate">state<></a></code> base of
- <code>InitialState</code> must be <code>MostDerived</code>. That is,
- <code>InitialState</code> must be an <a href=
- "definitions.html#OutermostState">outermost state</a> of this state
- machine</td>
- <td>The state that is entered when the state machine is
- initiated through the <code>Scheduler</code> object</td>
- <td> </td>
- </tr>
- <tr>
- <td><code>Scheduler</code></td>
- <td>A model of the Scheduler concept</td>
- <td>see <a href="#Scheduler">Scheduler</a> concept</td>
- <td><code>fifo_scheduler<></code></td>
- </tr>
- <tr>
- <td><code>Allocator</code></td>
- <td>A model of the standard Allocator concept</td>
- <td> </td>
- <td><code>std::allocator< void ></code></td>
- </tr>
- <tr>
- <td><code>ExceptionTranslator</code></td>
- <td>A model of the ExceptionTranslator concept</td>
- <td>see <a href=
- "#ExceptionTranslator">ExceptionTranslator</a> concept</td>
- <td><code>null_exception_translator</code></td>
- </tr>
- </table>
- <h3>Class template <code>asynchronous_state_machine</code> synopsis</h3>
- <pre>
- namespace boost
- {
- namespace statechart
- {
- template<
- class MostDerived,
- class InitialState,
- class Scheduler = fifo_scheduler<>,
- class Allocator = std::allocator< void >,
- class ExceptionTranslator = null_exception_translator >
- class asynchronous_state_machine :
- public state_machine<
- MostDerived, InitialState, Allocator, ExceptionTranslator >,
- public event_processor< Scheduler >
- {
- protected:
- typedef asynchronous_state_machine my_base;
- asynchronous_state_machine(
- typename event_processor< Scheduler >::my_context ctx );
- ~asynchronous_state_machine();
- };
- }
- }
- </pre>
- <h3>Class template <code>asynchronous_state_machine</code> constructor and
- destructor</h3>
- <pre>
- asynchronous_state_machine(
- typename event_processor< Scheduler >::my_context ctx );
- </pre>
- <p><b>Effects</b>: Constructs a non-running asynchronous state machine<br>
- <b>Note</b>: Users cannot create
- <code>asynchronous_state_machine<></code> subtype objects directly.
- This can only be done through an object of the <code>Scheduler</code>
- class</p>
- <pre>
- ~asynchronous_state_machine();
- </pre>
- <p><b>Effects</b>: Destructs the state machine<br>
- <b>Note</b>: Users cannot destruct
- <code>asynchronous_state_machine<></code> subtype objects directly.
- This can only be done through an object of the <code>Scheduler</code>
- class</p>
- <h1>Header <boost/statechart/<a name="event_processor.hpp" id=
- "event_processor.hpp">event_processor.hpp</a>></h1>
- <h2><a name="ClassTemplateevent_processor" id=
- "ClassTemplateevent_processor">Class template
- <code>event_processor</code></a></h2>
- <p>This is the base class template of all types that process events.
- <code>asynchronous_state_machine<></code> is just one possible event
- processor implementation.</p>
- <h3>Class template <code>event_processor</code> parameters</h3>
- <table border="3" cellpadding="2" width="100%" summary=
- "event_processor parameters">
- <tr>
- <td><b>Template parameter</b></td>
- <td><b>Requirements</b></td>
- <td><b>Semantics</b></td>
- </tr>
- <tr>
- <td><code>Scheduler</code></td>
- <td>A model of the Scheduler concept</td>
- <td>see <a href="#Scheduler">Scheduler</a> concept</td>
- </tr>
- </table>
- <h3>Class template <code>event_processor</code> synopsis</h3>
- <pre>
- namespace boost
- {
- namespace statechart
- {
- template< class Scheduler >
- class event_processor
- {
- public:
- virtual <a href="#event_processordtor">~event_processor</a>();
- Scheduler & <a href="#my_scheduler">my_scheduler</a>() const;
- typedef typename Scheduler::processor_handle
- processor_handle;
- processor_handle <a href="#my_handle">my_handle</a>() const;
- void <a href="#event_processor::initiate">initiate</a>();
- void <a href=
- "#event_processor::process_event">process_event</a>( const event_base & evt );
- void <a href="#event_processor::terminate">terminate</a>();
- protected:
- typedef const typename Scheduler::processor_context &
- my_context;
- <a href="#event_processor">event_processor</a>( my_context ctx );
- private:
- virtual void initiate_impl() = 0;
- virtual void process_event_impl(
- const event_base & evt ) = 0;
- virtual void terminate_impl() = 0;
- };
- }
- }
- </pre>
- <h3>Class template <code>event_processor</code> constructor and
- destructor</h3>
- <pre>
- <a name="event_processor" id=
- "event_processor">event_processor</a>( my_context ctx );
- </pre>
- <p><b>Effects</b>: Constructs an event processor object and stores copies
- of the reference returned by <code>myContext.my_scheduler()</code> and the
- object returned by <code>myContext.my_handle()</code><br>
- <b>Note</b>: Users cannot create <code>event_processor<></code>
- subtype objects directly. This can only be done through an object of the
- <code>Scheduler</code> class</p>
- <pre>
- virtual <a name="event_processordtor" id=
- "event_processordtor">~event_processor</a>();
- </pre>
- <p><b>Effects</b>: Destructs an event processor object<br>
- <b>Note</b>: Users cannot destruct <code>event_processor<></code>
- subtype objects directly. This can only be done through an object of the
- <code>Scheduler</code> class</p>
- <h3>Class template <code>event_processor</code> modifier functions</h3>
- <pre>
- void <a name="event_processor::initiate" id=
- "event_processor::initiate">initiate</a>();
- </pre>
- <p><b>Effects</b>: <code>initiate_impl();<br></code><b>Throws</b>: Any
- exceptions propagated from the implementation of
- <code>initiate_impl()</code></p>
- <pre>
- void <a name="event_processor::process_event" id=
- "event_processor::process_event">process_event</a>( const event_base & evt );
- </pre>
- <p><b>Effects</b>: <code>process_event_impl( evt
- );<br></code><b>Throws</b>: Any exceptions propagated from the
- implementation of <code>process_event_impl()</code></p>
- <pre>
- void <a name="event_processor::terminate" id=
- "event_processor::terminate">terminate</a>();
- </pre>
- <p><b>Effects</b>: <code>terminate_impl();<br></code><b>Throws</b>: Any
- exceptions propagated from the implementation of
- <code>terminate_impl()</code></p>
- <h3>Class template <code>event_processor</code> observer functions</h3>
- <pre>
- Scheduler & <a name="my_scheduler" id=
- "my_scheduler">my_scheduler</a>() const;
- </pre>
- <p><b>Returns</b>: The <code>Scheduler</code> reference obtained in the
- constructor</p>
- <pre>
- processor_handle <a name="my_handle" id="my_handle">my_handle</a>() const;
- </pre>
- <p><b>Returns</b>: The <code>processor_handle</code> object obtained in the
- constructor</p>
- <h1>Header <boost/statechart/<a name="fifo_scheduler.hpp" id=
- "fifo_scheduler.hpp">fifo_scheduler.hpp</a>></h1>
- <h2><a name="ClassTemplatefifo_scheduler" id=
- "ClassTemplatefifo_scheduler">Class template
- <code>fifo_scheduler</code></a></h2>
- <p>This class template is a model of the <a href="#Scheduler">Scheduler</a>
- concept.</p>
- <h3>Class template <code>fifo_scheduler</code> parameters</h3>
- <table border="3" cellpadding="2" width="100%" summary=
- "fifo_scheduler parameters">
- <tr>
- <td><b>Template parameter</b></td>
- <td><b>Requirements</b></td>
- <td><b>Semantics</b></td>
- <td><b>Default</b></td>
- </tr>
- <tr>
- <td><code>FifoWorker</code></td>
- <td>A model of the FifoWorker concept</td>
- <td>see <a href="#FifoWorker">FifoWorker</a> concept</td>
- <td><code>fifo_worker<></code></td>
- </tr>
- <tr>
- <td><code>Allocator</code></td>
- <td>A model of the standard Allocator concept</td>
- <td> </td>
- <td><code>std::allocator< void ></code></td>
- </tr>
- </table>
- <h3>Class template <code>fifo_scheduler</code> synopsis</h3>
- <pre>
- namespace boost
- {
- namespace statechart
- {
- template<
- class FifoWorker = fifo_worker<>,
- class Allocator = std::allocator< void > >
- class fifo_scheduler : noncopyable
- {
- public:
- <a href=
- "#fifo_scheduler::fifo_scheduler">fifo_scheduler</a>( bool waitOnEmptyQueue = false );
- typedef <i>implementation-defined</i> processor_handle;
- class processor_context : noncopyable
- {
- processor_context(
- fifo_scheduler & scheduler,
- const processor_handle & theHandle );
- fifo_scheduler & my_scheduler() const;
- const processor_handle & my_handle() const;
- friend class fifo_scheduler;
- friend class event_processor< fifo_scheduler >;
- };
- template< class Processor >
- processor_handle <a href="#create_processor">create_processor</a>();
- template< class Processor, typename Param1 >
- processor_handle <a href=
- "#create_processor1">create_processor</a>( Param1 param1 );
- // More create_processor overloads
- void <a href=
- "#destroy_processor">destroy_processor</a>( processor_handle processor );
- void <a href=
- "#initiate_processor">initiate_processor</a>( processor_handle processor );
- void <a href=
- "#terminate_processor">terminate_processor</a>( processor_handle processor );
- typedef intrusive_ptr< const event_base > event_ptr_type;
- void <a href="#queue_event">queue_event</a>(
- const processor_handle & processor,
- const event_ptr_type & pEvent );
- typedef typename FifoWorker::work_item work_item;
- void <a href=
- "#queue_work_item">queue_work_item</a>( const work_item & item );
- void <a href="#fifo_scheduler::terminate">terminate</a>();
- bool <a href="#fifo_scheduler::terminated">terminated</a>() const;
- unsigned long <a href="#operatorfuncall">operator()</a>(
- unsigned long maxEventCount = 0 );
- };
- }
- }
- </pre>
- <h3>Class template <code>fifo_scheduler</code> constructor</h3>
- <pre>
- <a name="fifo_scheduler::fifo_scheduler" id=
- "fifo_scheduler::fifo_scheduler">fifo_scheduler</a>( bool waitOnEmptyQueue = false );
- </pre>
- <p><b>Effects</b>: Constructs a <code>fifo_scheduler<></code> object.
- In multi-threaded builds, <code>waitOnEmptyQueue</code> is forwarded to the
- constructor of a data member of type <code>FifoWorker</code>. In
- single-threaded builds, the <code>FifoWorker</code> data member is
- default-constructed<br>
- <b>Note</b>: In single-threaded builds the
- <code>fifo_scheduler<></code> constructor does not accept any
- parameters and <code>operator()()</code> thus always returns to the caller
- when the event queue is empty</p>
- <h3>Class template <code>fifo_scheduler</code> modifier functions</h3>
- <pre>
- template< class Processor >
- processor_handle <a name="create_processor" id=
- "create_processor">create_processor</a>();
- </pre>
- <p><b>Requires</b>: The <code>Processor</code> type must be a direct or
- indirect subtype of the <a href=
- "#ClassTemplateevent_processor"><code>event_processor</code></a> class
- template<br>
- <b>Effects</b>: Creates and passes to
- <code>FifoWorker::queue_work_item()</code> an object of type
- <code>FifoWorker::work_item</code> that, when later executed in
- <code>FifoWorker::operator()()</code>, leads to a call to the constructor
- of <code>Processor</code>, passing an appropriate
- <code>processor_context</code> object as the only argument<br>
- <b>Returns</b>: A <code>processor_handle</code> object that henceforth
- identifies the created event processor object<br>
- <b>Throws</b>: Any exceptions propagated from
- <code>FifoWorker::work_item()</code> and
- <code>FifoWorker::queue_work_item()</code><br>
- <b>Caution</b>: The current implementation of this function makes an
- (indirect) call to global <code>operator new()</code>. Unless global
- <code>operator new()</code> is replaced, care must be taken when to call
- this function in applications with hard real-time requirements</p>
- <pre>
- template< class Processor, typename Param1 >
- processor_handle <a name="create_processor1" id=
- "create_processor1">create_processor( Param1 param1 )</a>;
- </pre>
- <p><b>Requires</b>: The <code>Processor</code> type must be a direct or
- indirect subtype of the <a href=
- "#ClassTemplateevent_processor"><code>event_processor</code></a> class
- template<br>
- <b>Effects</b>: Creates and passes to
- <code>FifoWorker::queue_work_item()</code> an object of type
- <code>FifoWorker::work_item</code> that, when later executed in
- <code>FifoWorker::operator()()</code>, leads to a call to the constructor
- of <code>Processor</code>, passing an appropriate
- <code>processor_context</code> object and <code>param1</code> as
- arguments<br>
- <b>Returns</b>: A <code>processor_handle</code> object that henceforth
- identifies the created event processor object<br>
- <b>Throws</b>: Any exceptions propagated from
- <code>FifoWorker::work_item()</code> and
- <code>FifoWorker::queue_work_item()</code><b><br>
- Note</b>: <code>boost::ref()</code> and <code>boost::cref()</code> can be
- used to pass arguments by reference rather than by copy.
- <code>fifo_scheduler<></code> has 5 additional
- <code>create_processor<></code> overloads, allowing to pass up to 6
- custom arguments to the constructors of event processors<br>
- <b>Caution</b>: The current implementation of this and all other overloads
- make (indirect) calls to global <code>operator new()</code>. Unless global
- <code>operator new()</code> is replaced, care must be taken when to call
- these overloads in applications with hard real-time requirements</p>
- <pre>
- void <a name="destroy_processor" id=
- "destroy_processor">destroy_processor</a>( processor_handle processor );
- </pre>
- <p><b>Requires</b>: <code>processor</code> was obtained from a call to one
- of the <code>create_processor<>()</code> overloads on the same
- <code>fifo_scheduler<></code> object<br>
- <b>Effects</b>: Creates and passes to
- <code>FifoWorker::queue_work_item()</code> an object of type
- <code>FifoWorker::work_item</code> that, when later executed in
- <code>FifoWorker::operator()()</code>, leads to a call to the destructor of
- the event processor object associated with <code>processor</code>. The
- object is silently discarded if the event processor object has been
- destructed before<br>
- <b>Throws</b>: Any exceptions propagated from
- <code>FifoWorker::work_item()</code> and
- <code>FifoWorker::queue_work_item()</code><br>
- <b>Caution</b>: The current implementation of this function leads to an
- (indirect) call to global <code>operator delete()</code> (the call is made
- when the last <code>processor_handle</code> object associated with the
- event processor object is destructed). Unless global <code>operator
- delete()</code> is replaced, care must be taken when to call this function
- in applications with hard real-time requirements</p>
- <pre>
- void <a name="initiate_processor" id=
- "initiate_processor">initiate_processor</a>( processor_handle processor );
- </pre>
- <p><b>Requires</b>: <code>processor</code> was obtained from a call to one
- of the <code>create_processor()</code> overloads on the same
- <code>fifo_scheduler<></code> object<br>
- <b>Effects</b>: Creates and passes to
- <code>FifoWorker::queue_work_item()</code> an object of type
- <code>FifoWorker::work_item</code> that, when later executed in
- <code>FifoWorker::operator()()</code>, leads to a call to <code><a href=
- "#event_processor::initiate">initiate</a>()</code> on the event processor
- object associated with <code>processor</code>. The object is silently
- discarded if the event processor object has been destructed before<br>
- <b>Throws</b>: Any exceptions propagated from
- <code>FifoWorker::work_item()</code> and
- <code>FifoWorker::queue_work_item()</code></p>
- <pre>
- void <a name="terminate_processor" id=
- "terminate_processor">terminate_processor</a>( processor_handle processor );
- </pre>
- <p><b>Requires</b>: <code>processor</code> was obtained from a call to one
- of the <code>create_processor<>()</code> overloads on the same
- <code>fifo_scheduler<></code> object<br>
- <b>Effects</b>: Creates and passes to
- <code>FifoWorker::queue_work_item()</code> an object of type
- <code>FifoWorker::work_item</code> that, when later executed in
- <code>FifoWorker::operator()()</code>, leads to a call to <code><a href=
- "#event_processor::terminate">terminate</a>()</code> on the event processor
- object associated with <code>processor</code>. The object is silently
- discarded if the event processor object has been destructed before<br>
- <b>Throws</b>: Any exceptions propagated from
- <code>FifoWorker::work_item()</code> and
- <code>FifoWorker::queue_work_item()</code></p>
- <pre>
- void <a name="queue_event" id="queue_event">queue_event</a>(
- const processor_handle & processor,
- const event_ptr_type & pEvent );
- </pre>
- <p><b>Requires</b>: <code>pEvent.get() != 0</code> and
- <code>processor</code> was obtained from a call to one of the
- <code>create_processor<>()</code> overloads on the same
- <code>fifo_scheduler<></code> object<br>
- <b>Effects</b>: Creates and passes to
- <code>FifoWorker::queue_work_item()</code> an object of type
- <code>FifoWorker::work_item</code> that, when later executed in
- <code>FifoWorker::operator()()</code>, leads to a call to <code><a href=
- "#event_processor::process_event">process_event</a>( *pEvent )</code> on
- the event processor object associated with <code>processor</code>. The
- object is silently discarded if the event processor object has been
- destructed before<br>
- <b>Throws</b>: Any exceptions propagated from
- <code>FifoWorker::work_item()</code> and
- <code>FifoWorker::queue_work_item()</code></p>
- <pre>
- void <a name="queue_work_item" id=
- "queue_work_item">queue_work_item</a>( const work_item & item );
- </pre>
- <p><b>Effects</b>: <code>FifoWorker::queue_work_item( item );</code><br>
- <b>Throws</b>: Any exceptions propagated from the above call</p>
- <pre>
- void <a name="fifo_scheduler::terminate" id=
- "fifo_scheduler::terminate">terminate</a>();
- </pre>
- <p><b>Effects</b>: <code>FifoWorker::terminate()</code><br>
- <b>Throws</b>: Any exceptions propagated from the above call</p>
- <pre>
- unsigned long <a name="operatorfuncall" id=
- "operatorfuncall">operator()</a>( unsigned long maxEventCount = 0 );
- </pre>
- <p><b>Requires</b>: Must only be called from exactly one thread<b><br>
- Effects</b>: <code>FifoWorker::operator()( maxEventCount )</code><br>
- <b>Returns</b>: The return value of the above call<br>
- <b>Throws</b>: Any exceptions propagated from the above call</p>
- <h3>Class template <code>fifo_scheduler</code> observer functions</h3>
- <pre>
- bool <a name="fifo_scheduler::terminated" id=
- "fifo_scheduler::terminated">terminated</a>() const;
- </pre>
- <p><b>Requires</b>: Must only be called from the thread that also calls
- <code>operator()()</code><br>
- <b>Returns</b>: <code>FifoWorker::terminated();</code></p>
- <h1>Header <boost/statechart/<a name="exception_translator.hpp" id=
- "exception_translator.hpp">exception_translator.hpp</a>></h1>
- <h2><a name="ClassTemplateexception_translator" id=
- "ClassTemplateexception_translator">Class template
- <code>exception_translator</code></a></h2>
- <p>This class template is a model of the <a href=
- "#ExceptionTranslator">ExceptionTranslator</a> concept.</p>
- <h3>Class template <code>exception_translator</code> parameters</h3>
- <table border="3" cellpadding="2" width="100%" summary=
- "exception_translator parameters">
- <tr>
- <td><b>Template parameter</b></td>
- <td><b>Requirements</b></td>
- <td><b>Semantics</b></td>
- <td><b>Default</b></td>
- </tr>
- <tr>
- <td><code>ExceptionEvent</code></td>
- <td>A model of the <a href="#Event">Event</a> concept</td>
- <td>The type of event that is dispatched when an exception
- is propagated into the framework</td>
- <td><code>exception_thrown</code></td>
- </tr>
- </table>
- <h3>Class template <code>exception_translator</code> synopsis &
- semantics</h3>
- <pre>
- namespace boost
- {
- namespace statechart
- {
- class exception_thrown : public event< exception_thrown > {};
- template< class ExceptionEvent = exception_thrown >
- class exception_translator
- {
- public:
- template< class Action, class ExceptionEventHandler >
- result operator()(
- Action action,
- ExceptionEventHandler eventHandler )
- {
- try
- {
- return action();
- }
- catch( ... )
- {
- return eventHandler( ExceptionEvent() );
- }
- }
- };
- }
- }
- </pre>
- <h1>Header <boost/statechart/<br>
- <a name="null_exception_translator.hpp" id=
- "null_exception_translator.hpp">null_exception_translator.hpp</a>></h1>
- <h2><a name="Classnull_exception_translator" id=
- "Classnull_exception_translator">Class
- <code>null_exception_translator</code></a></h2>
- <p>This class is a model of the <a href=
- "#ExceptionTranslator">ExceptionTranslator</a> concept.</p>
- <h3>Class <code>null_exception_translator</code> synopsis &
- semantics</h3>
- <pre>
- namespace boost
- {
- namespace statechart
- {
- class null_exception_translator
- {
- public:
- template< class Action, class ExceptionEventHandler >
- result operator()(
- Action action, ExceptionEventHandler )
- {
- return action();
- }
- };
- }
- }
- </pre>
- <h1>Header <boost/statechart/<a name="simple_state.hpp" id=
- "simple_state.hpp">simple_state.hpp</a>></h1>
- <h2><a name="Enumhistory_mode" id="Enumhistory_mode">Enum
- <code>history_mode</code></a></h2>
- <p>Defines the history type of a state.</p>
- <pre>
- namespace boost
- {
- namespace statechart
- {
- enum history_mode
- {
- has_no_history,
- has_shallow_history,
- has_deep_history,
- has_full_history // shallow & deep
- };
- }
- }
- </pre>
- <h2><a name="ClassTemplatesimple_state" id=
- "ClassTemplatesimple_state">Class template
- <code>simple_state</code></a></h2>
- <p>This is the base class template for all models of the <a href=
- "#SimpleState">SimpleState</a> concept. Such models must not call any of
- the following <code>simple_state<></code> member functions from their
- constructors:</p>
- <pre>
- void <b>post_event</b>(
- const intrusive_ptr< const event_base > & );
- void <b>post_event</b>( const event_base & );
- template<
- class HistoryContext,
- <i>implementation-defined-unsigned-integer-type
- </i> orthogonalPosition >
- void <b>clear_shallow_history</b>();
- template<
- class HistoryContext,
- <i>implementation-defined-unsigned-integer-type
- </i> orthogonalPosition >
- void <b>clear_deep_history</b>();
- outermost_context_type & <b>outermost_context</b>();
- const outermost_context_type & <b>outermost_context</b>() const;
- template< class OtherContext >
- OtherContext & <b>context</b>();
- template< class OtherContext >
- const OtherContext & <b>context</b>() const;
- template< class Target >
- Target <b>state_cast</b>() const;
- template< class Target >
- Target <b>state_downcast</b>() const;
- state_iterator <b>state_begin</b>() const;
- state_iterator <b>state_end</b>() const;
- const event_base * <b>triggering_event</b>() const;
- </pre>
- <p>States that need to call any of these member functions from their
- constructors must derive from the <code><a href=
- "#ClassTemplatestate">state</a></code> class template.</p>
- <h3>Class template <code>simple_state</code> parameters</h3>
- <table border="3" cellpadding="2" width="100%" summary=
- "simple_state parameters">
- <tr>
- <td><b>Template parameter</b></td>
- <td><b>Requirements</b></td>
- <td><b>Semantics</b></td>
- <td><b>Default</b></td>
- </tr>
- <tr>
- <td><code>MostDerived</code></td>
- <td>The most-derived subtype of this class template</td>
- <td> </td>
- <td> </td>
- </tr>
- <tr>
- <td><code>Context</code></td>
- <td>A most-derived direct or indirect subtype of the
- <code><a href="#ClassTemplatestate_machine">state_machine</a></code> or
- <code><a href=
- "#ClassTemplateasynchronous_state_machine">asynchronous_state_machine</a></code>
- class templates or a model of the <a href=
- "#SimpleState">SimpleState</a> or <a href="#State">State</a> concepts
- or an instantiation of the <code><a href=
- "#ClassTemplatesimple_state">simple_state<>::orthogonal</a></code>
- class template. Must be a complete type</td>
- <td>Defines the states' position in the state
- hierarchy</td>
- <td> </td>
- </tr>
- <tr>
- <td><code>InnerInitial</code></td>
- <td>An <code>mpl::list<></code> containing models of
- the <a href="#SimpleState">SimpleState</a> or <a href=
- "#State">State</a> concepts or instantiations of the <code><a href=
- "#ClassTemplateshallow_history">shallow_history</a></code> or
- <code><a href="#ClassTemplatedeep_history">deep_history</a></code>
- class templates. If there is only a single inner initial state that is
- not a template instantiation then it can also be passed directly,
- without wrapping it into an <code>mpl::list<></code>. The
- <code>Context</code> argument passed to the <code><a href=
- "#ClassTemplatesimple_state">simple_state<></a></code> or
- <code><a href="#ClassTemplatestate">state<></a></code> base
- of each state in the list must correspond to the orthogonal region
- it belongs to. That is, the first state in the list must pass
- <code>MostDerived::orthogonal< 0 ></code>, the second
- <code>MostDerived::orthogonal< 1 ></code> and so forth.
- <code>MostDerived::orthogonal< 0 ></code> and
- <code>MostDerived</code> are synonymous</td>
- <td>Defines the inner initial state for each orthogonal
- region. By default, a state does not have inner states</td>
- <td><i><code>unspecified</code></i></td>
- </tr>
- <tr>
- <td><code>historyMode</code></td>
- <td>One of the values defined in the <code><a href=
- "#Enumhistory_mode">history_mode</a></code> enumeration</td>
- <td>Defines whether the state saves shallow, deep or both
- histories upon exit</td>
- <td><code>has_no_history</code></td>
- </tr>
- </table>
- <h3>Class template <code>simple_state</code> synopsis</h3>
- <pre>
- namespace boost
- {
- namespace statechart
- {
- template<
- class MostDerived,
- class Context,
- class InnerInitial = <i>unspecified</i>,
- history_mode historyMode = has_no_history >
- class simple_state : <i>implementation-defined</i>
- {
- public:
- // by default, a state has no reactions
- typedef mpl::list<> reactions;
- // see template parameters
- template< <i>implementation-defined-unsigned-integer-type
- </i> innerOrthogonalPosition >
- struct orthogonal
- {
- // <i>implementation-defined</i>
- };
- typedef typename Context::outermost_context_type
- outermost_context_type;
- outermost_context_type & <a href=
- "#outermost_context">outermost_context</a>();
- const outermost_context_type & <a href=
- "#outermost_contextconst">outermost_context</a>() const;
- template< class OtherContext >
- OtherContext & <a href="#context">context</a>();
- template< class OtherContext >
- const OtherContext & <a href="#contextconst">context</a>() const;
- template< class Target >
- Target <a href="#simple_state::state_cast">state_cast</a>() const;
- template< class Target >
- Target <a href=
- "#simple_state::state_downcast">state_downcast</a>() const;
- // a model of the StateBase concept
- typedef <i>implementation-defined</i> state_base_type;
- // a model of the standard Forward Iterator concept
- typedef <i>implementation-defined</i> state_iterator;
- state_iterator <a href=
- "#simple_state::state_begin">state_begin</a>() const;
- state_iterator <a href=
- "#simple_state::state_end">state_end</a>() const;
- const event_base * <a href="#triggering_event0">triggering_event</a>() const;
- void <a href="#post_event0">post_event</a>(
- const intrusive_ptr< const <a href=
- "#Classevent_base">event_base</a> > & );
- void <a href="#post_event1">post_event</a>( const <a href=
- "#Classevent_base">event_base</a> & );
- <a href="#Classresult">result</a> <a href=
- "#discard_event">discard_event</a>();
- <a href="#Classresult">result</a> <a href=
- "#forward_event">forward_event</a>();
- <a href="#Classresult">result</a> <a href=
- "#defer_event">defer_event</a>();
- template< class DestinationState >
- <a href="#Classresult">result</a> <a href="#transit1">transit</a>();
- template<
- class DestinationState,
- class TransitionContext,
- class Event >
- <a href="#Classresult">result</a> <a href="#transit2">transit</a>(
- void ( TransitionContext::* )( const Event & ),
- const Event & );
- <a href="#Classresult">result</a> <a href=
- "#simple_state::terminate">terminate</a>();
- template<
- class HistoryContext,
- <i>implementation-defined-unsigned-integer-type
- </i> orthogonalPosition >
- void <a href="#clear_shallow_history">clear_shallow_history</a>();
- template<
- class HistoryContext,
- <i>implementation-defined-unsigned-integer-type
- </i> orthogonalPosition >
- void <a href="#clear_deep_history">clear_deep_history</a>();
- static id_type <a href="#static_type">static_type</a>();
- template< class CustomId >
- static const CustomId * <a href=
- "#custom_static_type_ptr">custom_static_type_ptr</a>();
- template< class CustomId >
- static void <a href=
- "#custom_static_type_ptr1">custom_static_type_ptr</a>( const CustomId * );
- // see <a href="#transit1">transit</a>() or <a href=
- "#simple_state::terminate">terminate</a>() effects
- void exit() {}
- protected:
- <a href="#simple_state">simple_state</a>();
- <a href="#simple_statedtor">~simple_state</a>();
- };
- }
- }
- </pre>
- <h3>Class template <code>simple_state</code> constructor and
- destructor</h3>
- <pre>
- <a name="simple_state" id="simple_state">simple_state</a>();
- </pre>
- <p><b>Effects</b>: Constructs a state object</p>
- <pre>
- <a name="simple_statedtor" id="simple_statedtor">~simple_state</a>();
- </pre>
- <p><b>Effects</b>: If the state has deferral reactions of which at least
- one has been triggered during the lifetime of the state then the contents
- of the deferred events queue is moved to the front of the posted events
- queue.</p>
- <h3>Class template <code>simple_state</code> modifier functions</h3>
- <pre>
- void <a name="post_event0" id="post_event0">post_event</a>(
- const intrusive_ptr< const <a href=
- "#Classevent_base">event_base</a> > & pEvt );
- </pre>
- <p><b>Requires</b>: If called from a constructor of a direct or indirect
- subtype then the most-derived type must directly or indirectly derive from
- the <code>state</code> class template<b>.</b> All direct and indirect
- callers must be exception-neutral<b><br>
- Effects</b>: <a href=
- "#outermost_context"><code>outermost_context</code></a><code>().<a href=
- "#post_event2">post_event</a>( pEvt );</code><br>
- <b>Throws</b>: Whatever the above call throws</p>
- <pre>
- void <a name="post_event1" id="post_event1">post_event</a>( const <a href=
- "#Classevent_base">event_base</a> & evt );
- </pre>
- <p><b>Requires</b>: If called from a constructor of a direct or indirect
- subtype then the most-derived type must directly or indirectly derive from
- the <code>state</code> class template<b>.</b> All direct and indirect
- callers must be exception-neutral<b><br>
- Effects</b>: <a href=
- "#outermost_context"><code>outermost_context</code></a><code>().<a href=
- "#post_event3">post_event</a>( evt );</code><br>
- <b>Throws</b>: Whatever the above call throws</p>
- <pre>
- <a href="#Classresult">result</a> <a name="discard_event" id=
- "discard_event">discard_event</a>();
- </pre>
- <p><b>Requires</b>: Must only be called from within <code>react</code>
- member functions, which are called by <code><a href=
- "#ClassTemplatecustom_reaction">custom_reaction<></a></code>
- instantiations. All direct and indirect callers must be
- exception-neutral<br>
- <b>Effects</b>: Instructs the state machine to discard the current event
- and to continue with the processing of the remaining events (see
- <code><a href=
- "#process_event">state_machine<>::process_event</a>()</code> for
- details)<br>
- <b>Returns</b>: A <code><a href="#Classresult">result</a></code> object.
- The user-supplied <code>react</code> member function must return this
- object to its caller</p>
- <pre>
- <a href="#Classresult">result</a> <a name="forward_event" id=
- "forward_event">forward_event</a>();
- </pre>
- <p><b>Requires</b>: Must only be called from within <code>react</code>
- member functions, which are called by <code><a href=
- "#ClassTemplatecustom_reaction">custom_reaction<></a></code>
- instantiations. All direct and indirect callers must be
- exception-neutral<br>
- <b>Effects</b>: Instructs the state machine to forward the current event to
- the next state (see <code><a href=
- "#process_event">state_machine<>::process_event</a>()</code> for
- details)<br>
- <b>Returns</b>: A <code><a href="#Classresult">result</a></code> object.
- The user-supplied <code>react</code> member function must return this
- object to its caller</p>
- <pre>
- <a href="#Classresult">result</a> <a name="defer_event" id=
- "defer_event">defer_event</a>();
- </pre>
- <p><b>Requires</b>: Must only be called from within <code>react</code>
- member functions, which are called by <code><a href=
- "#ClassTemplatecustom_reaction">custom_reaction<></a></code>
- instantiations. All direct and indirect callers must be
- exception-neutral<br>
- <b>Effects</b>: Instructs the state machine to defer the current event and
- to continue with the processing of the remaining events (see <code><a href=
- "#process_event">state_machine<>::process_event</a>()</code> for
- details)<br>
- <b>Returns</b>: A <code><a href="#Classresult">result</a></code> object.
- The user-supplied <code>react</code> member function must return this
- object to its caller<br>
- <b>Throws</b>: Any exceptions propagated from
- <code>Allocator::rebind<>::other::allocate()</code> (the template
- parameter passed to the base class of
- <code>outermost_context_type</code>)</p>
- <pre>
- template< class DestinationState >
- <a href="#Classresult">result</a> <a name="transit1" id=
- "transit1">transit</a>();
- </pre>
- <p><b>Requires</b>: Must only be called from within <code>react</code>
- member functions, which are called by <code><a href=
- "#ClassTemplatecustom_reaction">custom_reaction<></a></code>
- instantiations. All direct and indirect callers must be
- exception-neutral<br>
- <b>Effects</b>:</p>
- <ol>
- <li>Exits all currently active direct and indirect inner states of the
- innermost common context of this state and <code>DestinationState</code>.
- Innermost states are exited first. Other states are exited as soon as all
- their direct and indirect inner states have been exited. The inner states
- of each state are exited according to the number of their orthogonal
- region. The state in the orthogonal region with the highest number is
- always exited first, then the state in the region with the second-highest
- number and so on.<br>
- The process of exiting a state consists of the following steps:
- <ol>
- <li>If there is an exception pending that has not yet been handled
- successfully then only step 5 is executed</li>
- <li>Calls the <code>exit</code> member function (see <a href=
- "#ClassTemplatesimple_state">synopsis</a>) of the most-derived state
- object. If <code>exit()</code> throws then steps 3 and 4 are not
- executed</li>
- <li>If the state has shallow history then shallow history information
- is saved</li>
- <li>If the state is an innermost state then deep history information
- is saved for all direct and indirect outer states that have deep
- history</li>
- <li>The state object is destructed</li>
- </ol>
- </li>
- <li>Enters (constructs) the state that is both a direct inner state of
- the innermost common context and either the <code>DestinationState</code>
- itself or a direct or indirect outer state of
- <code>DestinationState</code></li>
- <li>Enters (constructs) the tree formed by the direct and indirect inner
- states of the previously entered state down to the
- <code>DestinationState</code> and beyond depth first. The inner states of
- each state are entered according to the number of their orthogonal
- region. The state in orthogonal region 0 is always entered first, then
- the state in region 1 and so on</li>
- <li>Instructs the state machine to discard the current event and to
- continue with the processing of the remaining events (see <code><a href=
- "#process_event">state_machine<>::process_event</a>()</code> for
- details)</li>
- </ol>
- <p><b>Returns</b>: A <code><a href="#Classresult">result</a></code> object.
- The user-supplied <code>react</code> member function must return this
- object to its caller<br>
- <b>Throws</b>: Any exceptions propagated from:</p>
- <ul>
- <li><code>Allocator::rebind<>::other::allocate()</code> (the
- template parameter passed to the base class of
- <code>outermost_context_type</code>)</li>
- <li>state constructors</li>
- <li><code>exit</code> member functions</li>
- </ul>
- <p><b>Caution</b>: Inevitably destructs this state before returning to the
- calling <code>react</code> member function, which must therefore not
- attempt to access anything except stack objects before returning to its
- caller</p>
- <pre>
- template<
- class DestinationState,
- class TransitionContext,
- class Event >
- <a href="#Classresult">result</a> <a name="transit2" id=
- "transit2">transit</a>(
- void ( TransitionContext::* )( const Event & ),
- const Event & );
- </pre>
- <p><b>Requires</b>: Must only be called from within <code>react</code>
- member functions, which are called by <code><a href=
- "#ClassTemplatecustom_reaction">custom_reaction<></a></code>
- instantiations. All direct and indirect callers must be
- exception-neutral<br>
- <b>Effects</b>:</p>
- <ol>
- <li>Exits all currently active direct and indirect inner states of the
- innermost common context of this state and <code>DestinationState</code>.
- Innermost states are exited first. Other states are exited as soon as all
- their direct and indirect inner states have been exited. The inner states
- of each state are exited according to the number of their orthogonal
- region. The state in the orthogonal region with the highest number is
- always exited first, then the state in the region with the second-highest
- number and so on.<br>
- The process of exiting a state consists of the following steps:
- <ol>
- <li>If there is an exception pending that has not yet been handled
- successfully then only step 5 is executed</li>
- <li>Calls the <code>exit</code> member function (see <a href=
- "#ClassTemplatesimple_state">synopsis</a>) of the most-derived state
- object. If <code>exit()</code> throws then steps 3 and 4 are not
- executed</li>
- <li>If the state has shallow history then shallow history information
- is saved</li>
- <li>If the state is an innermost state then deep history information
- is saved for all direct and indirect outer states that have deep
- history</li>
- <li>The state object is destructed</li>
- </ol>
- </li>
- <li>Executes the passed transition action, forwarding the passed
- event</li>
- <li>Enters (constructs) the state that is both a direct inner state of
- the innermost common context and either the <code>DestinationState</code>
- itself or a direct or indirect outer state of
- <code>DestinationState</code></li>
- <li>Enters (constructs) the tree formed by the direct and indirect inner
- states of the previously entered state down to the
- <code>DestinationState</code> and beyond depth first. The inner states of
- each state are entered according to the number of their orthogonal
- region. The state in orthogonal region 0 is always entered first, then
- the state in region 1 and so on</li>
- <li>Instructs the state machine to discard the current event and to
- continue with the processing of the remaining events (see <code><a href=
- "#process_event">state_machine<>::process_event</a>()</code> for
- details)</li>
- </ol>
- <p><b>Returns</b>: A <code><a href="#Classresult">result</a></code> object.
- The user-supplied <code>react</code> member function must return this
- object to its caller<br>
- <b>Throws</b>: Any exceptions propagated from:</p>
- <ul>
- <li><code>Allocator::rebind<>::other::allocate()</code> (the
- template parameter passed to the base class of
- <code>outermost_context_type</code>)</li>
- <li>state constructors</li>
- <li><code>exit</code> member functions</li>
- <li>the transition action</li>
- </ul>
- <p><b>Caution</b>: Inevitably destructs this state before returning to the
- calling <code>react</code> member function, which must therefore not
- attempt to access anything except stack objects before returning to its
- caller</p>
- <pre>
- <a href="#Classresult">result</a> <a name="simple_state::terminate" id=
- "simple_state::terminate">terminate</a>();
- </pre>
- <p><b>Requires</b>: Must only be called from within <code>react</code>
- member functions, which are called by <code><a href=
- "#ClassTemplatecustom_reaction">custom_reaction<></a></code>
- instantiations. All direct and indirect callers must be
- exception-neutral<br>
- <b>Effects</b>: Exits this state and all its direct and indirect inner
- states. Innermost states are exited first. Other states are exited as soon
- as all their direct and indirect inner states have been exited. The inner
- states of each state are exited according to the number of their orthogonal
- region. The state in the orthogonal region with the highest number is
- always exited first, then the state in the region with the second-highest
- number and so on.<br>
- The process of exiting a state consists of the following steps:</p>
- <ol>
- <li>If there is an exception pending that has not yet been handled
- successfully then only step 5 is executed</li>
- <li>Calls the <code>exit</code> member function (see <a href=
- "#ClassTemplatesimple_state">synopsis</a>) of the most-derived state
- object. If <code>exit()</code> throws then steps 3 and 4 are not
- executed</li>
- <li>If the state has shallow history then shallow history information is
- saved</li>
- <li>If the state is an innermost state then deep history information is
- saved for all direct and indirect outer states that have deep
- history</li>
- <li>The state object is destructed</li>
- </ol>
- <p>Also instructs the state machine to discard the current event and to
- continue with the processing of the remaining events (see <code><a href=
- "#process_event">state_machine<>::process_event</a>()</code> for
- details)<br>
- <b>Returns</b>: A <code><a href="#Classresult">result</a></code> object.
- The user-supplied <code>react</code> member function must return this
- object to its caller<br>
- <b>Throws</b>: Any exceptions propagated from:</p>
- <ul>
- <li><code>Allocator::rebind<>::other::allocate()</code> (the
- template parameter passed to the base class of
- <code>outermost_context_type</code>, used to allocate space to save
- history)</li>
- <li><code>exit</code> member functions</li>
- </ul>
- <p><b>Note</b>: If this state is the only currently active inner state of
- its direct outer state then the direct outer state is terminated also. The
- same applies recursively for all indirect outer states<br>
- <b>Caution</b>: Inevitably destructs this state before returning to the
- calling <code>react</code> member function, which must therefore not
- attempt to access anything except stack objects before returning to its
- caller</p>
- <pre>
- template<
- class HistoryContext,
- <i>implementation-defined-unsigned-integer-type
- </i> orthogonalPosition >
- void <a name="clear_shallow_history" id=
- "clear_shallow_history">clear_shallow_history</a>();
- </pre>
- <p><b>Requires</b>: If called from a constructor of a direct or indirect
- subtype then the most-derived type must directly or indirectly derive from
- the <code>state</code> class template. The <code>historyMode</code>
- argument passed to the <code><a href=
- "#ClassTemplatesimple_state">simple_state<></a></code> or
- <code><a href="#ClassTemplatestate">state<></a></code> base
- of <code>HistoryContext</code> must be equal to
- <code>has_shallow_history</code> or <code>has_full_history</code><br>
- <b>Effects</b>: Clears the shallow history of the orthogonal region
- specified by <code>orthogonalPosition</code> of the state specified by
- <code>HistoryContext</code><br>
- <b>Throws</b>: Any exceptions propagated from
- <code>Allocator::rebind<>::other::allocate()</code> (the template
- parameter passed to the base class of
- <code>outermost_context_type</code>)</p>
- <pre>
- template<
- class HistoryContext,
- <i>implementation-defined-unsigned-integer-type
- </i> orthogonalPosition >
- void <a name="clear_deep_history" id=
- "clear_deep_history">clear_deep_history</a>();
- </pre>
- <p><b>Requires</b>: If called from a constructor of a direct or indirect
- subtype then the most-derived type must directly or indirectly derive from
- the <code>state</code> class template. The <code>historyMode</code>
- argument passed to the <code><a href=
- "#ClassTemplatesimple_state">simple_state<></a></code> or
- <code><a href="#ClassTemplatestate">state<></a></code> base
- of <code>HistoryContext</code> must be equal to
- <code>has_deep_history</code> or <code>has_full_history</code><br>
- <b>Effects</b>: Clears the deep history of the orthogonal region specified
- by <code>orthogonalPosition</code> of the state specified by
- <code>HistoryContext</code><br>
- <b>Throws</b>: Any exceptions propagated from
- <code>Allocator::rebind<>::other::allocate()</code> (the template
- parameter passed to the base class of
- <code>outermost_context_type</code>)</p>
- <h3>Class template <code>simple_state</code> observer functions</h3>
- <pre>
- outermost_context_type & <a name="outermost_context" id=
- "outermost_context">outermost_context</a>();
- </pre>
- <p><b>Requires</b>: If called from a constructor of a direct or indirect
- subtype then the most-derived type must directly or indirectly derive from
- the <code>state</code> class template. If called from a destructor of a
- direct or indirect subtype then the <code>state_machine<></code> subclass
- portion must still exist<br>
- <b>Returns</b>: A reference to the outermost context, which is always the
- state machine this state belongs to<br></p>
- <pre>
- const outermost_context_type & <a name="outermost_contextconst" id=
- "outermost_contextconst">outermost_context() const</a>;
- </pre>
- <p><b>Requires</b>: If called from a constructor of a direct or indirect
- subtype then the most-derived type must directly or indirectly derive from
- the <code>state</code> class template. If called from a destructor of a
- direct or indirect subtype then the <code>state_machine<></code> subclass
- portion must still exist<br>
- <b>Returns</b>: A reference to the const outermost context, which is always
- the state machine this state belongs to</p>
- <pre>
- template< class OtherContext >
- OtherContext & <a name="context" id="context">context</a>();
- </pre>
- <p><b>Requires</b>: If called from a constructor of a direct or indirect
- subtype then the most-derived type must directly or indirectly derive from
- the <code>state</code> class template. If called from a destructor of a
- direct or indirect subtype with a <code>state_machine<></code> subtype as
- argument then the <code>state_machine<></code> subclass portion must still
- exist<br>
- <b>Returns</b>: A reference to a direct or indirect context or any public base
- type of the contexts</p>
- <pre>
- template< class OtherContext >
- const OtherContext & <a name="contextconst" id=
- "contextconst">context() const</a>;
- </pre>
- <p><b>Requires</b>: If called from a constructor of a direct or indirect
- subtype then the most-derived type must directly or indirectly derive from
- the <code>state</code> class template. If called from a destructor of a
- direct or indirect subtype with a <code>state_machine<></code> subtype as
- argument then the <code>state_machine<></code> subclass portion must still
- exist<br>
- <b>Returns</b>: A reference to a const direct or indirect context or any public
- base type of the contexts</p>
- <pre>
- template< class Target >
- Target <a name="simple_state::state_cast" id=
- "simple_state::state_cast">state_cast</a>() const;
- </pre>
- <p><b>Requires</b>: If called from a constructor of a direct or indirect
- subtype then the most-derived type must directly or indirectly derive from
- the <code>state</code> class template<b><br>
- Returns</b>: Has exactly the same semantics as <code><a href=
- "#state_cast">state_machine<>::state_cast</a><>()</code><br>
- <b>Throws</b>: Has exactly the same semantics as <code><a href=
- "#state_cast">state_machine<>::state_cast</a><>()</code><b><br>
- Note</b>: The result is <b>unspecified</b> if this function is called when
- the machine is <a href=
- "definitions.html#UnstableStateMachine">unstable</a></p>
- <pre>
- template< class Target >
- Target <a name="simple_state::state_downcast" id=
- "simple_state::state_downcast">state_downcast</a>() const;
- </pre>
- <p><b>Requires</b>: If called from a constructor of a direct or indirect
- subtype then the most-derived type must directly or indirectly derive from
- the <code>state</code> class template. Moreover, <code><a href=
- "#state_downcast">state_machine<>::state_downcast</a><>()</code>
- requirements also apply<br>
- <b>Returns</b>: Has exactly the same semantics as <code><a href=
- "#state_downcast">state_machine<>::state_downcast</a><>()</code><br>
- <b>Throws</b>: Has exactly the same semantics as <code><a href=
- "#state_downcast">state_machine<>::state_downcast</a><>()</code><b><br>
- Note</b>: The result is <b>unspecified</b> if this function is called when
- the machine is <a href=
- "definitions.html#UnstableStateMachine">unstable</a></p>
- <pre>
- state_iterator <a name="simple_state::state_begin" id=
- "simple_state::state_begin">state_begin</a>() const;
- </pre>
- <pre>
- state_iterator <a name="simple_state::state_end" id=
- "simple_state::state_end">state_end</a>() const;
- </pre>
- <p><b>Require</b>: If called from a constructor of a direct or indirect
- subtype then the most-derived type must directly or indirectly derive from
- the <code>state</code> class template<b><br>
- Return</b>: Have exactly the same semantics as <code><a href=
- "#state_begin">state_machine<>::state_begin</a>()</code> and
- <code><a href=
- "#state_end">state_machine<>::state_end</a>()</code><br>
- <b>Note</b>: The result is <b>unspecified</b> if these functions are called
- when the machine is <a href=
- "definitions.html#UnstableStateMachine">unstable</a></p>
- <pre>
- const event_base * <a name="triggering_event0" id="triggering_event0">triggering_event</a>();
- </pre>
- <p><b>Returns</b>: Has exactly the same semantics as
- <code><a href="#triggering_event1">state_machine<>::triggering_event</a>()</code></p>
- <h3>Class template <code>simple_state</code> static functions</h3>
- <pre>
- static id_type <a name="static_type" id="static_type">static_type</a>();
- </pre>
- <p><b>Returns</b>: A value unambiguously identifying the type of
- <code>MostDerived</code><br>
- <b>Note</b>: <code>id_type</code> values are comparable with
- <code>operator==()</code> and <code>operator!=()</code>. An unspecified
- collating order can be established with <code>std::less< id_type
- ></code></p>
- <pre>
- template< class CustomId >
- static const CustomId * <a name="custom_static_type_ptr" id=
- "custom_static_type_ptr">custom_static_type_ptr</a>();
- </pre>
- <p><b>Requires</b>: If a custom type identifier has been set then
- <code>CustomId</code> must match the type of the previously set
- pointer<b><br>
- Returns</b>: The pointer to the custom type identifier for
- <code>MostDerived</code> or <code>0</code><br>
- <b>Note</b>: This function is not available if <a href=
- "configuration.html#ApplicationDefinedMacros"><code>BOOST_STATECHART_USE_NATIVE_RTTI</code></a>
- is defined</p>
- <pre>
- template< class CustomId >
- static void <a name="custom_static_type_ptr1" id=
- "custom_static_type_ptr1">custom_static_type_ptr( const CustomId * )</a>;
- </pre>
- <p><b>Effects</b>: Sets the pointer to the custom type identifier for
- <code>MostDerived</code><br>
- <b>Note</b>: This function is not available if <a href=
- "configuration.html#ApplicationDefinedMacros"><code>BOOST_STATECHART_USE_NATIVE_RTTI</code></a>
- is defined</p>
- <h1>Header <boost/statechart/<a name="state.hpp" id=
- "state.hpp">state.hpp</a>></h1>
- <h2><a name="ClassTemplatestate" id="ClassTemplatestate">Class template
- <code>state</code></a></h2>
- <p>This is the base class template for all models of the <a href=
- "#State">State</a> concept. Such models typically need to call at least one
- of the following <code><a href=
- "#ClassTemplatesimple_state">simple_state<></a></code> member
- functions from their constructors:</p>
- <pre>
- void <b>post_event</b>(
- const intrusive_ptr< const event_base > & );
- void <b>post_event</b>( const event_base & );
- template<
- class HistoryContext,
- <i>implementation-defined-unsigned-integer-type
- </i> orthogonalPosition >
- void <b>clear_shallow_history</b>();
- template<
- class HistoryContext,
- <i>implementation-defined-unsigned-integer-type
- </i> orthogonalPosition >
- void <b>clear_deep_history</b>();
- outermost_context_type & <b>outermost_context</b>();
- const outermost_context_type & <b>outermost_context</b>() const;
- template< class OtherContext >
- OtherContext & <b>context</b>();
- template< class OtherContext >
- const OtherContext & <b>context</b>() const;
- template< class Target >
- Target <b>state_cast</b>() const;
- template< class Target >
- Target <b>state_downcast</b>() const;
- state_iterator <b>state_begin</b>() const;
- state_iterator <b>state_end</b>() const;
- const event_base * <b>triggering_event</b>() const;
- </pre>
- <p>States that do not need to call any of these member functions from their
- constructors should rather derive from the <code><a href=
- "#ClassTemplatesimple_state">simple_state</a></code> class template, what
- saves the implementation of the forwarding constructor.</p>
- <h3>Class template <code>state</code> synopsis</h3>
- <pre>
- namespace boost
- {
- namespace statechart
- {
- template<
- class MostDerived,
- class Context,
- class InnerInitial = <i>unspecified</i>,
- history_mode historyMode = has_no_history >
- class state : public simple_state<
- MostDerived, Context, InnerInitial, historyMode >
- {
- protected:
- struct my_context
- {
- // <i>implementation-defined</i>
- };
- typedef state my_base;
- state( my_context ctx );
- ~state();
- };
- }
- }
- </pre>
- <p>Direct and indirect subtypes of <code>state<></code> must provide
- a constructor with the same signature as the <code>state<></code>
- constructor, forwarding the context parameter.</p>
- <h1>Header <boost/statechart/<a name="shallow_history.hpp" id=
- "shallow_history.hpp">shallow_history.hpp</a>></h1>
- <h2><a name="ClassTemplateshallow_history" id=
- "ClassTemplateshallow_history">Class template
- <code>shallow_history</code></a></h2>
- <p>This class template is used to specify a shallow history transition
- target or a shallow history inner initial state.</p>
- <h3>Class template <code>shallow_history</code> parameters</h3>
- <table border="3" cellpadding="2" width="100%" summary=
- "shallow_history parameters">
- <tr>
- <td><b>Template parameter</b></td>
- <td><b>Requirements</b></td>
- <td><b>Semantics</b></td>
- </tr>
- <tr>
- <td><code>DefaultState</code></td>
- <td>A model of the <a href="#SimpleState">SimpleState</a>
- or <a href="#State">State</a> concepts. The type passed as
- <code>Context</code> argument to the <code><a href=
- "#ClassTemplatesimple_state">simple_state<></a></code> or
- <code><a href="#ClassTemplatestate">state<></a></code> base
- of <code>DefaultState</code> must itself pass
- <code>has_shallow_history</code> or <code>has_full_history</code> as
- <code>historyMode</code> argument to its <code><a href=
- "#ClassTemplatesimple_state">simple_state<></a></code> or
- <code><a href="#ClassTemplatestate">state<></a></code> base</td>
- <td>The state that is entered if shallow history is not available</td>
- </tr>
- </table>
- <h3>Class template <code>shallow_history</code> synopsis</h3>
- <pre>
- namespace boost
- {
- namespace statechart
- {
- template< class DefaultState >
- class shallow_history
- {
- // <i>implementation-defined</i>
- };
- }
- }
- </pre>
- <h1>Header <boost/statechart/<a name="deep_history.hpp" id=
- "deep_history.hpp">deep_history.hpp</a>></h1>
- <h2><a name="ClassTemplatedeep_history" id=
- "ClassTemplatedeep_history">Class template
- <code>deep_history</code></a></h2>
- <p>This class template is used to specify a deep history transition target
- or a deep history inner initial state. The current deep history
- implementation has some <a href=
- "rationale.html#Limitations">limitations</a>.</p>
- <h3>Class template <code>deep_history</code> parameters</h3>
- <table border="3" cellpadding="2" width="100%" summary=
- "deep_history parameters">
- <tr>
- <td><b>Template parameter</b></td>
- <td><b>Requirements</b></td>
- <td><b>Semantics</b></td>
- </tr>
- <tr>
- <td><code>DefaultState</code></td>
- <td>A model of the <a href="#SimpleState">SimpleState</a>
- or <a href="#State">State</a> concepts. The type passed as
- <code>Context</code> argument to the <code><a href=
- "#ClassTemplatesimple_state">simple_state<></a></code> or
- <code><a href="#ClassTemplatestate">state<></a></code> base
- of <code>DefaultState</code> must itself pass
- <code>has_deep_history</code> or <code>has_full_history</code> as
- <code>historyMode</code> argument to its <code><a href=
- "#ClassTemplatesimple_state">simple_state<></a></code> or
- <code><a href="#ClassTemplatestate">state<></a></code> base</td>
- <td>The state that is entered if deep history is not available</td>
- </tr>
- </table>
- <h3>Class template <code>deep_history</code> synopsis</h3>
- <pre>
- namespace boost
- {
- namespace statechart
- {
- template< class DefaultState >
- class deep_history
- {
- // <i>implementation-defined</i>
- };
- }
- }
- </pre>
- <h1>Header <boost/statechart/<a name="event_base.hpp" id=
- "event_base.hpp">event_base.hpp</a>></h1>
- <h2><a name="Classevent_base" id="Classevent_base">Class
- <code>event_base</code></a></h2>
- <p>This is the common base of all events.</p>
- <h3>Class <code>event_base</code> synopsis</h3>
- <pre>
- namespace boost
- {
- namespace statechart
- {
- class event_base
- {
- public:
- intrusive_ptr< const event_base >
- <a href="#intrusive_from_this">intrusive_from_this</a>() const;
- typedef <i>implementation-defined</i> id_type;
- id_type <a href="#event_base::dynamic_type">dynamic_type</a>() const;
- template< typename CustomId >
- const CustomId * <a href=
- "#event_base::custom_dynamic_type_ptr">custom_dynamic_type_ptr</a>() const;
-
- protected:
- <a href="#event_base">event_base</a>( <i>unspecified-parameter </i>);
- virtual <a href="#event_basedtor">~event_base</a>();
- };
- }
- }
- </pre>
- <h3>Class <code>event_base</code> constructor and destructor</h3>
- <pre>
- <a name="event_base" id=
- "event_base">event_base</a>( <i>unspecified-parameter </i>);
- </pre>
- <p><b>Effects</b>: Constructs the common base portion of an event</p>
- <pre>
- virtual <a name="event_basedtor" id="event_basedtor">~event_base</a>();
- </pre>
- <p><b>Effects</b>: Destructs the common base portion of an event</p>
- <h3>Class <code>event_base</code> observer functions</h3>
- <pre>
- intrusive_ptr< const event_base > <a name="intrusive_from_this" id=
- "intrusive_from_this">intrusive_from_this</a>() const;
- </pre>
- <p><b>Returns</b>: Another <code>intrusive_ptr< const event_base
- ></code> referencing <code>this</code> <b>if</b> <code>this</code> is
- already referenced by an <code>intrusive_ptr<></code>. Otherwise,
- returns an <code>intrusive_ptr< const event_base ></code> referencing
- a newly created copy of the most-derived object</p>
- <pre>
- id_type <a name="event_base::dynamic_type" id=
- "event_base::dynamic_type">dynamic_type</a>() const;
- </pre>
- <p><b>Returns</b>: A value unambiguously identifying the most-derived
- type<br>
- <b>Note</b>: <code>id_type</code> values are comparable with
- <code>operator==()</code> and <code>operator!=()</code>. An unspecified
- collating order can be established with <code>std::less< id_type
- ></code>. In contrast to <code>typeid( cs )</code>, this function is
- available even on platforms that do not support C++ RTTI (or have been
- configured to not support it)</p>
- <pre>
- template< typename CustomId >
- const CustomId * <a name="event_base::custom_dynamic_type_ptr" id=
- "event_base::custom_dynamic_type_ptr">custom_dynamic_type_ptr</a>() const;
- </pre>
- <p><b>Requires</b>: If a custom type identifier has been set then
- <code>CustomId</code> must match the type of the previously set
- pointer<b><br>
- Returns</b>: A pointer to the custom type identifier or <code>0</code><br>
- <b>Note</b>: This function is not available if <a href=
- "configuration.html#ApplicationDefinedMacros"><code>BOOST_STATECHART_USE_NATIVE_RTTI</code></a>
- is defined</p>
- <h1>Header <boost/statechart/<a name="event.hpp" id=
- "event.hpp">event.hpp</a>></h1>
- <h2><a name="ClassTemplateevent" id="ClassTemplateevent">Class template
- <code>event</code></a></h2>
- <p>This is the base class template of all events.</p>
- <h3>Class template <code>event</code> parameters</h3>
- <table border="3" cellpadding="2" width="100%" summary="event parameters">
- <tr>
- <td><b>Template parameter</b></td>
- <td><b>Requirements</b></td>
- <td><b>Semantics</b></td>
- <td><b>Default</b></td>
- </tr>
- <tr>
- <td><code>MostDerived</code></td>
- <td>The most-derived subtype of this class template</td>
- <td> </td>
- <td> </td>
- </tr>
- <tr>
- <td><code>Allocator</code></td>
- <td>A model of the standard Allocator concept</td>
- <td><code>Allocator::rebind< MostDerived
- >::other</code> is used to allocate and deallocate all event subtype
- objects of dynamic storage duration, see <code><a href=
- "#event::operatornew">operator new</a></code></td>
- <td><code>std::allocator< void ></code></td>
- </tr>
- </table>
- <h3>Class template <code>event</code> synopsis</h3>
- <pre>
- namespace boost
- {
- namespace statechart
- {
- template< class MostDerived, class Allocator = std::allocator< void > >
- class event : <i>implementation-defined</i>
- {
- public:
- static void * <a href=
- "#event::operatornew">operator new</a>( std::size_t size );
- static void * <a href=
- "#event::operatornew2">operator new</a>( std::size_t size, void * p );
- static void <a href=
- "#event::operatordelete">operator delete</a>( void * pEvent );
- static id_type <a href="#event::static_type">static_type</a>();
- template< class CustomId >
- static const CustomId * <a href=
- "#event::custom_static_type_ptr">custom_static_type_ptr</a>();
- template< class CustomId >
- static void <a href=
- "#event::custom_static_type_ptr1">custom_static_type_ptr</a>( const CustomId * );
- protected:
- <a href="#event::event">event</a>();
- virtual <a href="#eventdtor">~event</a>();
- };
- }
- }
- </pre>
- <h3>Class template <code>event</code> constructor and destructor</h3>
- <pre>
- <a name="event::event" id="event::event">event</a>();
- </pre>
- <p><b>Effects</b>: Constructs an event</p>
- <pre>
- virtual <a name="eventdtor" id="eventdtor">~event</a>();
- </pre>
- <p><b>Effects</b>: Destructs an event</p>
- <h3>Class template <code>event</code> static functions</h3>
- <pre>
- static void * <a name="event::operatornew" id=
- "event::operatornew">operator new</a>( std::size_t size );
- </pre>
- <p><b>Effects</b>: <code>Allocator::rebind< MostDerived
- >::other().allocate( 1, static_cast< MostDerived * >( 0 )
- );</code><br>
- <b>Returns</b>: The return value of the above call<br>
- <b>Throws</b>: Whatever the above call throws</p>
- <pre>
- static void * <a name="event::operatornew2" id=
- "event::operatornew2">operator new</a>( std::size_t size, void * p );
- </pre>
- <p><b>Effects</b>: None<br>
- <b>Returns</b>: <code>p</code></p>
- <pre>
- static void <a name="event::operatordelete" id=
- "event::operatordelete">operator delete</a>( void * pEvent );
- </pre>
- <p><b>Effects</b>: <code>Allocator::rebind< MostDerived
- >::other().deallocate( static_cast< MostDerived * >( pEvent ), 1
- );</code></p>
- <pre>
- static id_type <a name="event::static_type" id=
- "event::static_type">static_type</a>();
- </pre>
- <p><b>Returns</b>: A value unambiguously identifying the type of
- <code>MostDerived</code><br>
- <b>Note</b>: <code>id_type</code> values are comparable with
- <code>operator==()</code> and <code>operator!=()</code>. An unspecified
- collating order can be established with <code>std::less< id_type
- ></code></p>
- <pre>
- template< class CustomId >
- static const CustomId * <a name="event::custom_static_type_ptr" id=
- "event::custom_static_type_ptr">custom_static_type_ptr</a>();
- </pre>
- <p><b>Requires</b>: If a custom type identifier has been set then
- <code>CustomId</code> must match the type of the previously set
- pointer<b><br>
- Returns</b>: The pointer to the custom type identifier for
- <code>MostDerived</code> or <code>0</code><br>
- <b>Note</b>: This function is not available if <a href=
- "configuration.html#ApplicationDefinedMacros"><code>BOOST_STATECHART_USE_NATIVE_RTTI</code></a>
- is defined</p>
- <pre>
- template< class CustomId >
- static void <a name="event::custom_static_type_ptr1" id=
- "event::custom_static_type_ptr1">custom_static_type_ptr( const CustomId * )</a>;
- </pre>
- <p><b>Effects</b>: Sets the pointer to the custom type identifier for
- <code>MostDerived</code><br>
- <b>Note</b>: This function is not available if <a href=
- "configuration.html#ApplicationDefinedMacros"><code>BOOST_STATECHART_USE_NATIVE_RTTI</code></a>
- is defined</p>
- <h1>Header <boost/statechart/<a name="transition.hpp" id=
- "transition.hpp">transition.hpp</a>></h1>
- <h2><a name="ClassTemplatetransition" id="ClassTemplatetransition">Class
- template <code>transition</code></a></h2>
- <p>This class template is used to specify a transition reaction.
- Instantiations of this template can appear in the <code>reactions</code>
- member <code>typedef</code> in models of the <a href=
- "#SimpleState">SimpleState</a> and <a href="#State">State</a> concepts.</p>
- <h3>Class template <code>transition</code> parameters</h3>
- <table border="3" cellpadding="2" width="100%" summary=
- "transition parameters">
- <tr>
- <td><b>Template parameter</b></td>
- <td><b>Requirements</b></td>
- <td><b>Semantics</b></td>
- <td><b>Default</b></td>
- </tr>
- <tr>
- <td><code>Event</code></td>
- <td>A model of the <a href="#Event">Event</a> concept or
- the class <code><a href="#Classevent_base">event_base</a></code></td>
- <td>The event triggering the transition. If <code><a href=
- "#Classevent_base">event_base</a></code> is specified, the transition
- is triggered by all models of the <a href="#Event">Event</a>
- concept</td>
- <td> </td>
- </tr>
- <tr>
- <td><code>Destination</code></td>
- <td>A model of the <a href="#SimpleState">SimpleState</a>
- or <a href="#State">State</a> concepts, any of their public base types or an instantiation of the
- <code><a href=
- "#ClassTemplateshallow_history">shallow_history</a></code> or
- <code><a href="#ClassTemplatedeep_history">deep_history</a></code>
- class templates. The source state (the state for which this transition
- is defined) and <code>Destination</code> must have a common direct or
- indirect context</td>
- <td>The destination state to make a transition to</td>
- <td> </td>
- </tr>
- <tr>
- <td><code>TransitionContext</code></td>
- <td>A common context of the source and
- <code>Destination</code> state</td>
- <td>The state of which the transition action is a
- member</td>
- <td><i><code>unspecified</code></i></td>
- </tr>
- <tr>
- <td><code>pTransitionAction</code></td>
- <td>A pointer to a member function of
- <code>TransitionContext</code>. The member function must accept a
- <code>const Event &</code> parameter and return
- <code>void</code></td>
- <td>The transition action that is executed during the
- transition. By default no transition action is executed</td>
- <td><i><code>unspecified</code></i></td>
- </tr>
- </table>
- <h3>Class template <code>transition</code> synopsis</h3>
- <pre>
- namespace boost
- {
- namespace statechart
- {
- template<
- class Event,
- class Destination,
- class TransitionContext = <i>unspecified</i>,
- void ( TransitionContext::*pTransitionAction )(
- const Event & ) = <i>unspecified</i> >
- class transition
- {
- // <i>implementation-defined</i>
- };
- }
- }
- </pre>
- <h3>Class template <code>transition</code> semantics</h3>
- <p>When executed, one of the following calls to a member function of the
- state for which the reaction was defined is made:</p>
- <ul>
- <li><code><a href="#transit1">transit< Destination >()</a></code>,
- if no transition action was specified</li>
- <li><code><a href="#transit2">transit< Destination >(
- pTransitionAction, <i>currentEvent</i> )</a></code>, if a transition
- action was specified</li>
- </ul>
- <h1>Header <boost/statechart/<a name="in_state_reaction.hpp" id=
- "in_state_reaction.hpp">in_state_reaction.hpp</a>></h1>
- <h2><a name="ClassTemplatein_state_reaction" id=
- "ClassTemplatein_state_reaction">Class template
- <code>in_state_reaction</code></a></h2>
- <p>This class template is used to specify an in-state reaction.
- Instantiations of this template can appear in the <code>reactions</code>
- member <code>typedef</code> in models of the <a href=
- "#SimpleState">SimpleState</a> and <a href="#State">State</a> concepts.</p>
- <h3>Class template <code>in_state_reaction</code> parameters</h3>
- <table border="3" cellpadding="2" width="100%" summary=
- "in_state_reaction parameters">
- <tr>
- <td><b>Template parameter</b></td>
- <td><b>Requirements</b></td>
- <td><b>Semantics</b></td>
- <td><b>Default</b></td>
- </tr>
- <tr>
- <td><code>Event</code></td>
- <td>A model of the <a href="#Event">Event</a> concept or
- the class <code><a href="#Classevent_base">event_base</a></code></td>
- <td>The event triggering the in-state reaction. If
- <code><a href="#Classevent_base">event_base</a></code> is specified,
- the in-state reaction is triggered by all models of the <a href=
- "#Event">Event</a> concept</td>
- <td> </td>
- </tr>
- <tr>
- <td><code>ReactionContext</code></td>
- <td>Either the state defining the in-state reaction itself, one of its direct or indirect contexts
- or any of their public base types</td>
- <td>The state of which the action is a member</td>
- <td><i><code>unspecified</code></i></td>
- </tr>
- <tr>
- <td><code>pAction</code></td>
- <td>A pointer to a member function of
- <code>ReactionContext</code>. The member function must accept a
- <code>const Event &</code> parameter and return
- <code>void</code></td>
- <td>The action that is executed during the in-state
- reaction</td>
- <td><i><code>unspecified</code></i></td>
- </tr>
- </table>
- <h3>Class template <code>in_state_reaction</code> synopsis</h3>
- <pre>
- namespace boost
- {
- namespace statechart
- {
- template<
- class Event,
- class ReactionContext = <i>unspecified</i>,
- void ( ReactionContext::*pAction )(
- const Event & ) = <i>unspecified</i> >
- class in_state_reaction
- {
- // <i>implementation-defined</i>
- };
- }
- }
- </pre>
- <h3>Class template <code>in_state_reaction</code> semantics</h3>
- <p>When executed then the following happens:</p>
- <ol>
- <li>If an action was specified, <code>pAction</code> is called, passing
- the triggering event as the only argument</li>
- <li>A call is made to the <code><a href="#discard_event">discard_event</a>
- </code> member function of the state for which the reaction was defined
- </li>
- </ol>
- <h1>Header <boost/statechart/<a name="termination.hpp" id=
- "termination.hpp">termination.hpp</a>></h1>
- <h2><a name="ClassTemplatetermination" id="ClassTemplatetermination">Class
- template <code>termination</code></a></h2>
- <p>This class template is used to specify a termination reaction.
- Instantiations of this template can appear in the <code>reactions</code>
- member <code>typedef</code> in models of the <a href=
- "#SimpleState">SimpleState</a> and <a href="#State">State</a> concepts.</p>
- <h3>Class template <code>termination</code> parameters</h3>
- <table border="3" cellpadding="2" width="100%" summary=
- "termination parameters">
- <tr>
- <td><b>Template parameter</b></td>
- <td><b>Requirements</b></td>
- <td><b>Semantics</b></td>
- </tr>
- <tr>
- <td><code>Event</code></td>
- <td>A model of the <a href="#Event">Event</a> concept or
- the class <code><a href="#Classevent_base">event_base</a></code></td>
- <td>The event triggering the termination. If <code><a href=
- "#Classevent_base">event_base</a></code> is specified, the termination
- is triggered by all models of the <a href="#Event">Event</a>
- concept</td>
- </tr>
- </table>
- <h3>Class template <code>termination</code> synopsis</h3>
- <pre>
- namespace boost
- {
- namespace statechart
- {
- template< class Event >
- class termination
- {
- // <i>implementation-defined</i>
- };
- }
- }
- </pre>
- <h3>Class template <code>termination</code> semantics</h3>
- <p>When executed, a call is made to the <code><a href=
- "#simple_state::terminate">terminate</a></code> member function of the
- state for which the reaction was defined.</p>
- <h1>Header <boost/statechart/<a name="deferral.hpp" id=
- "deferral.hpp">deferral.hpp</a>></h1>
- <h2><a name="ClassTemplatedeferral" id="ClassTemplatedeferral">Class
- template <code>deferral</code></a></h2>
- <p>This class template is used to specify a deferral reaction.
- Instantiations of this template can appear in the <code>reactions</code>
- member <code>typedef</code> in models of the <a href=
- "#SimpleState">SimpleState</a> and <a href="#State">State</a> concepts.</p>
- <h3>Class template <code>deferral</code> parameters</h3>
- <table border="3" cellpadding="2" width="100%" summary=
- "deferral parameters">
- <tr>
- <td><b>Template parameter</b></td>
- <td><b>Requirements</b></td>
- <td><b>Semantics</b></td>
- </tr>
- <tr>
- <td><code>Event</code></td>
- <td>A model of the <a href="#Event">Event</a> concept or
- the class <code><a href="#Classevent_base">event_base</a></code></td>
- <td>The event triggering the deferral. If <code><a href=
- "#Classevent_base">event_base</a></code> is specified, the deferral is
- triggered by all models of the <a href="#Event">Event</a> concept</td>
- </tr>
- </table>
- <h3>Class template <code>deferral</code> synopsis</h3>
- <pre>
- namespace boost
- {
- namespace statechart
- {
- template< class Event >
- class deferral
- {
- // <i>implementation-defined</i>
- };
- }
- }
- </pre>
- <h3>Class template <code>deferral</code> semantics</h3>
- <p>When executed, a call is made to the <a href=
- "#defer_event"><code>defer_event</code></a> member function of the state
- for which the reaction was defined.</p>
- <h1>Header <boost/statechart/<a name="custom_reaction.hpp" id=
- "custom_reaction.hpp">custom_reaction.hpp</a>></h1>
- <h2><a name="ClassTemplatecustom_reaction" id=
- "ClassTemplatecustom_reaction">Class template
- <code>custom_reaction</code></a></h2>
- <p>This class template is used to specify a custom reaction. Instantiations
- of this template can appear in the <code>reactions</code> member
- <code>typedef</code> in models of the <a href=
- "#SimpleState">SimpleState</a> and <a href="#State">State</a> concepts.</p>
- <h3>Class template <code>custom_reaction</code> parameters</h3>
- <table border="3" cellpadding="2" width="100%" summary=
- "custom_reaction parameters">
- <tr>
- <td><b>Template parameter</b></td>
- <td><b>Requirements</b></td>
- <td><b>Semantics</b></td>
- </tr>
- <tr>
- <td><code>Event</code></td>
- <td>A model of the <a href="#Event">Event</a> concept or
- the class <code><a href="#Classevent_base">event_base</a></code></td>
- <td>The event triggering the custom reaction. If
- <code><a href="#Classevent_base">event_base</a></code> is specified,
- the custom reaction is triggered by all models of the <a href=
- "#Event">Event</a> concept</td>
- </tr>
- </table>
- <h3>Class template <code>custom_reaction</code> synopsis</h3>
- <pre>
- namespace boost
- {
- namespace statechart
- {
- template< class Event >
- class custom_reaction
- {
- // <i>implementation-defined</i>
- };
- }
- }
- </pre>
- <h3>Class template <code>custom_reaction</code> semantics</h3>
- <p>When executed, a call is made to the user-supplied <code>react</code>
- member function of the state for which the reaction was defined. The
- <code>react</code> member function must have the following signature:</p>
- <pre>
- <a href="#Classresult">result</a> react( const Event & );
- </pre>
- <p>and must call exactly one of the following reaction functions and return
- the obtained <code><a href="#Classresult">result</a></code> object:</p>
- <pre>
- <a href="#Classresult">result</a> <a href=
- "#discard_event">discard_event</a>();
- <a href="#Classresult">result</a> <a href=
- "#forward_event">forward_event</a>();
- <a href="#Classresult">result</a> <a href="#defer_event">defer_event</a>();
- template< class DestinationState >
- <a href="#Classresult">result</a> <a href="#transit1">transit</a>();
- template<
- class DestinationState,
- class TransitionContext,
- class Event >
- <a href="#Classresult">result</a> <a href="#transit2">transit</a>(
- void ( TransitionContext::* )( const Event & ),
- const Event & );
- <a href="#Classresult">result</a> <a href=
- "#simple_state::terminate">terminate</a>();
- </pre>
- <h1>Header <boost/statechart/<a name="result.hpp" id=
- "result.hpp">result.hpp</a>></h1>
- <h2><a name="Classresult" id="Classresult">Class
- <code>result</code></a></h2>
- <p>Defines the nature of the reaction taken in a user-supplied
- <code>react</code> member function (called when a <code><a href=
- "#ClassTemplatecustom_reaction">custom_reaction</a></code> is executed).
- Objects of this type are always obtained by calling one of the reaction
- functions and must be returned from the <code>react</code> member function
- immediately.</p>
- <pre>
- namespace boost
- {
- namespace statechart
- {
- class result
- {
- public:
- <a href="#result0">result</a>( const result & other );
- <a href="#resultdtor">~result</a>();
- private:
- // Result objects are not assignable
- result & operator=( const result & other );
- };
- }
- }
- </pre>
- <h3>Class <code>result</code> constructor and destructor</h3>
- <pre>
- <a name="result0" id="result0">result</a>( const result & other );
- </pre>
- <p><b>Requires</b>: <code>other</code> is <b>not</b> consumed<br>
- <b>Effects</b>: Copy-constructs a new <code>result</code> object and marks
- <code>other</code> as consumed. That is, <code>result</code> has
- destructive copy semantics</p>
- <pre>
- <a name="resultdtor" id="resultdtor">~result</a>();
- </pre>
- <p><b>Requires</b>: <code>this</code> is marked as consumed<br>
- <b>Effects</b>: Destructs the result object</p>
- <hr>
- <p><a href="http://validator.w3.org/check?uri=referer"><img border="0" src=
- "../../../doc/images/valid-html401.png" alt="Valid HTML 4.01 Transitional"
- height="31" width="88"></a></p>
- <p>Revised 06 November, 2010</p>
- <p><i>Copyright © 2003-2010 <a href="contact.html">Andreas Huber
- Dönni</a></i></p>
- <p><i>Distributed under the Boost Software License, Version 1.0. (See
- accompanying file <a href="../../../LICENSE_1_0.txt">LICENSE_1_0.txt</a> or
- copy at <a href=
- "http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</a>)</i></p>
- </body>
- </html>
|