Our story will be placed in a little universe. This little universe will
consist of a heaven, an earth and an underworld. The earth in the story
- isn't round like ours. It's a very small flat-earth, acting as a platform,
- floating above the underworld. On top of the earth are a set of pubs,
- arranged on different terraces.
+ isn't round like ours. It's a very small flat platform, floating above the
+ underworld. On top of the earth are a set of pubs, arranged on different
+ terraces. Each terrace has one pub.
@@ -90,10 +78,6 @@ statechart ideas you need to know.
less space have a more specialized aesthetic.
-
- Now let's add some characters and a bit more detail to the story.
-
-
On every terrace, there will be two bouncers, a greeter and zero or more
bartenders. There will only be one set of stairs that can be used to enter or
@@ -113,7 +97,7 @@ statechart ideas you need to know.
:target: _static/md_terraced_pubs.pdf
:align: center
-.. admonition:: hint
+.. admonition:: translation
Each pub is a state in a statemachine. You would program these states as
functions that take two arguments, a reference to an active object and an event.
@@ -133,12 +117,12 @@ statechart ideas you need to know.
- Now let's add some supernatural beings: three gods and a spirit.
+ Now let's add some supernatural beings: three "gods" and a "spirit".
- The heaven will have one goddess Eve, "the goddess of law and order" and
- the underworld will be ruled by Theo, the solipsist. The earth
+ The heaven will have one goddess, Eve, "the goddess of law and order" and the
+ underworld will be ruled by Theo, "the solipsist." The earth
will have a lazy god named Spike, "the source" who happens to be the only guy
who can drink in the whole universe. Spike will have a companion spirit,
named Tara "the explorer."
@@ -155,7 +139,7 @@ statechart ideas you need to know.
:target: _static/md_terraced_gods.pdf
:align: center
-.. admonition:: hint
+.. admonition:: translation
Eve represents the "event processor", or the algorithm that sends the state
functions different events.
@@ -179,9 +163,10 @@ statechart ideas you need to know.
- Let's put our little universe into a small multiverse. Each universe will have
- it's own heaven and underworld, gods, people and explorer spirit, but its
- terraced architecture of pubs, can be shared across all connected universes.
+ Let's put our little universe into a small multiverse. Each universe will
+ have it's own heaven and underworld, gods and explorer spirit, but its
+ terraced architecture of pubs, and people (bartenders, greeters) can be
+ shared across all connected universes.
@@ -194,16 +179,17 @@ statechart ideas you need to know.
:target: _static/md_multiverse.pdf
:align: center
-.. admonition:: hint
+.. admonition:: translation
- Anytime a statechart references a callback, that callback will change the
- internal variable state of the active object in its first argument -- the
- state callback functions do not have their own memory.
+ Anytime a statechart references a callback (a pub), that callback will change
+ the internal variable state of the ActiveObject that is passed in as its first
+ argument -- the state callback functions themselves, do not have their own
+ memory.
Since the callback functions don't keep any information, they can be called by
- many different active objects, in that active object's thread, and behave as
- expected; there are no side effects. In this way, many different active
- objects can use the same set of state callback functions.
+ many different ActiveObjects (in that ActiveObjects's thread) and behave as
+ expected; there are no side effects. In this way, many different ActiveObject
+ can use the same set of state callback functions.
.. raw:: html
@@ -223,19 +209,18 @@ statechart ideas you need to know.
:target: _static/md_eve.pdf
:align: center
-.. admonition:: hint
+.. admonition:: translation
- Eve is the "event processor". The if-elif clauses, represented by the people
- in the story, exist within each of the state functions. These if-elif clauses
- only become active when the event processor calls its function with an
- internal event, represented by one of the people in the story.
+ The if-elif clauses, represented by the people in the story, exist within each
+ of the state functions. These if-elif clauses only become active when the
+ event processor (Eve) calls its function with an internal event, represented
+ by one of the people in the story.
Tara, the "target state" is used by the event processor when it is searching a
- statemachine to see which state handles an external event.
-
- Since the event processor calls the function and change's its target state
- while it is searching through a statemachine, we say that Eve rules over the
- people and Tara the "explorer spirit".
+ statemachine to see which state handles an external event. Since the event
+ processor calls the function and change's its target state while it is
+ searching through a statemachine, we say that Eve rules over the people and
+ Tara the "explorer spirit".
.. raw:: html
@@ -262,9 +247,9 @@ statechart ideas you need to know.
:target: _static/md_theo.pdf
:align: center
-.. admonition:: hint
+.. admonition:: translation
- Theo represents a "thread" pending on a queue. The activeobject's ``post_fifo``
+ Theo represents a "thread" pending on a queue. The ActiveObject's ``post_fifo``
and ``post_lifo`` methods allow an application developer to put events into
this queue. When the thread sees that a queue has an item, it will wake up,
and drive the event processor, which in turn, will call the functions
@@ -286,39 +271,37 @@ statechart ideas you need to know.
:target: _static/md_events.pdf
:align: center
-.. admonition:: hint
+.. admonition:: translation
An event has a name, called a signal, which can be a user defined name or it
- can be a predefined name. An event with a user defined signal name is called
- an external event. An event with a predefined name is called an internal
- event.
+ can be a predefined name (ENTRY_SIGNAL, EXIT_SIGNAL, INIT_SIGNAL, etc...). An
+ event with a user defined signal name is called an external event. An event
+ with a predefined name is called an internal event.
The whole point of naming an event with a signal is so that a state function
can use an if-elif clause to "catch" the event when it is given to that
function. When such an event is caught, your code is run.
- An event can have an optional payload.
-
.. raw:: html
- When an "event" comes through the portal, Theo will pick it up, marvel at it
+ When an "event" comes through the portal, Theo will pick it up, marvel at it,
then in a reverent gesture, pass it to Eve. They both become excited, maybe
- even a little nervous, because they know there universe is going to change; it
+ even a little nervous, because they know their universe is going to change; it
will react to the event.
- Theo encourages Eve to fly back up into the sky and to "follow the laws." Then
- he will watch as she gives her minions their marching orders. Only after all of
- the activity stops, will he focus his attention back on the portal.
+ Theo encourages Eve to "follow the laws." Then he will watch as she gives her
+ minions their marching orders. Only after all of the activity stops, will he
+ focus his attention back on the portal.
Feeling oddly refreshed and encouraged by Theo, Eve looks around the map until
- she see's Spike from her high vantage point. Spike being the god of the earth,
+ she sees Spike from her high vantage point. Spike being the god of the earth,
is easy to see and Eve knows that her underling-spirit Tara, "the explorer", is
always near him.
@@ -353,19 +336,22 @@ statechart ideas you need to know.
- If there is no bartender to talk to on her terrace, she will go to it's exit
- staircase and descend to the next terrace. Being a spirit, she is hard to see
- and the bouncers and greeters leave her alone when she is by herself.
+ If there is no bartender to talk to on her terrace, she will go to its exit
+ staircase and descends to the next terrace (Tara only ascends when given
+ instructions to do so). Being a spirit, she is hard to see and the bouncers
+ and greeters leave her alone when she is by herself.
-.. admonition:: hint
+.. admonition:: translation
- The terraces are just callback functions containing if-elif-else clauses. The
- else clause of each callback function provides information about what other
- callback function should be called if it doesn't know what to do with a given
- event. This other function, can be thought of as a lower terrace.
+ The terraces are just callback functions containing if-elif-else clauses (pub
+ == terrace == state == callback).
+
+ The else clause of each callback function provides information about what
+ other callback function should be called if it doesn't know what to do with a
+ given event. This other function, can be thought of as a lower terrace.
The bartenders are named arrows on the HSM diagram.
@@ -388,7 +374,7 @@ statechart ideas you need to know.
:target: _static/md_bartenders_on_the_hsm_oblivion.pdf
:align: center
-.. admonition:: hint
+.. admonition:: translation
Here we are starting to explore a statechart's dynamics. If your statemachine
doesn't handle an event in any of it's callback functions, the event will be
@@ -415,7 +401,7 @@ statechart ideas you need to know.
:target: _static/md_bartenders_on_the_hsm_hook.pdf
:align: center
-.. admonition:: hint
+.. admonition:: translation
Tara, the "target state" is used by the event processor to find which state
callback function knows how to handle a given event. In the above picture we
@@ -456,7 +442,7 @@ statechart ideas you need to know.
where Tara has gotten her next clue. He knows that she will want to talk to him
about it. As he approaches the exit, the exit bouncer puts up a hand, then
looks at a clip board to see if Spike is on the guest list, which he always is,
- and then let's Spike pass to the next lower terrace. You really can't stop the
+ and then let's Spike pass to the next terrace. You really can't stop the
god of the earth. For every terrace that Spike needs to leave so that he can
rejoin with Tara, this futile ritual is repeated.
@@ -466,7 +452,7 @@ statechart ideas you need to know.
:target: _static/md_bartenders_on_the_hsm_reaction_2.pdf
:align: center
-.. admonition:: hint
+.. admonition:: translation
Tara, the "target state" is used by the event processor to recurse outward
from C1 to find a state that knows what to do with the Event, who's signal
@@ -558,7 +544,7 @@ statechart ideas you need to know.
-.. admonition:: hint
+.. admonition:: translation
The run to completion, RTC, concept is very important to understand. Your
statechart will only react to one event at a time. The thread will only
@@ -637,6 +623,8 @@ statechart ideas you need to know.
| | arguments, a reference to a statechart |
| | and an event to send to it |
+-------------------------------------+-----------------------------------------+
+| A pub | a state within a state machine |
++-------------------------------------+-----------------------------------------+
| Eve, "the goddess of law and order",| the event processor |
| goddess of heaven | |
+-------------------------------------+-----------------------------------------+
diff --git a/docs/_images/md_bartenders_on_the_hsm_hook.svg b/docs/_images/md_bartenders_on_the_hsm_hook.svg
index 1e2f493..5be8c2c 100644
--- a/docs/_images/md_bartenders_on_the_hsm_hook.svg
+++ b/docs/_images/md_bartenders_on_the_hsm_hook.svg
@@ -1,7 +1,7 @@
-BobBobBobBobTararejoinsSpikeTarathrow eventtothrow event tooblivionTarasearching forMary inA pubTarasearching forMary inB pubTarasearching forMary inC pubC pubB pubA pubTSide Viewstory board 5SBobexit /entry /exit /entry /exit /entry /TSide Viewstory board 4SBobexit /entry /B pubC pubA pubexit /entry /exit /entry /TEvent(signal=signals.Mary)Side Viewstory board 3SBobexit /entry /B pubC pubA pubexit /entry /exit /entry /TEvent(signal=signals.Mary)Side Viewstory board 2SBobexit /entry /B pubC pubA pubexit /entry /exit /entry /Side Viewstory board 1STBobEvent(signal=signals.Mary)exit /entry /B pubC pubA pubexit /entry /exit /entry /
diff --git a/docs/_images/md_bartenders_on_the_hsm_reaction_1.svg b/docs/_images/md_bartenders_on_the_hsm_reaction_1.svg
index aaf41f9..c5d67d4 100644
--- a/docs/_images/md_bartenders_on_the_hsm_reaction_1.svg
+++ b/docs/_images/md_bartenders_on_the_hsm_reaction_1.svg
@@ -1,7 +1,7 @@
-BobBobTEvent(signal=signals.Mary)Top View(UML)story board 2SBobMaryC2entry /exit / B2entry /exit / C1entry /exit / B1entry /exit / Aentry /exit / Top View(UML)story board 1Event(signal=signals.Mary)TSBobMaryexit /entry /C2entry /exit / B2entry /exit / C1entry /exit / B1entry /exit / Aentry /exit / Event(signal=signals.Mary)Page 1 of hsm reaction toEvent(signal=signals.Mary)MaryC2 pubB2 pubexit /entry /exit /entry /Side Viewstory board 2STBobexit /entry /B1 pubC1 pubA pubexit /entry /exit /entry /Page 1 of hsm reaction toEvent(signal=signals.Mary)MaryC2 pubB2 pubexit /entry /Side Viewstory board 1STBobEvent(signal=signals.Mary)exit /entry /B1 pubC1 pubA pubexit /entry /exit /entry /If an init doesn't do anything, it's not written on the UML diagram
diff --git a/docs/_images/md_eve.svg b/docs/_images/md_eve.svg
index e5b8820..c5bb778 100644
--- a/docs/_images/md_eve.svg
+++ b/docs/_images/md_eve.svg
@@ -1,7 +1,7 @@
-Application developersname the bartendersThe bossTaraEveBartender(bob)heavenearthhigher pubterraceSide ViewFull Drawinglower pubterraceinitexitenterinitexitenter
diff --git a/docs/_images/md_events.svg b/docs/_images/md_events.svg
index a0f1acc..1d91760 100644
--- a/docs/_images/md_events.svg
+++ b/docs/_images/md_events.svg
@@ -1,7 +1,7 @@
-Short HandFull Drawingfrom miros import EventEvent(signal=signals.Sue, payload="Orange")Event(signal=signals.Mary, payload="Red")Event(signal=signals.Bob)Event namesare calledEvents (orbs)have namesthat are calledsignalsEvents appearas orbs in thestory:SueBobMary Orange Red
-
-
-