From b54d82fea10c24359d2a315668b6176fc47963b7 Mon Sep 17 00:00:00 2001 From: Raimo Niskanen Date: Fri, 22 Apr 2016 15:18:07 +0200 Subject: Promote gen_statem over gen_fsm --- lib/stdlib/doc/src/gen_fsm.xml | 16 +++- lib/stdlib/doc/src/gen_server.xml | 3 +- lib/stdlib/doc/src/gen_statem.xml | 187 ++++++++++++++++++++++++-------------- 3 files changed, 137 insertions(+), 69 deletions(-) (limited to 'lib/stdlib/doc/src') diff --git a/lib/stdlib/doc/src/gen_fsm.xml b/lib/stdlib/doc/src/gen_fsm.xml index 4d594b8eb2..835e252704 100644 --- a/lib/stdlib/doc/src/gen_fsm.xml +++ b/lib/stdlib/doc/src/gen_fsm.xml @@ -4,7 +4,7 @@
- 19962014 + 19962016 Ericsson AB. All Rights Reserved. @@ -31,12 +31,23 @@ gen_fsm Generic Finite State Machine Behaviour + +

+ There is a new behaviour + gen_statem + that is intended to replace gen_fsm for new code. + It has the same features and add some really useful. + This module will not be removed for the foreseeable future + to keep old state machine implementations running. +

+

A behaviour module for implementing a finite state machine. A generic finite state machine process (gen_fsm) implemented using this module will have a standard set of interface functions and include functionality for tracing and error reporting. It will also fit into an OTP supervision tree. Refer to - OTP Design Principles for more information.

+ OTP Design Principles for more information. +

A gen_fsm assumes all specific parts to be located in a callback module exporting a pre-defined set of functions. The relationship between the behaviour functions and the callback functions can be @@ -848,6 +859,7 @@ gen_fsm:sync_send_all_state_event -----> Module:handle_sync_event/4 SEE ALSO

gen_event(3), gen_server(3), + gen_statem(3), supervisor(3), proc_lib(3), sys(3)

diff --git a/lib/stdlib/doc/src/gen_server.xml b/lib/stdlib/doc/src/gen_server.xml index 6d04771cd4..10dc978afc 100644 --- a/lib/stdlib/doc/src/gen_server.xml +++ b/lib/stdlib/doc/src/gen_server.xml @@ -4,7 +4,7 @@
- 19962014 + 19962016 Ericsson AB. All Rights Reserved. @@ -715,6 +715,7 @@ gen_server:abcast -----> Module:handle_cast/2 SEE ALSO

gen_event(3), gen_fsm(3), + gen_statem(3), supervisor(3), proc_lib(3), sys(3)

diff --git a/lib/stdlib/doc/src/gen_statem.xml b/lib/stdlib/doc/src/gen_statem.xml index adca3673be..91332fbdde 100644 --- a/lib/stdlib/doc/src/gen_statem.xml +++ b/lib/stdlib/doc/src/gen_statem.xml @@ -34,12 +34,40 @@

A behaviour module for implementing a state machine. Two callback modes - are supported. One for a finite state - machine like gen_fsm - that requires the state to be an atom and use that state as - the name of the callback function for a particular state, + are supported. One for finite state machines + (gen_fsm like) + that requires the state to be an atom and uses that state as + the name of the current callback function, and one without restriction on the state data type - that uses the same callback function for all states. + that uses one callback function for all states. +

+

+ This is a new behaviour in OTP-19.0. + It has been thoroughly reviewed, is stable enough + to be used by at least two heavy OTP applications, and is here to stay. + But depending on user feedback, we do not expect + but might find it necessary to make minor + not backwards compatible changes into OTP-20.0, + so its state can be designated as "not quite experimental"... +

+

+ The gen_statem behaviour is intended to replace + gen_fsm for new code. + It has the same features and add some really useful: +

+ + State code is gathered + The state can be any term + Events can be postponed + Events can be self generated + A reply can be sent from a later state + There can be multiple sys traceable replies + +

+ The callback model(s) for gen_statem differs from + the one for gen_fsm, + but it is still fairly easy to rewrite + from gen_fsm to gen_statem.

A generic state machine process (gen_statem) implemented @@ -148,15 +176,15 @@ erlang:'!' -----> Module:StateName/3 to the state function. That is: as if it is the oldest incoming event. There is a dedicated - event_type() internal + event_type() - that can be used for such events making them impossible + internal that can be used for such events making them impossible to mistake for external events.

