diff options
Diffstat (limited to 'lib/stdlib/doc')
| -rw-r--r-- | lib/stdlib/doc/src/gen_statem.xml | 130 |
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> |