From 26b3c7d60d52d8a7be006b06d856bb0f7276e77a Mon Sep 17 00:00:00 2001 From: Raimo Niskanen Date: Thu, 21 Apr 2016 15:58:52 +0200 Subject: Modify code_change/4 to return CallbackMode Also move check of non-atom states in callback mode state_functions to where the state function is called. This gives homogenous diagnostics for state functions, code_change/4 and system_replace_state StateFun. Irregularities pointed out by James Fish. --- lib/stdlib/doc/src/gen_statem.xml | 71 ++++++++++++++++++++++++--------------- 1 file changed, 44 insertions(+), 27 deletions(-) (limited to 'lib/stdlib/doc/src') diff --git a/lib/stdlib/doc/src/gen_statem.xml b/lib/stdlib/doc/src/gen_statem.xml index c21398d64d..adca3673be 100644 --- a/lib/stdlib/doc/src/gen_statem.xml +++ b/lib/stdlib/doc/src/gen_statem.xml @@ -32,8 +32,9 @@ Generic State Machine Behaviour

- A behaviour module for implementing a state machine. - Two callback modes are supported. One for a finite state + 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, @@ -89,13 +90,13 @@ erlang:'!' -----> Module:StateName/3 The "state function" for a specific state in a gen_statem is the callback function that is called - for all events in this state, and is selected depending on - callback_mode + for all events in this state, and is selected depending on which + callback mode that the implementation specifies when the the server starts.

- When - callback_mode + When the + callback mode is state_functions, the state has to be an atom and is used as the state function name. See @@ -110,7 +111,8 @@ erlang:'!' -----> Module:StateName/3 makes the state name terminate unusable.

- When callback_mode + When the + callback mode is handle_event_function the state can be any term and the state function name is @@ -208,9 +210,7 @@ erlang:'!' -----> Module:StateName/3

This example shows a simple pushbutton model for a toggling pushbutton implemented with - - callback_mode() - + callback mode state_functions. You can push the button and it replies if it went on or off, and you can ask for a count of how many times it has been @@ -226,6 +226,7 @@ erlang:'!' -----> Module:StateName/3 -export([on/3,off/3]). name() -> pushbutton_statem. % The registered server name +callback_mode() -> state_functions. %% API. This example uses a registered name name() %% and does not link to the caller. @@ -242,12 +243,12 @@ stop() -> terminate(_Reason, _State, _Data) -> void. code_change(_Vsn, State, Data, _Extra) -> - {ok,State,Data}. + {callback_mode(),State,Data}. init([]) -> %% Set the callback mode and initial state + data. %% Data is used only as a counter. State = off, Data = 0, - {state_functions,State,Data}. + {callback_mode(),State,Data}. %%% State functions @@ -297,9 +298,7 @@ ok

And just to compare styles here is the same example using - - callback_mode - + callback mode state_functions, or rather here is code to replace from the init/1 function of the pushbutton.erl example file above: @@ -453,10 +452,8 @@ handle_event(_, _, State, Data) ->

- If - - callback_mode - + If the + callback mode is state_functions, the state has to be of this type.

@@ -499,7 +496,7 @@ handle_event(_, _, State, Data) ->

- The callback_mode is selected when starting the + The callback mode is selected when starting the gen_statem using the return value from Module:init/1 or when calling @@ -1277,7 +1274,7 @@ handle_event(_, _, State, Data) -> return {CallbackMode,State,Data} or {CallbackMode,State,Data,Actions}. CallbackMode selects the - callback_mode(). + callback mode. of the gen_statem. State is the initial state() @@ -1344,8 +1341,8 @@ handle_event(_, _, State, Data) -> Whenever a gen_statem receives an event from call/2, cast/2 or - as a normal process message one of these functions is called. - If callback_mode + as a normal process message one of these functions is called. If + callback mode is state_functions then Module:StateName/3 is called, and if it is handle_event_function then Module:handle_event/4 is called. @@ -1468,7 +1465,11 @@ handle_event(_, _, State, Data) ->   Vsn = term() OldState = NewState = term() Extra = term() - Result = {ok,NewState,NewData} | Reason + Result = {NewCallbackMode,NewState,NewData} | Reason + + NewCallbackMode = + callback_mode() + OldState = NewState = state() @@ -1484,8 +1485,9 @@ handle_event(_, _, State, Data) -> This function is called by a gen_statem when it should update its internal state during a release upgrade/downgrade, that is when the instruction {update,Module,Change,...} - where Change={advanced,Extra} is given in - the appup file. See + where Change={advanced,Extra} is given in the + appup + file. See OTP Design Principles @@ -1499,6 +1501,21 @@ handle_event(_, _, State, Data) -> Module. If no such attribute is defined, the version is the checksum of the BEAM file.

+ +

+ If you would dare to change + 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 + know from the Extra argument that comes from the + appup + file what callback mode the old code did use. + It may also be possible to figure this out + from the {down,Vsn} argument since Vsn + in effect defines the old callback module version. +

+

OldState and OldData is the internal state of the gen_statem. @@ -1510,7 +1527,7 @@ handle_event(_, _, State, Data) ->

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

If the function returns Reason, the ongoing -- cgit v1.2.3