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 +++++++++++++++++++++----------------- 1 file changed, 124 insertions(+), 98 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 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. +

-- cgit v1.2.3