From 35985299ae5414fb448d9961071f722ce209f0b6 Mon Sep 17 00:00:00 2001 From: Raimo Niskanen Date: Fri, 20 Jan 2017 16:22:15 +0100 Subject: Change arity of type to init_result/1 --- lib/stdlib/doc/src/gen_statem.xml | 67 +++++++++++++++++++-------------------- 1 file changed, 32 insertions(+), 35 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 fd498ee82e..6fa2d86e0b 100644 --- a/lib/stdlib/doc/src/gen_statem.xml +++ b/lib/stdlib/doc/src/gen_statem.xml @@ -4,7 +4,7 @@
- 2016 + 2016-2017 Ericsson AB. All Rights Reserved. @@ -982,6 +982,33 @@ handle_event(_, _, State, Data) ->

+ + + +

+ For a succesful initialization, + State is the initial + state() + and Data the initial server + data() + of the gen_statem. +

+

+ The Actions + are executed when entering the first + state just as for a + state callback, + except that the action postpone is forced to + false since there is no event to postpone. +

+

+ For an unsuccesful initialization, + {stop,Reason} + or ignore should be used; see + start_link/3,4. +

+ + @@ -1613,25 +1640,16 @@ handle_event(_, _, State, Data) -> - Module:init(Args) -> Result + Module:init(Args) -> Result(StateType) Optional function for initializing process and internal state. Args = term() - Result = {ok,State,Data} -  | {ok,State,Data,Actions} -  | {stop,Reason} | ignore - State = state() - - Data = data() - - Actions = - [action()] | - action() + Result(StateType) = + init_result(StateType) - Reason = term() @@ -1644,30 +1662,9 @@ handle_event(_, _, State, Data) -> the implementation state and server data.

- Args is the Args argument provided to the start + Args is the Args argument provided to that start function.

-

- If the initialization is successful, the function is to - return {ok,State,Data} or - {ok,State,Data,Actions}. - State is the initial - state() - and Data the initial server - data(). -

-

- The Actions - are executed when entering the first - state just as for a - state callback. -

-

- If the initialization fails, - the function is to return {stop,Reason} - or ignore; see - start_link/3,4. -

This callback is optional, so a callback module does not need -- cgit v1.2.3 From 85e9fed232a6d89e3659cabbb2169cf3e21127e3 Mon Sep 17 00:00:00 2001 From: Raimo Niskanen Date: Tue, 24 Jan 2017 14:15:26 +0100 Subject: Implement repeat_state and repeat_state_and_data --- lib/stdlib/doc/src/gen_statem.xml | 82 +++++++++++++++++++++++++++++++++------ 1 file changed, 71 insertions(+), 11 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 6fa2d86e0b..b20abbea5d 100644 --- a/lib/stdlib/doc/src/gen_statem.xml +++ b/lib/stdlib/doc/src/gen_statem.xml @@ -587,8 +587,8 @@ handle_event(_, _, State, Data) ->

- If the state machine should use state enter calls - is selected when starting the gen_statem + Whether the state machine should use state enter calls + or not is selected when starting the gen_statem and after code change using the return value from Module:callback_mode/0.

@@ -606,7 +606,16 @@ handle_event(_, _, State, Data) -> See Module:StateName/3 and - Module:handle_event/4. + Module:handle_event/4. + Such a call can be repeated by returning a + + repeat_state + + or + + repeat_state_and_data + + tuple from the state callback.

If @@ -625,7 +634,8 @@ handle_event(_, _, State, Data) -> right before entering the initial state even though this formally is not a state change. In this case OldState will be the same as State, - which can not happen for a subsequent state change. + which can not happen for a subsequent state change, + but will happen when repeating the state enter call.

@@ -640,7 +650,15 @@ handle_event(_, _, State, Data) ->

- If the state changes or is the initial state, and + If the state changes, is the initial state, + + repeat_state + + or + + repeat_state_and_data + + is used, and also state enter calls are used, the gen_statem calls the new state callback with arguments @@ -1095,6 +1113,37 @@ handle_event(_, _, State, Data) -> {next_state,CurrentState,CurrentData,Actions}.