Inserting an event replaces the trick of calling your own state handling functions that you often would have to - resort to in for example gen_fsm + resort to in for example gen_fsm to force processing an inserted event before others. 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, @@ -172,9 +200,8 @@ erlang:'!' -----> Module:StateName/3

A gen_statem handles system messages as documented in - sys. - The sys module - can be used for debugging a gen_statem. + sys. + The sysmodule can be used for debugging a gen_statem.

Note that a gen_statem does not trap exit signals @@ -354,7 +381,7 @@ handle_event(_, _, State, Data) ->

Server specification to use when addressing a gen_statem server. - See call/2 and + See call/2 and server_name() @@ -397,7 +424,7 @@ handle_event(_, _, State, Data) ->

Debug option that can be used when starting a gen_statem server through for example - enter_loop/5. + enter_loop/5.

For every entry in Dbgs @@ -412,7 +439,7 @@ handle_event(_, _, State, Data) ->

Options that can be used when starting a gen_statem server through for example - start_link/3. + start_link/3.

@@ -421,7 +448,7 @@ handle_event(_, _, State, Data) ->

Return value from the start functions for_example - start_link/3. + start_link/3.

@@ -432,10 +459,11 @@ handle_event(_, _, State, Data) ->

Destination to use when replying through for example the - action() {reply,From,Reply} + action() + {reply,From,Reply} to a process that has called the gen_statem server using - call/2. + call/2.

@@ -465,7 +493,7 @@ handle_event(_, _, State, Data) ->

A term in which the state machine implementation should store any server data it needs. The difference between - this and the state() + this and the state() itself is that a change in this data does not cause postponed events to be retried. Hence if a change in this data would change the set of events that @@ -498,9 +526,13 @@ handle_event(_, _, State, Data) ->

The callback mode is selected when starting the gen_statem using the return value from - Module:init/1 + Module:init/1 or when calling - enter_loop/5-7. + enter_loop/5-7, + and with the return value from + + Module:code_change/4. +

state_functions @@ -536,7 +568,7 @@ handle_event(_, _, State, Data) -> All - actions + actions are processed in order of appearance. @@ -554,20 +586,22 @@ handle_event(_, _, State, Data) -> All events stored with - action() next_event + action() + next_event are inserted in the queue to be processed before all other events. If an - event_timeout() + event_timeout() is set through - action() timeout + action() + timeout an event timer may be started or a timeout zero event may be enqueued. @@ -622,7 +656,8 @@ handle_event(_, _, State, Data) ->

Generate an event of - type timeout + event_type() + timeout after this time (in milliseconds) unless some other event arrives in which case this timeout is cancelled. Note that a retried or inserted event @@ -652,9 +687,9 @@ handle_event(_, _, State, Data) -> These state transition actions may be invoked by returning them from the state function, - from Module:init/1 + from Module:init/1 or by giving them to - enter_loop/6,7. + enter_loop/6,7.

Actions are executed in the containing list order. @@ -677,20 +712,26 @@ handle_event(_, _, State, Data) -> Set the - transition_option() postpone() + transition_option() + + + postpone() for this state transition. This action is ignored when returned from - Module:init/1 + Module:init/1 or given to - enter_loop/5,6 + enter_loop/5,6 since there is no event to postpone in those cases. hibernate Set the - transition_option() hibernate() + transition_option() + + + hibernate() for this state transition. @@ -703,13 +744,17 @@ handle_event(_, _, State, Data) -> return value {next_state,NextState,NewData,Timeout} allowed like for - gen_fsm Module:StateName/2. + gen_fsm Module:StateName/2. + timeout Set the - transition_option() event_timeout() + transition_option() + + + event_timeout() to Time with EventContent. @@ -906,7 +951,7 @@ handle_event(_, _, State, Data) -> If the option {spawn_opt,SpawnOpts} is present in Opts, SpawnOpts will be passed as option list to - spawn_opt/2 + spawn_opt/2 which is used to spawn the gen_statem process.

@@ -967,7 +1012,7 @@ handle_event(_, _, State, Data) -> to start a child.

- See start_link/3,4 + See start_link/3,4 for a description of arguments and return values.

@@ -979,7 +1024,9 @@ handle_event(_, _, State, Data) ->

