From 972a8fcb57a64c9a0dc7587e9072c15758e36da2 Mon Sep 17 00:00:00 2001
From: Raimo Niskanen
Date: Thu, 18 Feb 2016 10:22:50 +0100
Subject: Rename insert_event -> next_event
---
lib/stdlib/doc/src/gen_statem.xml | 130 ++++++++++++++++++++++++--------------
1 file changed, 83 insertions(+), 47 deletions(-)
(limited to 'lib/stdlib/doc/src/gen_statem.xml')
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.
-
- 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.
+
The gen_statem enqueues incoming events in order of arrival
+ and presents these to the
+ state function
+ 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.
+
+ The
+ state function
+ can insert events using the
+
+ state_operation() next_event
+
+ 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
+
+ event_type() internal
+
+ that can be used for such events making it impossible
+ to mistake for an external event.
A gen_statem handles system messages as documented in
sys.
@@ -302,7 +319,12 @@ erlang:'!' -----> Module:StateName/5
- Option that only is valid when initializing the gen_statem
+ Option that only is valid when initializing the gen_statem
+ that is it can be returned from
+ Module:init/1
+ or given to
+ enter_loop/5,6.
+
@@ -332,7 +354,7 @@ erlang:'!' -----> Module:StateName/5
Either a
state_option()
- of which the first occurence
+ of which the last occurence
in the containing list takes precedence, or a
state_operation()
@@ -340,42 +362,34 @@ erlang:'!' -----> Module:StateName/5
the containing list.
These may be returned from the
- state function
- or from Module:init/1.
-
- 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
- {insert_event,EventType,EventContent} that is inserted
- as the next event to process.
+ state function,
+ from Module:init/1
+ or given to
+ enter_loop/5,6.
- 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.
-
- The processing order is:
+ The processing order for a state change is:
- If the option retry is true
- the current event is enqueued as postponed to be retried.
+ the current event is postponed.
- - If the state changes all postponed events
- are transferred to not yet processed to be processed
- before other not yet processed events.
+
- If the state changes the queue of incoming events
+ is reset to start with the oldest postponed.
- All operations are processed in order of appearance.
- - The timeout option is processed if present.
- So a state timer may be started or a timeout zero event
- may be inserted as if just received.
+
- The timeout option is processed if present,
+ so a state timer may be started or a timeout zero event
+ may be enqueued as the newest incoming.
- The (possibly new)
state function
- is called with the next not yet processed event
- if there is any, otherwise the gen_statem goes into receive
+ is called with the oldest enqueued event if there is any,
+ otherwise the gen_statem goes into receive
or hibernation (if the option hibernate is true)
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.
@@ -383,12 +397,21 @@ erlang:'!' -----> Module:StateName/5
+ 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.
+
retry
{retry,Retry}
- If Retry =:= true
or plain retry postpone the current event
to be retried after a state change.
+ This option is ignored when returned from
+ Module:init/1
+ or given to
+ enter_loop/5,6
+ since there is no event to postpone in those cases.
hibernate
{hibernate,Hibernate}
@@ -397,9 +420,9 @@ erlang:'!' -----> Module:StateName/5
proc_lib:hibernate/3
before receive to wait for a new event.
- If there are not yet processed events the
- hibernate operation is ignored as if an event
- just arrived and awakened the gen_statem.
+ If there are enqueued events the hibernate operation
+ is ignored as if an event just arrived and awakened
+ the gen_statem.
{timeout,Time,Msg}
@@ -426,14 +449,20 @@ erlang:'!' -----> Module:StateName/5
+ The state operations are executed in the containing
+ list order. This matters for next_event 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 {remove_event,EventPredicate}
+ that the order may matter.
+
- {insert_event,EventType,EventContent}
+ {next_event,EventType,EventContent}
- - Insert the given event as the next to process
- before any other not yet processed events.
+
- Insert the given event as the next to process.
An event of type
internal
@@ -982,7 +1011,13 @@ erlang:'!' -----> Module:StateName/5
gen_statem:call/2,
gen_statem:cast/2 or
as a normal process message this function is called.
- If the EventType is
+ If
+ callback_mode
+ is state_functions then Module:StateName/5 is called,
+ and if it is handle_event_function
+ then Module:handle_event/5 is called.
+
+ If EventType is
{call,Client}
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
gen_statem:reply(Client, Reply)
.
- StateName is rarely useful. One exception is if
- you call a common event handling function from your state
+
StateName 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 StateName.
- PrevStateName and PrevState 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 reference() since
- that can not match the state.
+
PrevStateName and PrevState 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 reference()
+ since that can not match equal to any state.
If this function returns with a new state that
does not match equal (=/=) to the current state
all postponed events will be retried in the new state.
See state_op()
- 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.
--
cgit v1.2.3