+ repeat_state + +

+ The gen_statem keeps the current state, or + does a state transition to the current state if you like, + sets NewData, + and executes all Actions. + If the gen_statem runs with + state enter calls, + the state enter call is repeated, see type + transition_option(), + otherwise repeat_state is the same as + keep_state. +

+ + repeat_state_and_data + +

+ The gen_statem keeps the current state and data, or + does a state transition to the current state if you like, + and executes all Actions. + This is the same as + {repeat_state,CurrentData,Actions}. + If the gen_statem runs with + state enter calls, + the state enter call is repeated, see type + transition_option(), + otherwise repeat_state_and_data is the same as + keep_state_and_data. +

+ stop

@@ -1870,22 +1919,33 @@ handle_event(_, _, State, Data) -> actions that may be returned: postpone() - and + is not allowed since a state enter call is not + an event so there is no event to postpone, and {next_event,_,_} - are not allowed. + is not allowed since using state enter calls + should not affect how events are consumed and produced. You may also not change states from this call. Should you return {next_state,NextState, ...} with NextState =/= State the gen_statem crashes. - You are advised to use {keep_state,...} or - keep_state_and_data. + It is possible to use {repeat_state, ...}, + {repeat_state_and_data,_} or + repeat_state_and_data but all of them makes little + sense since you immediately will be called again with a new + state enter call making this just a weird way + of looping, and there are better ways to loop in Erlang. + You are advised to use {keep_state,...}, + {keep_state_and_data,_} or + keep_state_and_data since you can not change states + from a state enter call anyway.

Note the fact that you can use throw to return the result, which can be useful. For example to bail out with throw(keep_state_and_data) - from deep within complex code that is in no position to - return {next_state,State,Data}. + from deep within complex code that can not + return {next_state,State,Data} because + State or Data is no longer in scope.

-- cgit v1.2.3 From f1365135f1dd0b57849317b77e8bc9a1e0fd6307 Mon Sep 17 00:00:00 2001 From: Raimo Niskanen Date: Wed, 22 Feb 2017 15:50:07 +0100 Subject: Clarify code_change and callback mode change --- lib/stdlib/doc/src/gen_statem.xml | 13 +++++++++++++ 1 file changed, 13 insertions(+) (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 b20abbea5d..d19602b67c 100644 --- a/lib/stdlib/doc/src/gen_statem.xml +++ b/lib/stdlib/doc/src/gen_statem.xml @@ -1685,6 +1685,19 @@ handle_event(_, _, State, Data) -> It is recommended to use an atom as Reason since it will be wrapped in an {error,Reason} tuple.

+

+ Also note when upgrading a gen_statem, + this function and hence + the Change={advanced,Extra} parameter in the + appup file + is not only needed to update the internal state + or to act on the Extra argument. + It is also needed if an upgrade or downgrade should change + callback mode, + or else the callback mode after the code change + will not be honoured, + most probably causing a server crash. +

-- cgit v1.2.3 From 913d0b52df1e029fb1728b44ba7da318f3dc49dd Mon Sep 17 00:00:00 2001 From: Raimo Niskanen Date: Wed, 22 Feb 2017 15:41:26 +0100 Subject: Implement fallback for terminate/3 --- lib/stdlib/doc/src/gen_statem.xml | 5 +++++ 1 file changed, 5 insertions(+) (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 d19602b67c..5eb13db1aa 100644 --- a/lib/stdlib/doc/src/gen_statem.xml +++ b/lib/stdlib/doc/src/gen_statem.xml @@ -1973,6 +1973,11 @@ handle_event(_, _, State, Data) -> Ignored = term() + +

This callback is optional, so callback modules need not + export it. The gen_statem module provides a default + implementation without cleanup.

+

This function is called by a gen_statem when it is about to terminate. It is to be the opposite of -- cgit v1.2.3