From 898e66f07dce8b7b33874255bb3ea1c6f5534d34 Mon Sep 17 00:00:00 2001 From: Raimo Niskanen Date: Fri, 19 Feb 2016 15:26:33 +0100 Subject: Update terminology to data(), transition_op(), etc --- lib/stdlib/doc/src/gen_statem.xml | 222 +++++++++++--------- lib/stdlib/src/gen_statem.erl | 382 ++++++++++++++++++----------------- lib/stdlib/test/gen_statem_SUITE.erl | 44 ++-- 3 files changed, 338 insertions(+), 310 deletions(-) (limited to 'lib') diff --git a/lib/stdlib/doc/src/gen_statem.xml b/lib/stdlib/doc/src/gen_statem.xml index c685d24b78..15e9584360 100644 --- a/lib/stdlib/doc/src/gen_statem.xml +++ b/lib/stdlib/doc/src/gen_statem.xml @@ -94,7 +94,7 @@ erlang:'!' -----> Module:StateName/5 Module:StateName/5 . - This naturally collects all code for a specific state + This gathers all code for a specific state in one function and hence dispatches on state first.

When @@ -135,8 +135,8 @@ erlang:'!' -----> Module:StateName/5

The state function can insert events using the - - state_operation() next_event + + transition_action() next_event and such an event is inserted as the next to present to the state function. That is: as if it is @@ -176,8 +176,8 @@ erlang:'!' -----> Module:StateName/5 state function or Module:init/1 specifies 'hibernate' in the returned - StateOps list. - This might be useful if the server is expected to be idle + Ops + list. This might be useful if the server is expected to be idle for a long time. However use this feature with care since hibernation implies at least two garbage collections (when hibernating and shortly after waking up) and that is not @@ -273,8 +273,8 @@ erlang:'!' -----> Module:StateName/5

Client address to use when replying through for example the - - state_op() {reply,Client,Reply} + + transition_op() {reply,Client,Reply} to a client that has called the gen_statem server using call/2. @@ -296,19 +296,21 @@ erlang:'!' -----> Module:StateName/5 callback_mode is state_functions, which is the default, - the state has to be of this type i.e an atom(). + the state has to be of this type.

- + -

A term() in which the state machine implementation - should store any state data it needs. The difference between - this data and the - state() +

A term in which the state machine implementation + should store any server data it needs. The difference between + this and the state() itself is that a change in this data does not cause - postponed events to be retried. + postponed events to be retried. Hence if a change + in this data would change the set of events that + are handled than that data item should be made + a part of the state.

@@ -334,8 +336,8 @@ erlang:'!' -----> Module:StateName/5

A fun() of arity 2 that takes an event and returns a boolean. - When used in {remove_event,RemoveEventPredicate} - from state_op(). + When used in {remove_event,RemoveEventPredicate} from + transition_op(). The event for which the predicate returns true will be removed.

@@ -378,17 +380,16 @@ erlang:'!' -----> Module:StateName/5 - +

Either a - - state_option() + + transition_option() of which the last occurence in the containing list takes precedence, or a - - state_operation() - that are performed in order of - the containing list. + + transition_action() + performed in the order of the containing list.

These may be returned from the state function, @@ -404,7 +405,7 @@ erlang:'!' -----> Module:StateName/5 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. + All actions 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 @@ -424,9 +425,9 @@ erlang:'!' -----> Module:StateName/5 - + -

If multiple state options of the same type are present +

If multiple state options of the same kind are present in the containing list these are set in the list order and the last value is kept.

@@ -448,7 +449,7 @@ erlang:'!' -----> Module:StateName/5 proc_lib:hibernate/3 before receive to wait for a new event. - If there are enqueued events the hibernate operation + If there are enqueued events the hibernate action is ignored as if an event just arrived and awakened the gen_statem. @@ -464,8 +465,8 @@ erlang:'!' -----> Module:StateName/5 is immediately enqueued as the newest received. Also note that it is not possible nor needed to cancel this timeout using the - - state_operation() + + transition_action() cancel_timer. This timeout is cancelled automatically by any event. @@ -473,17 +474,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 with - EventPredicate - and for reply_operation() that the order may matter. +

The state transition actions 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 actions + it is only for remove_event with + EventPredicate + and for reply_action() that the order may matter.

+ reply_action() + Reply to a calling client. next_event Insert the given EventType and EventContent the next to process. @@ -518,7 +522,7 @@ erlang:'!' -----> Module:StateName/5 demonitor/2 with MonitorRef. - {unlink,Id} + unlink Like {cancel_timer,_} above but for unlink/1 @@ -528,7 +532,7 @@ erlang:'!' -----> Module:StateName/5 - +

Reply to a client that called call/2. @@ -550,26 +554,26 @@ erlang:'!' -----> Module:StateName/5 Module:terminate/3 with Reason and - NewStateData, if given. + NewData, if given. next_state The gen_statem will do a state transition to NewState (which may be the same as the current state), - set NewStateData - and execute all StateOps + set NewData + and execute all Ops keep_state The gen_statem will keep the current state, or do a state transition to the current state if you like, - set NewStateData - and execute all StateOps + set NewData + and execute all Ops keep_state_and_data The gen_statem will keep the current state, or do a state transition to the current state if you like, - keep the current state data, - and execute all StateOps + keep the current server data, + and execute all Ops @@ -614,7 +618,7 @@ erlang:'!' -----> Module:StateName/5 .

If the option {timeout,Time} is present in - Options, the gen_statem + Opts, the gen_statem is allowed to spend Time milliseconds initializing or it will be terminated and the start function will return @@ -623,15 +627,14 @@ erlang:'!' -----> Module:StateName/5

If the option {debug,Dbgs} - is present in Options, debugging through + is present in Opts, debugging through sys is activated.

