aboutsummaryrefslogtreecommitdiffstats
path: root/lib/stdlib/doc
diff options
context:
space:
mode:
Diffstat (limited to 'lib/stdlib/doc')
-rw-r--r--lib/stdlib/doc/src/gen_statem.xml130
1 files changed, 83 insertions, 47 deletions
diff --git a/lib/stdlib/doc/src/gen_statem.xml b/lib/stdlib/doc/src/gen_statem.xml
index f608e10469..5de1812b41 100644
--- a/lib/stdlib/doc/src/gen_statem.xml
+++ b/lib/stdlib/doc/src/gen_statem.xml
@@ -110,11 +110,28 @@ erlang:'!' -----> Module:StateName/5
states so you do not accidentally postpone one event
forever creating an infinite busy loop.
</p>
- <p>
- An event can can be postponed causing it to be retried
- after the state has changed, or more precisely;
- after a state change all postponed events are retried
- in the new state.
+ <p>The gen_statem enqueues incoming events in order of arrival
+ and presents these to the
+ <seealso marker="#state_function">state function</seealso>
+ in that order. The state function can postpone an event
+ so it is not retried in the current state.
+ After a state change all enqueued events (including postponed)
+ are again presented to the state function.
+ </p>
+ <p>The
+ <seealso marker="#state_function">state function</seealso>
+ can insert events using the
+ <seealso marker="#type-state_operation">
+ <c>state_operation()</c> <c>next_event</c>
+ </seealso>
+ and such an event is inserted as the next to present
+ to the state function. That is: as if it is
+ the oldest incoming event. There is a dedicated
+ <seealso marker="#type-event_type">
+ <c>event_type()</c> <c>internal</c>
+ </seealso>
+ that can be used for such events making it impossible
+ to mistake for an external event.
</p>
<p>A gen_statem handles system messages as documented in
<seealso marker="sys">sys</seealso>.
@@ -302,7 +319,12 @@ erlang:'!' -----> Module:StateName/5
<datatype>
<name name="init_option" />
<desc>
- <p>Option that only is valid when initializing the gen_statem</p>
+ <p>Option that only is valid when initializing the gen_statem
+ that is it can be returned from
+ <seealso marker="#Module:init/1">Module:init/1</seealso>
+ or given to
+ <seealso marker="#enter_loop/5">enter_loop/5,6</seealso>.
+ </p>
</desc>
</datatype>
<datatype>
@@ -332,7 +354,7 @@ erlang:'!' -----> Module:StateName/5
<p>Either a
<seealso marker="#type-state_option">
<c>state_option()</c>
- </seealso> of which the first occurence
+ </seealso> of which the last occurence
in the containing list takes precedence, or a
<seealso marker="#type-state_operation">
<c>state_operation()</c>
@@ -340,42 +362,34 @@ erlang:'!' -----> Module:StateName/5
the containing list.
</p>
<p>These may be returned from the
- <seealso marker="#state_function">state function</seealso>
- or from <seealso marker="#Module:init/1">Module:init/1</seealso>.
- </p>
- <p>The gen_statem enqueues postponed events and
- not yet processed events in order of arrival, except for
- an event that a callback function inserts with
- <c>{insert_event,EventType,EventContent}</c> that is inserted
- as the next event to process.
+ <seealso marker="#state_function">state function</seealso>,
+ from <seealso marker="#Module:init/1">Module:init/1</seealso>
+ or given to
+ <seealso marker="#enter_loop/5">enter_loop/5,6</seealso>.
</p>
- <p>When the state machine changes states all enqueued events
- becomes not yet processed to be processed before the old
- not yet processed events. In other words; the order of arrival
- is retained.
- </p>
- <p>The processing order is:</p>
+ <p>The processing order for a state change is:</p>
<list type="ordered">
<item>If the option <c>retry</c> is <c>true</c>
- the current event is enqueued as postponed to be retried.
+ the current event is postponed.
</item>
- <item>If the state changes all postponed events
- are transferred to not yet processed to be processed
- before other not yet processed events.
+ <item>If the state changes the queue of incoming events
+ is reset to start with the oldest postponed.
</item>
<item>All operations are processed in order of appearance.
</item>
- <item>The <c>timeout</c> option is processed if present.
- So a state timer may be started or a timeout zero event
- may be inserted as if just received.
+ <item>The <c>timeout</c> option is processed if present,
+ so a state timer may be started or a timeout zero event
+ may be enqueued as the newest incoming.
</item>
<item>The (possibly new)
<seealso marker="#state_function">state function</seealso>
- is called with the next not yet processed event
- if there is any, otherwise the gen_statem goes into <c>receive</c>
+ is called with the oldest enqueued event if there is any,
+ otherwise the gen_statem goes into <c>receive</c>
or hibernation (if the option <c>hibernate</c> is <c>true</c>)
to wait for the next message. In hibernation the next
- non-system event awakens the gen_statem.
+ non-system event awakens the gen_statem, or rather
+ the next incoming message awakens the gen_statem but if it
+ is a system event it goes back into hibernation.
</item>
</list>
</desc>
@@ -383,12 +397,21 @@ erlang:'!' -----> Module:StateName/5
<datatype>
<name name="state_option" />
<desc>
+ <p>If multiple state options of the same type are present
+ in the containing list these are set in the list order
+ and the last value is kept.
+ </p>
<taglist>
<tag><c>retry</c></tag>
<tag><c>{retry,<anno>Retry</anno>}</c></tag>
<item>If <c><anno>Retry</anno> =:= true</c>
or plain <c>retry</c> postpone the current event
to be retried after a state change.
+ This option is ignored when returned from
+ <seealso marker="#Module:init/1">Module:init/1</seealso>
+ or given to
+ <seealso marker="#enter_loop/5">enter_loop/5,6</seealso>
+ since there is no event to postpone in those cases.
</item>
<tag><c>hibernate</c></tag>
<tag><c>{hibernate,<anno>Hibernate</anno>}</c></tag>
@@ -397,9 +420,9 @@ erlang:'!' -----> Module:StateName/5
<seealso marker="proc_lib#hibernate/3">
<c>proc_lib:hibernate/3</c>
</seealso> before <c>receive</c> to wait for a new event.
- If there are not yet processed events the
- <c>hibernate</c> operation is ignored as if an event
- just arrived and awakened the gen_statem.
+ If there are enqueued events the <c>hibernate</c> operation
+ is ignored as if an event just arrived and awakened
+ the gen_statem.
</item>
<tag>
<c>{timeout,<anno>Time</anno>,<anno>Msg</anno>}</c>
@@ -426,14 +449,20 @@ erlang:'!' -----> Module:StateName/5
<datatype>
<name name="state_operation" />
<desc>
+ <p>The state operations are executed in the containing
+ list order. This matters for <c>next_event</c> where
+ the last one in the list will become the next event to present
+ to the state functions. Regarding the other operations
+ it is only for <c>{remove_event,<anno>EventPredicate</anno>}</c>
+ that the order may matter.
+ </p>
<taglist>
<tag>
<c>
- {insert_event,<anno>EventType</anno>,<anno>EventContent</anno>}
+ {next_event,<anno>EventType</anno>,<anno>EventContent</anno>}
</c>
</tag>
- <item>Insert the given event as the next to process
- before any other not yet processed events.
+ <item>Insert the given event as the next to process.
An event of type
<seealso marker="#type-event_type">
<c>internal</c>
@@ -982,7 +1011,13 @@ erlang:'!' -----> Module:StateName/5
<seealso marker="#call/2">gen_statem:call/2</seealso>,
<seealso marker="#cast/2">gen_statem:cast/2</seealso> or
as a normal process message this function is called.
- If the <c>EventType</c> is
+ If
+ <seealso marker="#type-callback_mode">callback_mode</seealso>
+ is <c>state_functions</c> then <c>Module:StateName/5</c> is called,
+ and if it is <c>handle_event_function</c>
+ then <c>Module:handle_event/5</c> is called.
+ </p>
+ <p>If <c>EventType</c> is
<seealso marker="#type-event_type"><c>{call,Client}</c></seealso>
the client is waiting for a reply. The reply can be sent
from this or from any other
@@ -995,23 +1030,24 @@ erlang:'!' -----> Module:StateName/5
<c>gen_statem:reply(Client, Reply)</c>
</seealso>.
</p>
- <p><c>StateName</c> is rarely useful. One exception is if
- you call a common event handling function from your state
+ <p><c>StateName</c> is useful in some odd cases for example
+ if you call a common event handling function from your state
function then you might want to pass <c>StateName</c>.
</p>
- <p><c>PrevStateName</c> and <c>PrevState</c> are rarely useful.
- They can be used when you want to do something only at the
- first event in a state. Note that when gen_statem enters
- its first state this is set to a <c>reference()</c> since
- that can not match the state.
+ <p><c>PrevStateName</c> and <c>PrevState</c> are useful
+ in some odd cases for example when you want to do something
+ only at the first event in a state.
+ Note that when gen_statem enters its first state
+ this is set to a <c>reference()</c>
+ since that can not match equal to any state.
</p>
<p>If this function returns with a new state that
does not match equal (<c>=/=</c>) to the current state
all postponed events will be retried in the new state.
</p>
<p>See <seealso marker="#type-state_op">state_op()</seealso>
- for the operations that can be done by gen_statem
- after returning from this function.
+ for options that can be set and operations that can be done
+ by gen_statem after returning from this function.
</p>
</desc>
</func>