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 ++++++++++++++++++++++------------- lib/stdlib/src/gen_statem.erl | 15 ++-- lib/stdlib/test/gen_statem_SUITE.erl | 2 +- 3 files changed, 91 insertions(+), 56 deletions(-) (limited to 'lib/stdlib') 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.

diff --git a/lib/stdlib/src/gen_statem.erl b/lib/stdlib/src/gen_statem.erl index 782e027b29..52fde7df7b 100644 --- a/lib/stdlib/src/gen_statem.erl +++ b/lib/stdlib/src/gen_statem.erl @@ -88,7 +88,7 @@ %% These can occur multiple times and are executed in order %% of appearence in the state_op() list reply_operation() | - {'insert_event', % Insert event as the next to handle + {'next_event', % Insert event as the next to handle EventType :: event_type(), EventContent :: term()} | {'remove_event', % Remove the oldest matching (=:=) event @@ -469,7 +469,7 @@ enter(Module, Options, State, StateData, Server, InitOps, Parent) -> S#{callback_mode := CallbackMode}, [], {event,undefined}, State, StateData, - [{retry,false}|StateOps]); + StateOps++[{retry,false}]); [Reason] -> ?TERMINATE(Reason, Debug, S, []) end. @@ -846,10 +846,10 @@ loop_event_state_ops( %% Server helpers collect_init_options(InitOps) -> - collect_init_options(lists:reverse(InitOps), state_functions, []). + collect_init_options(InitOps, state_functions, []). %% Keep the last of each kind collect_init_options([], CallbackMode, StateOps) -> - {CallbackMode,StateOps}; + {CallbackMode,lists:reverse(StateOps)}; collect_init_options([InitOp|InitOps] = IOIOs, CallbackMode, StateOps) -> case InitOp of {callback_mode,Mode} @@ -864,12 +864,11 @@ collect_init_options([InitOp|InitOps] = IOIOs, CallbackMode, StateOps) -> end. collect_state_options(StateOps) -> - collect_state_options( - lists:reverse(StateOps), false, false, undefined, []). + collect_state_options(StateOps, false, false, undefined, []). %% Keep the last of each kind collect_state_options( [], Retry, Hibernate, Timeout, Operations) -> - {Retry,Hibernate,Timeout,Operations}; + {Retry,Hibernate,Timeout,lists:reverse(Operations)}; collect_state_options( [StateOp|StateOps] = SOSOs, Retry, Hibernate, Timeout, Operations) -> case StateOp of @@ -909,7 +908,7 @@ process_state_operations([Operation|Operations] = OOs, Debug, S, Q, P) -> {reply,{_To,_Tag}=Client,Reply} -> NewDebug = do_reply(Debug, S, Client, Reply), process_state_operations(Operations, NewDebug, S, Q, P); - {insert_event,Type,Content} -> + {next_event,Type,Content} -> case event_type(Type) of true -> process_state_operations( diff --git a/lib/stdlib/test/gen_statem_SUITE.erl b/lib/stdlib/test/gen_statem_SUITE.erl index 8a96f0e8e2..facc36fb9f 100644 --- a/lib/stdlib/test/gen_statem_SUITE.erl +++ b/lib/stdlib/test/gen_statem_SUITE.erl @@ -1180,7 +1180,7 @@ timeout(timeout, idle, idle, timeout, {From,Time}) -> TRefC2 = erlang:start_timer(Time, self(), cancel2), {next_state,timeout2,{From,Time,TRef2}, [{cancel_timer, TRefC1}, - {insert_event,internal,{cancel_timer,TRefC2}}]}; + {next_event,internal,{cancel_timer,TRefC2}}]}; timeout(_, _, _, State, Data) -> {next_state,State,Data}. -- cgit v1.2.3