The same as - stop(ServerRef, normal, infinity). + + stop(ServerRef, normal, infinity). +

@@ -996,7 +1043,7 @@ handle_event(_, _, State, Data) -> and waits for it to terminate. The gen_statem will call - Module:terminate/3 + Module:terminate/3 before exiting.

@@ -1005,7 +1052,9 @@ handle_event(_, _, State, Data) -> with the expected reason. Any other reason than normal, shutdown, or {shutdown,Term} will cause an error report to be issued through - error_logger:format/2. + + error_logger:format/2. + The default Reason is normal.

@@ -1125,7 +1174,7 @@ handle_event(_, _, State, Data) ->

A reply sent with this function will not be visible - in sys debug output. + in sys debug output.

@@ -1194,7 +1243,9 @@ handle_event(_, _, State, Data) -> Module, Opts and Server have the same meanings as when calling - gen_statem:start[_link]/3,4. + + gen_statem:start[_link]/3,4. + However, the server_name() @@ -1205,7 +1256,7 @@ handle_event(_, _, State, Data) -> CallbackMode, State, Data and Actions have the same meanings as in the return value of - Module:init/1. + Module:init/1. Also, the callback module Module does not need to export an init/1 function.

@@ -1259,9 +1310,9 @@ handle_event(_, _, State, Data) ->

Whenever a gen_statem is started using - start_link/3,4 + start_link/3,4 or - start/3,4, + start/3,4, this function is called by the new process to initialize the implementation state and server data.

@@ -1277,9 +1328,9 @@ handle_event(_, _, State, Data) -> callback mode. of the gen_statem. State is the initial - state() + state() and Data the initial server - data(). + data().

The Actions @@ -1291,11 +1342,11 @@ handle_event(_, _, State, Data) -> If something goes wrong during the initialization the function should return {stop,Reason} or ignore. See - start_link/3,4. + start_link/3,4.

This function may use - throw + throw/1 to return Result.

@@ -1339,8 +1390,8 @@ handle_event(_, _, State, Data) ->

Whenever a gen_statem receives an event from - call/2, - cast/2 or + call/2, + cast/2 or as a normal process message one of these functions is called. If callback mode is state_functions then Module:StateName/3 is called, @@ -1354,8 +1405,8 @@ handle_event(_, _, State, Data) -> from this or from any other state function by returning with {reply,From,Reply} in - Actions, in - Replies + Actions, in + Replies or by calling reply(From, Reply).

@@ -1371,13 +1422,13 @@ handle_event(_, _, State, Data) -> there is no restriction on the next state.

- See action() + See action() 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, + throw/1, to return the result.

@@ -1402,7 +1453,7 @@ handle_event(_, _, State, Data) -> value is ignored.

Reason is a term denoting the stop reason and - State + State is the internal state of the gen_statem.

@@ -1410,7 +1461,7 @@ handle_event(_, _, State, Data) -> is terminating. If it is because another callback function has returned a stop tuple {stop,Reason} in - Actions, + Actions, Reason will have the value specified in that tuple. If it is due to a failure, Reason is the error reason.

@@ -1445,11 +1496,13 @@ handle_event(_, _, State, Data) -> shutdown, or {shutdown,Term} the gen_statem is assumed to terminate due to an error and an error report is issued using - error_logger:format/2. + + error_logger:format/2. +

This function may use - throw + throw/1 to return Ignored, which is ignored anyway.

@@ -1504,7 +1557,9 @@ handle_event(_, _, State, Data) ->

If you would dare to change - callback mode + + callback mode + during release upgrade/downgrade, the upgrade is no problem since the new code surely knows what callback mode it needs, but for a downgrade this function will have to @@ -1534,7 +1589,7 @@ handle_event(_, _, State, Data) -> upgrade will fail and roll back to the old release.

This function may use - throw + throw/1 to return Result or Reason.

@@ -1640,7 +1695,7 @@ handle_event(_, _, State, Data) ->

This function may use - throw + throw/1 to return Status.

@@ -1650,11 +1705,11 @@ handle_event(_, _, State, Data) ->
SEE ALSO -

gen_event, - gen_fsm, - gen_server, - supervisor, - proc_lib, - sys

+

gen_event(3), + gen_fsm(3), + gen_server(3), + supervisor(3), + proc_lib(3), + sys(3)

-- cgit v1.2.3