-

If the option {spawn_opt,SOpts} is present in - Options, SOpts will be passed - as option list to the spawn_opt BIF - which is used to - spawn - the gen_statem. +

If the option {spawn_opt,SpawnOpts} is present in + Opts, SpawnOpts will be passed + as option list to + spawn_opt/2 + which is used to spawn the gen_statem process.

Using the spawn option monitor is currently not @@ -760,7 +763,9 @@ erlang:'!' -----> Module:StateName/5 state function returns with {reply,Client,Reply} as one - state_op(), + + transition_op() + , and that Reply becomes the return value of this function.

@@ -823,8 +828,8 @@ erlang:'!' -----> Module:StateName/5 state function. Client and Reply can also be specified using a - - reply_operation() + + reply_action() and multiple replies with a list of them.

@@ -852,20 +857,20 @@ erlang:'!' -----> Module:StateName/5 Enter the gen_statem receive loop -

If Server_or_StateOps is a list() +

If Server_or_Ops is a list() the same as enter_loop/6 except that no server_name() must have been registered and - StateOps = Server_or_StateOps. + Ops = Server_or_Ops.

Otherwise the same as enter_loop/6 with - Server = Server_or_StateOps and - StateOps = []. + Server = Server_or_Ops and + Ops = [].

@@ -887,7 +892,7 @@ erlang:'!' -----> Module:StateName/5 procedure is needed than the gen_statem behaviour provides.

-

Module, Options and +

Module, Opts and Server have the same meanings as when calling @@ -898,8 +903,8 @@ erlang:'!' -----> Module:StateName/5 server_name() name must have been registered accordingly before this function is called.

-

State, StateData - and StateOps +

State, Data + and Ops have the same meanings as in the return value of Module:init/1. Also, the callback module Module @@ -933,15 +938,14 @@ erlang:'!' -----> Module:StateName/5 Initialize process and internal state Args = term() - Result = {ok,State,StateData} -  | {ok,State,StateData,StateOps} + Result = {ok,State,Data} +  | {ok,State,Data,Ops}  | {stop,Reason} | ignore State = state() - StateData = - state_data() + Data = data() - StateOps = - [state_op() + Ops = + [transition_op() | init_option()] Reason = term() @@ -953,17 +957,17 @@ erlang:'!' -----> Module:StateName/5 or start/3,4, this function is called by the new process to initialize - the implementation loop data. + the implementation state and server data.

Args is the Args argument provided to the start function.

If the initialization is successful, the function should - return {ok,State,StateData} or - {ok,State,StateData,StateOps}. + return {ok,State,Data} or + {ok,State,Data,Ops}. State is the state of the gen_statem.

-

The StateOps +

The Ops are executed when entering the first state just as for a state function. @@ -978,15 +982,19 @@ erlang:'!' -----> Module:StateName/5 or ignore. See start_link/3,4.

+

This function may use + throw, + to return its value. +

Module:StateName(EventType, EventContent, - PrevStateName, StateName, StateData) -> Result + PrevStateName, StateName, Data) -> Result Module:handle_event(EventType, EventContent, - PrevState, State, StateData) -> Result + PrevState, State, Data) -> Result Handle an event @@ -1003,8 +1011,8 @@ erlang:'!' -----> Module:StateName/5 PrevState = State = state() - StateData = NewStateData = - state_data() + Data = NewData = + data() Result = @@ -1029,8 +1037,8 @@ erlang:'!' -----> Module:StateName/5 from this or from any other state function by returning with {reply,Client,Reply} in - StateOps, in - Replies + Ops, in + Replies or by calling reply(Client, Reply) @@ -1050,23 +1058,25 @@ erlang:'!' -----> Module:StateName/5 does not match equal (=/=) to the current state all postponed events will be retried in the new state.

-

See state_op() - for options that can be set and operations that can be done +

See + transition_op() + for options that can be set and actions that can be done by gen_statem after returning from this function.

+

These functions may use + throw, + to return its value. +

- Module:terminate(Reason, State, StateData) -> Ignored + Module:terminate(Reason, State, Data) -> Ignored Clean up before termination Reason = normal | shutdown | {shutdown,term()} | term() State = state() - StateData = - - state_data() - + Data = data() Ignored = term() @@ -1085,7 +1095,7 @@ erlang:'!' -----> Module:StateName/5 is terminating. If it is because another callback function has returned a stop tuple {stop,Reason} in - StateOps, + Ops, Reason will have the value specified in that tuple. If it is due to a failure, Reason is the error reason.

@@ -1118,11 +1128,15 @@ erlang:'!' -----> Module:StateName/5 error_logger:format/2 .

+

This function may use + throw, + to return its value. +

- Module:code_change(OldVsn, OldState, OldStateData, Extra) -> + Module:code_change(OldVsn, OldState, OldData, Extra) -> Result Update the internal state during upgrade/downgrade @@ -1131,12 +1145,12 @@ erlang:'!' -----> Module:StateName/5   Vsn = term() OldState = NewState = term() Extra = term() - Result = {ok,{NewState,NewStateData}} | Reason + Result = {ok,{NewState,NewData}} | Reason OldState = NewState = state() - OldStateData = NewStateData = - state_data() + OldData = NewData = + data() Reason = term() @@ -1158,7 +1172,7 @@ erlang:'!' -----> Module:StateName/5 Module. If no such attribute is defined, the version is the checksum of the BEAM file.

-

OldState and OldStateData is the internal state +

OldState and OldData is the internal state of the gen_statem.

Extra is passed as-is from the {advanced,Extra} @@ -1166,15 +1180,19 @@ erlang:'!' -----> Module:StateName/5

If successful, the function shall return the updated internal state in an - {ok,{NewState,NewStateData}} tuple. + {ok,{NewState,NewData}} tuple.

