From 1958b93b4aa90883be5102d465f67f167549dea9 Mon Sep 17 00:00:00 2001 From: Raimo Niskanen Date: Wed, 24 Feb 2016 09:41:34 +0100 Subject: Ditch State so StateName/5 -> StateName/4 --- lib/stdlib/doc/src/gen_statem.xml | 64 ++++++++++++++++++++++----------------- 1 file changed, 36 insertions(+), 28 deletions(-) (limited to 'lib/stdlib/doc') diff --git a/lib/stdlib/doc/src/gen_statem.xml b/lib/stdlib/doc/src/gen_statem.xml index 096be3025e..8934d912c6 100644 --- a/lib/stdlib/doc/src/gen_statem.xml +++ b/lib/stdlib/doc/src/gen_statem.xml @@ -62,7 +62,7 @@ gen_statem:stop -----> Module:terminate/2 gen_statem:call gen_statem:cast erlang:send -erlang:'!' -----> Module:StateName/5 +erlang:'!' -----> Module:StateName/4 Module:handle_event/5 - -----> Module:terminate/3 @@ -84,18 +84,28 @@ erlang:'!' -----> Module:StateName/5 in a gen_statem is the callback function that is called for all events in this state, and is selected depending on callback_mode - that the implementation selects during gen_statem init. + that the implementation specifies during gen_statem init.

When callback_mode is state_functions the state has to be an atom and is used as the state function name. See - - Module:StateName/5 + + Module:StateName/4 . This gathers all code for a specific state in one function and hence dispatches on state first. + Note that in this mode the callback function + + Module:code_change/4 + makes the state name code_change + unusable. Actually you might get away with using it + as a state name but you will have to find a way to separate + the two callback roles e.g by observing that you can force + argument 3 into having different types for the different roles. + This is a slippery slope, though. It is easier + to simply not use code_change as a state name.

When callback_mode @@ -110,13 +120,11 @@ erlang:'!' -----> Module:StateName/5 states so you do not accidentally postpone one event forever creating an infinite busy loop.

-

Any state name or any state value (depending on - callback_mode) - is permitted with a small gotcha regarding the state - undefined that is used as the previous state when - the first gen_statem state function is called. - You might need to know about this faked state if you - inspect the previous state argument in your state functions. +

There is a small gotcha in both callback modes regarding + the state undefined that is used as the previous state + when the first state function is called. So either do not + use undefined as a state, or figure out + the implications yourself.

The gen_statem enqueues incoming events in order of arrival and presents these to the @@ -181,7 +189,7 @@ erlang:'!' -----> Module:StateName/5 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 - something you'd want to do between each event on a busy server. + something you would want to do between each event on a busy server.

@@ -350,13 +358,20 @@ erlang:'!' -----> Module:StateName/5 +

+ The callback_mode is selected when starting the + gen_statem using the return value from + Module:init/1 + or when calling + enter_loop/5-7. +

state_functions The state has to be of type state_name() and one callback function per state that is - - Module:StateName/5 + + Module:StateName/4 is used. This is the default. handle_event_function @@ -384,7 +399,7 @@ erlang:'!' -----> Module:StateName/5 state function, from Module:init/1 or given to - enter_loop/5,6. + enter_loop/6,7.

The processing order for a state change is:

@@ -990,7 +1005,7 @@ erlang:'!' -----> Module:StateName/5 Module:StateName(EventType, EventContent, - PrevStateName, StateName, Data) -> Result + PrevStateName, Data) -> Result Module:handle_event(EventType, EventContent, PrevState, State, Data) -> Result @@ -1004,9 +1019,6 @@ erlang:'!' -----> Module:StateName/5 PrevStateName = state_name() - StateName = - state_name() - PrevState = State = state() @@ -1023,10 +1035,9 @@ erlang:'!' -----> Module:StateName/5

Whenever a gen_statem receives an event from call/2, cast/2 or - as a normal process message this function is called. - If - callback_mode - is state_functions then Module:StateName/5 is called, + as a normal process message one of these functions is called. + If callback_mode + is state_functions then Module:StateName/4 is called, and if it is handle_event_function then Module:handle_event/5 is called.

@@ -1043,13 +1054,10 @@ erlang:'!' -----> Module:StateName/5 reply(Caller, Reply) .

-

StateName is useful in some odd cases for example - if you call a common event handling function from your state - function then you might want to pass StateName. -

PrevStateName and PrevState are useful in some odd cases for example when you want to do something - only at the first event in a state. + only at the first event in a state, or when you need to + handle events differently depending on the previous state. Note that when gen_statem enters its first state this is set to undefined.

-- cgit v1.2.3