From 6bf2768c6836440634019d69231534ed69fcf982 Mon Sep 17 00:00:00 2001 From: Raimo Niskanen Date: Fri, 18 Mar 2016 10:23:48 +0100 Subject: Do more intricate Fred Hebert doc changes --- lib/stdlib/doc/src/gen_statem.xml | 126 +++++++++++++++++++++----------------- lib/stdlib/src/gen_statem.erl | 10 +-- 2 files changed, 74 insertions(+), 62 deletions(-) (limited to 'lib/stdlib') diff --git a/lib/stdlib/doc/src/gen_statem.xml b/lib/stdlib/doc/src/gen_statem.xml index 83f7dc1c8a..bd70c4c37e 100644 --- a/lib/stdlib/doc/src/gen_statem.xml +++ b/lib/stdlib/doc/src/gen_statem.xml @@ -127,8 +127,7 @@ erlang:'!' -----> Module:StateName/3 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 ones) - are presented again to the state function. + After a state change the queue restarts with the postponed events.

The gen_statem event queue model is sufficient @@ -157,10 +156,10 @@ erlang:'!' -----> Module:StateName/3 state handling functions that you often would have to resort to in for example gen_fsm to force processing an inserted event before others. - If you for example in gen_statem postpone an event - in one state and then call some other state function of yours, - you have not changed states and hence the postponed event - will not be retried, which is logical but might be confusing. + A warning, though: if you in gen_statem for example + postpone an event in one state and then call some other state function of yours, + you have not changed states and hence the postponed event will not be retried, + which is logical but might be confusing.

See the type @@ -302,8 +301,8 @@ ok callback_mode state_functions, or rather here is code to replace - from the init/1 function of the pushbutton - example module above: + from the init/1 function of the pushbutton.erl + example file above:

init([]) -> @@ -364,8 +363,8 @@ handle_event(_, _, State, Data) ->

It can be:

- pid() - LocalName + pid()
+ LocalName The gen_statem is locally registered. Name, Node @@ -489,13 +488,10 @@ handle_event(_, _, State, Data) -> casts originate from the corresponding API functions. For calls the event contain whom to reply to. - Type info originates from - regular process messages sent - to the gen_statem. - It is also possible for the state machine - implementation to insert events to itself, - in particular of types - timeout and internal. + Type info originates from regular process messages sent + to the gen_statem. It is also possible for the state machine + implementation to generate events of types + timeout and internal to itself.

@@ -559,7 +555,7 @@ handle_event(_, _, State, Data) -> is reset to start with the oldest postponed. - All events inserted with + All events stored with action() next_event @@ -634,14 +630,21 @@ handle_event(_, _, State, Data) -> event arrives in which case this timeout is cancelled. Note that a retried or inserted event counts just like a new in this respect. - If the value is infinity no timer is started. - If it is 0 the timeout event - is immediately enqueued as the newest received - (unless there are retried or inserted events to process - since then the timeout is cancelled). - Also note that it is not possible nor needed - to cancel this timeout since it is cancelled automatically - by any other event. +

+

+ If the value is infinity no timer is started since + it will never trigger anyway. +

+

+ If the value is 0 the timeout event is immediately enqueued + unless there already are enqueued events since then the + timeout is immediately cancelled. + This is a feature ensuring that a timeout 0 event + will be processed before any not yet received external event. +

+

+ Note that it is not possible nor needed to cancel this timeout + since it is cancelled automatically by any other event.

@@ -658,16 +661,19 @@ handle_event(_, _, State, Data) ->

Actions are executed in the containing list order. - The order matters for some actions such as next_event - and reply_action().

Actions that set transition options - overrides any previous of the same kind, + overrides any previous of the same type, so the last in the containing list wins. + For example the last + + event_timeout() + + overrides any other event_timeout() in the list.

postpone @@ -693,7 +699,7 @@ handle_event(_, _, State, Data) -> Timeout - Short for {timeout,Timeout} that is + Short for {timeout,Timeout,Timeout} that is the timeout message is the timeout time. This form exists to make the state function @@ -708,27 +714,33 @@ handle_event(_, _, State, Data) -> transition_option() event_timeout() - to Time with the - EventContent as Msg. + to Time with EventContent. reply_action() Reply to a caller. next_event - Insert the given EventType - and EventContent as the next to process. - This will bypass any events in the process mailbox as well - as any other queued events. - All next_event actions - in the containing list are buffered and inserted - after the actions have been done - so that the first in the list will be the first to process. - An event of type - - internal - - should be used when you want to reliably distinguish - an event inserted this way from any external event. + Store the given EventType + and EventContent for insertion after all + actions have been executed. + + +

+ The stored events are inserted in the queue as the next to process + before any already queued events. The order of these stored events + is preserved so the first next_event in the containing list + will become the first to process. +

+ + +

+ An event of type + + internal + + should be used when you want to reliably distinguish + an event inserted this way from any external event. +

@@ -1047,17 +1059,17 @@ handle_event(_, _, State, Data) -> or the atom infinity to wait indefinitely, which is the default. If no reply is received within the specified time, the function call fails. - -

- To avoid getting a late reply in the caller's - inbox this function spawns a proxy process that - does the call. A late reply gets delivered to the - dead proxy process hence gets discarded. This is - less efficient than using - Timeout =:= infinity. -

-

+ +

+ To avoid getting a late reply in the caller's + inbox this function spawns a proxy process that + does the call. A late reply gets delivered to the + dead proxy process hence gets discarded. This is + less efficient than using + Timeout =:= infinity. +

+

The call may fail for example if the gen_statem dies before or during this function call. @@ -1218,7 +1230,7 @@ handle_event(_, _, State, Data) -> CALLBACK FUNCTIONS

The following functions should be exported from a - gen_statem callback module. + gen_statem callback module.

diff --git a/lib/stdlib/src/gen_statem.erl b/lib/stdlib/src/gen_statem.erl index 82ac5824eb..9c1e126507 100644 --- a/lib/stdlib/src/gen_statem.erl +++ b/lib/stdlib/src/gen_statem.erl @@ -86,7 +86,7 @@ %% If 'true' hibernate the server instead of going into receive boolean(). -type event_timeout() :: - %% Generate a ('timeout', Msg, ...) event after Time + %% Generate a ('timeout', EventContent, ...) event after Time %% unless some other event is delivered Time :: timeout(). @@ -113,7 +113,7 @@ %% (Timeout :: event_timeout()) | % {timeout,Timeout} {'timeout', % Set the event timeout option - Time :: event_timeout(), Msg :: term()} | + Time :: event_timeout(), EventContent :: term()} | %% reply_action() | %% @@ -1054,17 +1054,17 @@ loop_event_actions( undefined -> %% No state timeout has been requested {Q3,undefined}; - {timeout,Time,Msg} -> + {timeout,Time,EventContent} -> %% A state timeout has been requested case Q3 of [] when Time =:= 0 -> %% Immediate timeout - simulate it %% so we do not get the timeout message %% after any received event - {[{timeout,Msg}],undefined}; + {[{timeout,EventContent}],undefined}; [] -> %% Actually start a timer - {Q3,erlang:start_timer(Time, self(), Msg)}; + {Q3,erlang:start_timer(Time, self(), EventContent)}; _ -> %% Do not start a timer since any queued %% event cancels the state timer so we pretend -- cgit v1.2.3