If the function returns Reason, the ongoing upgrade will fail and roll back to the old release.

+

This function may use + throw, + to return its value. +

- Module:format_status(Opt, [PDict,State,StateData]) -> + Module:format_status(Opt, [PDict,State,Data]) -> Status Optional function for providing a term describing the @@ -1185,8 +1203,8 @@ erlang:'!' -----> Module:StateName/5 State = state() - StateData = - state_data() + Data = + data() Key = term() Value = term() @@ -1197,7 +1215,8 @@ erlang:'!' -----> Module:StateName/5

This callback is optional, so callback modules need not export it. The gen_statem module provides a default implementation of this function that returns the callback - module state. + module state and data. The default function will also + be used if this callback fails.

This function is called by a gen_statem process when:

@@ -1229,6 +1248,9 @@ erlang:'!' -----> Module:StateName/5

State is the internal state of the gen_statem.

+

Data + is the internal server data of the gen_statem. +

The function should return Status, a term that customises the details of the current state and status of the gen_statem. There are no restrictions on the @@ -1250,6 +1272,10 @@ erlang:'!' -----> Module:StateName/5 state representations to avoid having large state terms printed in logfiles.

+

This function may use + throw, + to return its value. +

diff --git a/lib/stdlib/src/gen_statem.erl b/lib/stdlib/src/gen_statem.erl index 8aa8afd091..1ca2e1009c 100644 --- a/lib/stdlib/src/gen_statem.erl +++ b/lib/stdlib/src/gen_statem.erl @@ -57,7 +57,7 @@ state_name() | % For state callback function StateName/5 term(). % For state callback function handle_event/5 -type state_name() :: atom(). --type state_data() :: term(). +-type data() :: term(). -type event_type() :: {'call',Client :: client()} | 'cast' | 'info' | 'timeout' | 'internal'. @@ -66,17 +66,18 @@ -type init_option() :: {'callback_mode', callback_mode()}. -type callback_mode() :: 'state_functions' | 'handle_event_function'. --type state_op() :: - %% First NewState and NewStateData are set, - %% then all state_operations() are executed in order of +-type transition_op() :: + %% First NewState and NewData are set, + %% then all transition_action()s are executed in order of %% apperance. Postponing the current event is performed - %% (iff state_option() 'postpone' is 'true'). + %% (iff transition_option() 'postpone' is 'true'). %% Lastly pending events are processed or if there are %% no pending events the server goes into receive - %% or hibernate (iff state_option() 'hibernate' is 'true') - state_option() | state_operation(). --type state_option() :: - %% The first of each kind in the state_op() list takes precedence + %% or hibernate (iff transition_option() 'hibernate' is 'true') + transition_option() | transition_action(). +-type transition_option() :: + %% The last of each kind in the transition_op() + %% list takes precedence 'postpone' | % Postpone the current event to a different (=/=) state {'postpone', Postpone :: boolean()} | 'hibernate' | % Hibernate the server instead of going into receive @@ -84,10 +85,10 @@ (Timeout :: timeout()) | % {timeout,Timeout} {'timeout', % Generate a ('timeout', Msg, ...) event after Time Time :: timeout(), Msg :: term()}. --type state_operation() :: +-type transition_action() :: %% These can occur multiple times and are executed in order - %% of appearence in the state_op() list - reply_operation() | + %% of appearence in the transition_op() list + reply_action() | {'next_event', % Insert event as the next to handle EventType :: event_type(), EventContent :: term()} | @@ -101,7 +102,7 @@ MonitorRef :: reference()} | {'unlink', % Unlink and clean up mess(ages) Id :: pid() | port()}. --type reply_operation() :: +-type reply_action() :: {'reply', % Reply to a client Client :: client(), Reply :: term()}. -type state_callback_result() :: @@ -109,34 +110,34 @@ Reason :: term()} | {'stop', % Stop the server Reason :: term(), - NewStateData :: state_data()} | + NewData :: data()} | {'stop', % Stop the server Reason :: term(), - Replies :: [reply_operation()] | reply_operation(), - NewStateData :: state_data()} | - {'next_state', % {next_state,NewState,NewStateData,[]} + Replies :: [reply_action()] | reply_action(), + NewData :: data()} | + {'next_state', % {next_state,NewState,NewData,[]} NewState :: state(), - NewStateData :: state_data()} | + NewData :: data()} | {'next_state', % State transition, maybe to the same state NewState :: state(), - NewStateData :: state_data(), - StateOps :: [state_op()] | state_op()} | - {'keep_state', % {keep_state,NewStateData,[]} - NewStateData :: state_data()} | + NewData :: data(), + Ops :: [transition_op()] | transition_op()} | + {'keep_state', % {keep_state,NewData,[]} + NewData :: data()} | {'keep_state', - NewStateData :: state_data(), - StateOps :: [state_op()] | state_op()} | + NewData :: data(), + Ops :: [transition_op()] | transition_op()} | {'keep_state_and_data'} | % {keep_state_and_data,[]} {'keep_state_and_data', - StateOps :: [state_op()] | state_op()}. + Ops :: [transition_op()] | transition_op()}. %% The state machine init function. It is called only once and %% the server is not running until this function has returned %% an {ok, ...} tuple. Thereafter the state callbacks are called %% for all events to this server. -callback init(Args :: term()) -> - {'ok', state(), state_data()} | - {'ok', state(), state_data(), [state_op()|init_option()]} | + {'ok', state(), data()} | + {'ok', state(), data(), [transition_op()|init_option()]} | 'ignore' | {'stop', Reason :: term()}. @@ -152,7 +153,7 @@ EventContent :: term(), PrevStateName :: state_name() | reference(), StateName :: state_name(), % Current state - StateData :: state_data()) -> + Data :: data()) -> state_callback_result(). %% %% Callback for callback_mode =:= handle_event_function. @@ -164,7 +165,7 @@ EventContent :: term(), PrevState :: state(), State :: state(), % Current state - StateData :: state_data()) -> + Data :: data()) -> state_callback_result(). %% Clean up before the server terminates. @@ -172,7 +173,7 @@ Reason :: 'normal' | 'shutdown' | {'shutdown', term()} | term(), State :: state(), - StateData :: state_data()) -> + Data :: data()) -> any(). %% Note that the new code can expect to get an OldState from @@ -181,9 +182,9 @@ -callback code_change( OldVsn :: term() | {'down', term()}, OldState :: state(), - OldStateData :: state_data(), + OldData :: data(), Extra :: term()) -> - {ok, {NewState :: state(), NewStateData :: state_data()}}. + {ok, {NewState :: state(), NewData :: data()}}. %% Format the callback module state in some sensible that is %% often condensed way. For StatusOption =:= 'normal' the perferred @@ -193,7 +194,7 @@ StatusOption, [ [{Key :: term(), Value :: term()}] | state() | - state_data()]) -> + data()]) -> Status :: term() when StatusOption :: 'normal' | 'terminate'. @@ -264,38 +265,38 @@ event_type(Type) -> -type start_opt() :: debug_opt() | {'timeout', Time :: timeout()} - | {'spawn_opt', SOpts :: [proc_lib:spawn_option()]}. + | {'spawn_opt', [proc_lib:spawn_option()]}. -type start_ret() :: {'ok', pid()} | 'ignore' | {'error', term()}. %% Start a state machine -spec start( - Module :: module(), Args :: term(), Options :: [start_opt()]) -> + Module :: module(), Args :: term(), Opts :: [start_opt()]) -> start_ret(). -start(Module, Args, Options) -> - gen:start(?MODULE, nolink, Module, Args, Options). +start(Module, Args, Opts) -> + gen:start(?MODULE, nolink, Module, Args, Opts). %% -spec start( ServerName :: server_name(), - Module :: module(), Args :: term(), Options :: [start_opt()]) -> + Module :: module(), Args :: term(), Opts :: [start_opt()]) -> start_ret(). -start(ServerName, Module, Args, Options) -> - gen:start(?MODULE, nolink, ServerName, Module, Args, Options). +start(ServerName, Module, Args, Opts) -> + gen:start(?MODULE, nolink, ServerName, Module, Args, Opts). %% Start and link to a state machine -spec start_link( - Module :: module(), Args :: term(), Options :: [start_opt()]) -> + Module :: module(), Args :: term(), Opts :: [start_opt()]) -> start_ret(). -start_link(Module, Args, Options) -> - gen:start(?MODULE, link, Module, Args, Options). +start_link(Module, Args, Opts) -> + gen:start(?MODULE, link, Module, Args, Opts). %% -spec start_link( ServerName :: server_name(), - Module :: module(), Args :: term(), Options :: [start_opt()]) -> + Module :: module(), Args :: term(), Opts :: [start_opt()]) -> start_ret(). -start_link(ServerName, Module, Args, Options) -> - gen:start(?MODULE, link, ServerName, Module, Args, Options). +start_link(ServerName, Module, Args, Opts) -> + gen:start(?MODULE, link, ServerName, Module, Args, Opts). %% Stop a state machine -spec stop(ServerRef :: server_ref()) -> ok. @@ -389,7 +390,7 @@ call(ServerRef, Request, Timeout) -> end. %% Reply from a state machine callback to whom awaits in call/2 --spec reply([reply_operation()] | reply_operation()) -> ok. +-spec reply([reply_action()] | reply_action()) -> ok. reply({reply,{_To,_Tag}=Client,Reply}) -> reply(Client, Reply); reply(Replies) when is_list(Replies) -> @@ -411,39 +412,39 @@ reply({To,Tag}, Reply) -> %% started by proc_lib into a state machine using %% the same arguments as you would have returned from init/1 -spec enter_loop( - Module :: module(), Options :: [debug_opt()], - State :: state(), StateData :: state_data()) -> + Module :: module(), Opts :: [debug_opt()], + State :: state(), Data :: data()) -> no_return(). -enter_loop(Module, Options, State, StateData) -> - enter_loop(Module, Options, State, StateData, self()). +enter_loop(Module, Opts, State, Data) -> + enter_loop(Module, Opts, State, Data, self()). %% -spec enter_loop( - Module :: module(), Options :: [debug_opt()], - State :: state(), StateData :: state_data(), - Server_or_StateOps :: - server_name() | pid() | [state_op()|init_option()]) -> + Module :: module(), Opts :: [debug_opt()], + State :: state(), Data :: data(), + Server_or_Ops :: + server_name() | pid() | [transition_op()|init_option()]) -> no_return(). -enter_loop(Module, Options, State, StateData, Server_or_StateOps) -> +enter_loop(Module, Opts, State, Data, Server_or_Ops) -> if - is_list(Server_or_StateOps) -> + is_list(Server_or_Ops) -> enter_loop( - Module, Options, State, StateData, - self(), Server_or_StateOps); + Module, Opts, State, Data, + self(), Server_or_Ops); true -> enter_loop( - Module, Options, State, StateData, - Server_or_StateOps, []) + Module, Opts, State, Data, + Server_or_Ops, []) end. %% -spec enter_loop( - Module :: module(), Options :: [debug_opt()], - State :: state(), StateData :: state_data(), + Module :: module(), Opts :: [debug_opt()], + State :: state(), Data :: data(), Server :: server_name() | pid(), - StateOps :: [state_op()|init_option()]) -> + Ops :: [transition_op()|init_option()]) -> no_return(). -enter_loop(Module, Options, State, StateData, Server, StateOps) -> +enter_loop(Module, Opts, State, Data, Server, Ops) -> Parent = gen:get_parent(), - enter(Module, Options, State, StateData, Server, StateOps, Parent). + enter(Module, Opts, State, Data, Server, Ops, Parent). %%--------------------------------------------------------------------------- %% API helpers @@ -465,29 +466,29 @@ do_send(Proc, Msg) -> end. %% Here init_it and all enter_loop functions converge -enter(Module, Options, State, StateData, Server, InitOps, Parent) -> +enter(Module, Opts, State, Data, Server, InitOps, Parent) -> Name = gen:get_proc_name(Server), - Debug = gen:debug_options(Name, Options), + Debug = gen:debug_options(Name, Opts), PrevState = undefined, S = #{ callback_mode => state_functions, module => Module, name => Name, prev_state => PrevState, - state => PrevState, % Will be discarded by loop_event_state_ops - state_data => StateData, + state => PrevState, % Will be discarded by loop_event_transition_ops + data => Data, timer => undefined, postponed => [], hibernate => false}, case collect_init_options(InitOps) of - {CallbackMode,StateOps} -> - loop_event_state_ops( + {CallbackMode,Ops} -> + loop_event_transition_ops( Parent, Debug, S#{callback_mode := CallbackMode}, [], {event,undefined}, % Will be discarded by {postpone,false} - PrevState, State, StateData, - StateOps++[{postpone,false}]); + PrevState, State, Data, + Ops++[{postpone,false}]); [Reason] -> ?TERMINATE(Reason, Debug, S, []) end. @@ -495,13 +496,13 @@ enter(Module, Options, State, StateData, Server, InitOps, Parent) -> %%%========================================================================== %%% gen callbacks -init_it(Starter, Parent, ServerRef, Module, Args, Options) -> +init_it(Starter, Parent, ServerRef, Module, Args, Opts) -> try Module:init(Args) of Result -> - init_result(Starter, Parent, ServerRef, Module, Result, Options) + init_result(Starter, Parent, ServerRef, Module, Result, Opts) catch Result -> - init_result(Starter, Parent, ServerRef, Module, Result, Options); + init_result(Starter, Parent, ServerRef, Module, Result, Opts); Class:Reason -> gen:unregister_name(ServerRef), proc_lib:init_ack(Starter, {error,Reason}), @@ -511,18 +512,14 @@ init_it(Starter, Parent, ServerRef, Module, Args, Options) -> %%--------------------------------------------------------------------------- %% gen callbacks helpers -init_result(Starter, Parent, ServerRef, Module, Result, Options) -> +init_result(Starter, Parent, ServerRef, Module, Result, Opts) -> case Result of - {ok,State,StateData} -> + {ok,State,Data} -> proc_lib:init_ack(Starter, {ok,self()}), - enter( - Module, Options, State, StateData, ServerRef, - [], Parent); - {ok,State,StateData,StateOps} -> + enter(Module, Opts, State, Data, ServerRef, [], Parent); + {ok,State,Data,Ops} -> proc_lib:init_ack(Starter, {ok,self()}), - enter( - Module, Options, State, StateData, ServerRef, - StateOps, Parent); + enter(Module, Opts, State, Data, ServerRef, Ops, Parent); {stop,Reason} -> gen:unregister_name(ServerRef), proc_lib:init_ack(Starter, {error,Reason}), @@ -549,32 +546,32 @@ system_terminate(Reason, _Parent, Debug, S) -> system_code_change( #{module := Module, state := State, - state_data := StateData} = S, + data := Data} = S, _Mod, OldVsn, Extra) -> case - try Module:code_change(OldVsn, State, StateData, Extra) + try Module:code_change(OldVsn, State, Data, Extra) catch Result -> Result end of - {ok,{NewState,NewStateData}} -> + {ok,{NewState,NewData}} -> {ok, S#{ state := NewState, - state_data := NewStateData}}; + data := NewData}}; Error -> Error end. -system_get_state(#{state := State, state_data := StateData}) -> - {ok,{State,StateData}}. +system_get_state(#{state := State, data := Data}) -> + {ok,{State,Data}}. system_replace_state( StateFun, #{state := State, - state_data := StateData} = S) -> - {NewState,NewStateData} = Result = StateFun({State,StateData}), - {ok,Result,S#{state := NewState, state_data := NewStateData}}. + data := Data} = S) -> + {NewState,NewData} = Result = StateFun({State,Data}), + {ok,Result,S#{state := NewState, data := NewData}}. format_status( Opt, @@ -642,7 +639,7 @@ wakeup_from_hibernate(Parent, Debug, S) -> loop_receive(Parent, Debug, S). %%%========================================================================== -%%% STate Machine engine implementation of proc_lib/gen server +%%% State Machine engine implementation of proc_lib/gen server %% Server loop, consists of all loop* functions %% and some detours through sys and proc_lib @@ -717,7 +714,7 @@ loop_events( module := Module, prev_state := PrevState, state := State, - state_data := StateData} = S, + data := Data} = S, [{Type,Content} = Event|Events] = Q, Timer) -> _ = (Timer =/= undefined) andalso cancel_timer(Timer), @@ -728,7 +725,7 @@ loop_events( state_functions -> State end, - try Module:Func(Type, Content, PrevState, State, StateData) of + try Module:Func(Type, Content, PrevState, State, Data) of Result -> loop_event_result( Parent, Debug, S, Events, Event, Result) @@ -741,7 +738,7 @@ loop_events( %% of calling a nonexistent state function case erlang:get_stacktrace() of [{Module,Func, - [Type,Content,PrevState,State,StateData]=Args, + [Type,Content,PrevState,State,Data]=Args, _} |Stacktrace] -> terminate( @@ -760,18 +757,18 @@ loop_events( %% Interpret all callback return value variants loop_event_result( Parent, Debug, - #{state := State, state_data := StateData} = S, + #{state := State, data := Data} = S, Events, Event, Result) -> case Result of {stop,Reason} -> ?TERMINATE(Reason, Debug, S, [Event|Events]); - {stop,Reason,NewStateData} -> + {stop,Reason,NewData} -> ?TERMINATE( Reason, Debug, - S#{state_data := NewStateData}, + S#{data := NewData}, [Event|Events]); - {stop,Reason,Reply,NewStateData} -> - NewS = S#{state_data := NewStateData}, + {stop,Reason,Reply,NewData} -> + NewS = S#{data := NewData}, Q = [Event|Events], Replies = if @@ -785,43 +782,43 @@ loop_event_result( exit, Reason, ?STACKTRACE(), Debug, NewS, Q, Replies), %% Since we got back here Replies was bad ?TERMINATE( - {bad_return_value,{stop,Reason,BadReplies,NewStateData}}, + {bad_return_value,{stop,Reason,BadReplies,NewData}}, Debug, NewS, Q); - {next_state,NewState,NewStateData} -> - loop_event_state_ops( + {next_state,NewState,NewData} -> + loop_event_transition_ops( Parent, Debug, S, Events, Event, - State, NewState, NewStateData, []); - {next_state,NewState,NewStateData,StateOps} - when is_list(StateOps) -> - loop_event_state_ops( + State, NewState, NewData, []); + {next_state,NewState,NewData,Ops} + when is_list(Ops) -> + loop_event_transition_ops( Parent, Debug, S, Events, Event, - State, NewState, NewStateData, StateOps); - {keep_state,NewStateData} -> - loop_event_state_ops( + State, NewState, NewData, Ops); + {keep_state,NewData} -> + loop_event_transition_ops( Parent, Debug, S, Events, Event, - State, State, NewStateData, []); - {keep_state,NewStateData,StateOps} -> - loop_event_state_ops( + State, State, NewData, []); + {keep_state,NewData,Ops} -> + loop_event_transition_ops( Parent, Debug, S, Events, Event, - State, State, NewStateData, StateOps); + State, State, NewData, Ops); {keep_state_and_data} -> - loop_event_state_ops( + loop_event_transition_ops( Parent, Debug, S, Events, Event, - State, State, StateData, []); - {keep_state_and_data,StateOps} -> - loop_event_state_ops( + State, State, Data, []); + {keep_state_and_data,Ops} -> + loop_event_transition_ops( Parent, Debug, S, Events, Event, - State, State, StateData, StateOps); + State, State, Data, Ops); _ -> ?TERMINATE( {bad_return_value,Result}, Debug, S, [Event|Events]) end. -loop_event_state_ops( +loop_event_transition_ops( Parent, Debug0, #{postponed := P0} = S, Events, Event, - State, NewState, NewStateData, StateOps) -> - case collect_state_options(StateOps) of - {Postpone,Hibernate,Timeout,Operations} -> + State, NewState, NewData, Ops) -> + case collect_transition_options(Ops) of + {Postpone,Hibernate,Timeout,Actions} -> P1 = % Move current event to postponed if Postpone case Postpone of true -> @@ -837,8 +834,8 @@ loop_event_state_ops( {lists:reverse(P1, Events),[]} end, %% - case process_state_operations( - Operations, Debug0, S, Q2, P2) of + case process_transition_actions( + Actions, Debug0, S, Q2, P2) of {Debug,Q3,P} -> NewDebug = sys_debug( @@ -865,7 +862,7 @@ loop_event_state_ops( S#{ prev_state := State, state := NewState, - state_data := NewStateData, + data := NewData, timer := Timer, hibernate := Hibernate, postponed := P}, @@ -892,92 +889,96 @@ collect_init_options(InitOps) -> collect_init_options([InitOps], state_functions, []) end. %% Keep the last of each kind -collect_init_options([], CallbackMode, StateOps) -> - {CallbackMode,lists:reverse(StateOps)}; -collect_init_options([InitOp|InitOps] = IOIOs, CallbackMode, StateOps) -> +collect_init_options([], CallbackMode, Ops) -> + {CallbackMode,lists:reverse(Ops)}; +collect_init_options( + [InitOp|InitOps] = AllInitOps, CallbackMode, Ops) -> case InitOp of {callback_mode,Mode} when Mode =:= state_functions; Mode =:= handle_event_function -> - collect_init_options(InitOps, Mode, StateOps); + collect_init_options(InitOps, Mode, Ops); {callback_mode,_} -> - [{bad_init_ops,IOIOs}]; - _ -> % Collect others as StateOps + [{bad_init_ops,AllInitOps}]; + _ -> % Collect others as Ops collect_init_options( - InitOps, CallbackMode, [InitOp|StateOps]) + InitOps, CallbackMode, [InitOp|Ops]) end. -collect_state_options(StateOps) -> +collect_transition_options(Ops) -> if - is_list(StateOps) -> - collect_state_options(StateOps, false, false, undefined, []); + is_list(Ops) -> + collect_transition_options( + Ops, false, false, undefined, []); true -> - collect_state_options([StateOps], false, false, undefined, []) + collect_transition_options( + [Ops], false, false, undefined, []) end. %% Keep the last of each kind -collect_state_options( - [], Postpone, Hibernate, Timeout, Operations) -> - {Postpone,Hibernate,Timeout,lists:reverse(Operations)}; -collect_state_options( - [StateOp|StateOps] = SOSOs, Postpone, Hibernate, Timeout, Operations) -> - case StateOp of +collect_transition_options( + [], Postpone, Hibernate, Timeout, Actions) -> + {Postpone,Hibernate,Timeout,lists:reverse(Actions)}; +collect_transition_options( + [Op|Ops] = AllOps, Postpone, Hibernate, Timeout, Actions) -> + case Op of postpone -> - collect_state_options( - StateOps, true, Hibernate, Timeout, Operations); + collect_transition_options( + Ops, true, Hibernate, Timeout, Actions); {postpone,NewPostpone} when is_boolean(NewPostpone) -> - collect_state_options( - StateOps, NewPostpone, Hibernate, Timeout, Operations); + collect_transition_options( + Ops, NewPostpone, Hibernate, Timeout, Actions); {postpone,_} -> - [{bad_state_ops,SOSOs}]; + [{bad_ops,AllOps}]; hibernate -> - collect_state_options( - StateOps, Postpone, true, Timeout, Operations); + collect_transition_options( + Ops, Postpone, true, Timeout, Actions); {hibernate,NewHibernate} when is_boolean(NewHibernate) -> - collect_state_options( - StateOps, Postpone, NewHibernate, Timeout, Operations); + collect_transition_options( + Ops, Postpone, NewHibernate, Timeout, Actions); {hibernate,_} -> - [{bad_state_ops,SOSOs}]; + [{bad_ops,AllOps}]; {timeout,infinity,_} -> % Ignore since it will never time out - collect_state_options( - StateOps, Postpone, Hibernate, undefined, Operations); + collect_transition_options( + Ops, Postpone, Hibernate, undefined, Actions); {timeout,Time,_} = NewTimeout when is_integer(Time), Time >= 0 -> - collect_state_options( - StateOps, Postpone, Hibernate, NewTimeout, Operations); + collect_transition_options( + Ops, Postpone, Hibernate, NewTimeout, Actions); {timeout,_,_} -> - [{bad_state_ops,SOSOs}]; - _ -> % Collect others as operations - collect_state_options( - StateOps, Postpone, Hibernate, Timeout, [StateOp|Operations]) + [{bad_ops,AllOps}]; + _ -> % Collect others as actions + collect_transition_options( + Ops, Postpone, Hibernate, Timeout, [Op|Actions]) end. -process_state_operations([], Debug, _S, Q, P) -> +process_transition_actions([], Debug, _S, Q, P) -> {Debug,Q,P}; -process_state_operations([Operation|Operations] = OOs, Debug, S, Q, P) -> - case Operation of +process_transition_actions( + [Action|Actions] = AllActions, Debug, S, Q, P) -> + case Action of {reply,{_To,_Tag}=Client,Reply} -> NewDebug = do_reply(Debug, S, Client, Reply), - process_state_operations(Operations, NewDebug, S, Q, P); + process_transition_actions(Actions, NewDebug, S, Q, P); {next_event,Type,Content} -> case event_type(Type) of true -> - process_state_operations( - Operations, Debug, S, [{Type,Content}|Q], P); + process_transition_actions( + Actions, Debug, S, [{Type,Content}|Q], P); false -> - [{bad_state_ops,OOs},Debug] + [{bad_ops,AllActions},Debug] end; _ -> - %% All others are remove operations - case remove_fun(Operation) of + %% All others are remove actions + case remove_fun(Action) of false -> - process_state_operations( - Operations, Debug, S, Q, P); + process_transition_actions( + Actions, Debug, S, Q, P); undefined -> - [{bad_state_ops,OOs},Debug]; + [{bad_ops,AllActions},Debug]; RemoveFun when is_function(RemoveFun, 2) -> case remove_event(RemoveFun, Q, P) of {NewQ,NewP} -> - process_state_operations( - Operations, Debug, S, NewQ, NewP); + process_transition_actions( + Actions, Debug, S, NewQ, NewP); Error -> Error ++ [Debug] end; @@ -1023,7 +1024,8 @@ remove_event(RemoveFun, Q, P) -> [Class,Reason,erlang:get_stacktrace()] end. -%% Do the given state operation and create an event removal predicate fun() +%% Do the given transition action and create +%% an event removal predicate fun() remove_fun({remove_event,Type,Content}) -> fun (T, C) when T =:= Type, C =:= Content -> true; (_, _) -> false @@ -1104,9 +1106,9 @@ cancel_timer(TimerRef) -> terminate( Class, Reason, Stacktrace, Debug, #{module := Module, - state := State, state_data := StateData} = S, + state := State, data := Data} = S, Q) -> - try Module:terminate(Reason, State, StateData) of + try Module:terminate(Reason, State, Data) of _ -> ok catch _ -> ok; @@ -1137,7 +1139,7 @@ error_info( Class, Reason, Stacktrace, Debug, #{name := Name, callback_mode := CallbackMode, state := State, postponed := P}, - Q, FmtStateData) -> + Q, FmtData) -> {FixedReason,FixedStacktrace} = case Stacktrace of [{M,F,Args,_}|ST] @@ -1190,7 +1192,7 @@ error_info( [Event|_] -> [Event] end] ++ - [FmtStateData,Class,FixedReason, + [FmtData,Class,FixedReason, State,CallbackMode,length(Q),length(P)] ++ case FixedStacktrace of [] -> @@ -1205,22 +1207,22 @@ error_info( %% Call Module:format_status/2 or return a default value format_status( Opt, PDict, - #{module := Module, state := State, state_data := StateData}) -> + #{module := Module, state := State, data := Data}) -> case erlang:function_exported(Module, format_status, 2) of true -> - try Module:format_status(Opt, [PDict,State,StateData]) + try Module:format_status(Opt, [PDict,State,Data]) catch Result -> Result; _:_ -> - format_status_default(Opt, State, StateData) + format_status_default(Opt, State, Data) end; false -> - format_status_default(Opt, State, StateData) + format_status_default(Opt, State, Data) end. %% The default Module:format_status/2 -format_status_default(Opt, State, StateData) -> - SSD = {State,StateData}, +format_status_default(Opt, State, Data) -> + SSD = {State,Data}, case Opt of terminate -> SSD; diff --git a/lib/stdlib/test/gen_statem_SUITE.erl b/lib/stdlib/test/gen_statem_SUITE.erl index 4ac4acd189..65a8d35645 100644 --- a/lib/stdlib/test/gen_statem_SUITE.erl +++ b/lib/stdlib/test/gen_statem_SUITE.erl @@ -573,10 +573,10 @@ call_format_status(Config) when is_list(Config) -> error_format_status(Config) when is_list(Config) -> error_logger_forwarder:register(), OldFl = process_flag(trap_exit, true), - StateData = "called format_status", + Data = "called format_status", {ok,Pid} = gen_statem:start( - ?MODULE, start_arg(Config, {state_data,StateData}), []), + ?MODULE, start_arg(Config, {data,Data}), []), %% bad return value in the gen_statem loop {{bad_return_value,badreturn},_} = ?EXPECT_FAILURE(gen_statem:call(Pid, badreturn), Reason), @@ -585,7 +585,7 @@ error_format_status(Config) when is_list(Config) -> {Pid, "** State machine"++_, [Pid,{{call,_},badreturn}, - {formatted,idle,StateData}, + {formatted,idle,Data}, exit,{bad_return_value,badreturn}|_]}} -> ok; Other when is_tuple(Other), element(1, Other) =:= error -> @@ -609,10 +609,10 @@ error_format_status(Config) when is_list(Config) -> terminate_crash_format(Config) when is_list(Config) -> error_logger_forwarder:register(), OldFl = process_flag(trap_exit, true), - StateData = crash_terminate, + Data = crash_terminate, {ok,Pid} = gen_statem:start( - ?MODULE, start_arg(Config, {state_data,StateData}), []), + ?MODULE, start_arg(Config, {data,Data}), []), stop_it(Pid), Self = self(), receive @@ -621,7 +621,7 @@ terminate_crash_format(Config) when is_list(Config) -> "** State machine"++_, [Pid, {{call,{Self,_}},stop}, - {formatted,idle,StateData}, + {formatted,idle,Data}, exit,{crash,terminate}|_]}} -> ok; Other when is_tuple(Other), element(1, Other) =:= error -> @@ -647,7 +647,7 @@ get_state(Config) when is_list(Config) -> State = self(), {ok,Pid} = gen_statem:start( - ?MODULE, start_arg(Config, {state_data,State}), []), + ?MODULE, start_arg(Config, {data,State}), []), {idle,State} = sys:get_state(Pid), {idle,State} = sys:get_state(Pid, 5000), stop_it(Pid), @@ -656,7 +656,7 @@ get_state(Config) when is_list(Config) -> %% already checked by the previous test) {ok,Pid2} = gen_statem:start( - {local,gstm}, ?MODULE, start_arg(Config, {state_data,State}), []), + {local,gstm}, ?MODULE, start_arg(Config, {data,State}), []), {idle,State} = sys:get_state(gstm), {idle,State} = sys:get_state(gstm, 5000), stop_it(Pid2), @@ -664,7 +664,7 @@ get_state(Config) when is_list(Config) -> %% check that get_state works when pid is sys suspended {ok,Pid3} = gen_statem:start( - ?MODULE, start_arg(Config, {state_data,State}), []), + ?MODULE, start_arg(Config, {data,State}), []), {idle,State} = sys:get_state(Pid3), ok = sys:suspend(Pid3), {idle,State} = sys:get_state(Pid3, 5000), @@ -676,7 +676,7 @@ replace_state(Config) when is_list(Config) -> State = self(), {ok, Pid} = gen_statem:start( - ?MODULE, start_arg(Config, {state_data,State}), []), + ?MODULE, start_arg(Config, {data,State}), []), {idle,State} = sys:get_state(Pid), NState1 = "replaced", Replace1 = fun({StateName, _}) -> {StateName,NState1} end, @@ -1124,8 +1124,8 @@ init(hiber) -> {ok,hiber_idle,[]}; init(hiber_now) -> {ok,hiber_idle,[],[hibernate]}; -init({state_data, StateData}) -> - {ok,idle,StateData}; +init({data, Data}) -> + {ok,idle,Data}; init({init_ops,Arg,InitOps}) -> case init(Arg) of {ok,State,Data,Ops} -> @@ -1136,7 +1136,7 @@ init({init_ops,Arg,InitOps}) -> Other end; init([]) -> - {ok,idle,state_data}. + {ok,idle,data}. terminate(_, _State, crash_terminate) -> exit({crash,terminate}); @@ -1362,20 +1362,20 @@ unwrap_state(State) -> wrap_result(Result) -> case Result of - {next_state,NewState,NewStateData} -> - {next_state,[NewState],NewStateData}; - {next_state,NewState,NewStateData,StateOps} -> - {next_state,[NewState],NewStateData,StateOps}; + {next_state,NewState,NewData} -> + {next_state,[NewState],NewData}; + {next_state,NewState,NewData,StateOps} -> + {next_state,[NewState],NewData,StateOps}; Other -> Other end. -code_change(_OldVsn, State, StateData, _Extra) -> - {ok,State,StateData}. +code_change(_OldVsn, State, Data, _Extra) -> + {ok,State,Data}. -format_status(terminate, [_Pdict,State,StateData]) -> - {formatted,State,StateData}; -format_status(normal, [_Pdict,_State,_StateData]) -> +format_status(terminate, [_Pdict,State,Data]) -> + {formatted,State,Data}; +format_status(normal, [_Pdict,_State,_Data]) -> [format_status_called]. -- cgit v1.2.3