aboutsummaryrefslogtreecommitdiffstats
path: root/lib
diff options
context:
space:
mode:
Diffstat (limited to 'lib')
-rw-r--r--lib/stdlib/doc/src/gen_statem.xml82
-rw-r--r--lib/stdlib/src/gen_statem.erl208
-rw-r--r--lib/stdlib/test/gen_statem_SUITE.erl66
3 files changed, 287 insertions, 69 deletions
diff --git a/lib/stdlib/doc/src/gen_statem.xml b/lib/stdlib/doc/src/gen_statem.xml
index 17f1526a21..a4c5438a08 100644
--- a/lib/stdlib/doc/src/gen_statem.xml
+++ b/lib/stdlib/doc/src/gen_statem.xml
@@ -70,6 +70,7 @@
<item>The state can be any term.</item>
<item>Events can be postponed.</item>
<item>Events can be self-generated.</item>
+ <item>Automatic state entry events can be generated.</item>
<item>A reply can be sent from a later state.</item>
<item>There can be multiple <c>sys</c> traceable replies.</item>
</list>
@@ -193,6 +194,12 @@ erlang:'!' -----> Module:StateName/3
<seealso marker="gen_fsm"><c>gen_fsm</c></seealso>
to force processing an inserted event before others.
</p>
+ <p>
+ The <c>gen_statem</c> engine can automatically insert
+ a special event whenever a new state is entered; see
+ <seealso marker="#type-state_entry_mode"><c>state_entry_mode()</c></seealso>.
+ This makes it easy to handle code common to all state entries.
+ </p>
<note>
<p>If you in <c>gen_statem</c>, for example, postpone
an event in one state and then call another state function
@@ -515,7 +522,7 @@ handle_event(_, _, State, Data) ->
Type <c>info</c> originates from regular process messages sent
to the <c>gen_statem</c>. Also, the state machine
implementation can generate events of types
- <c>timeout</c> and <c>internal</c> to itself.
+ <c>timeout</c>, <c>enter</c> and <c>internal</c> to itself.
</p>
</desc>
</datatype>
@@ -551,6 +558,34 @@ handle_event(_, _, State, Data) ->
</desc>
</datatype>
<datatype>
+ <name name="state_entry_mode"/>
+ <desc>
+ <p>
+ The <em>state entry mode</em> is selected when starting the
+ <c>gen_statem</c> and after code change
+ using the return value from
+ <seealso marker="#Module:callback_mode/0"><c>Module:callback_mode/0</c></seealso>.
+ </p>
+ <p>
+ If
+ <seealso marker="#Module:callback_mode/0"><c>Module:callback_mode/0</c></seealso>
+ returns a list containing <c>state_entry_events</c>,
+ the <c>gen_statem</c> engine will, at every state change,
+ insert an event of type
+ <seealso marker="#type-event_type">enter</seealso>
+ with content <c>OldState</c>. This event will be inserted
+ before all other events such as those generated by
+ <seealso marker="#type-action"><c>action()</c></seealso>
+ <c>next_event</c>.
+ </p>
+ <p>
+ If
+ <seealso marker="#Module:callback_mode/0"><c>Module:callback_mode/0</c></seealso>
+ does not return such a list, no state entry events are inserted.
+ </p>
+ </desc>
+ </datatype>
+ <datatype>
<name name="transition_option"/>
<desc>
<p>
@@ -591,6 +626,16 @@ handle_event(_, _, State, Data) ->
</p>
</item>
<item>
+ <p>
+ If the state changes or is the initial state, and the
+ <seealso marker="#type-state_entry_mode"><em>state entry mode</em></seealso>
+ is <c>state_entry_events</c>, an event of type
+ <seealso marker="#type-event_type">enter</seealso>
+ with content <c>OldState</c> is inserted
+ to be processed before all other events including those above.
+ </p>
+ </item>
+ <item>
<p>
If an
<seealso marker="#type-event_timeout"><c>event_timeout()</c></seealso>
@@ -1288,7 +1333,9 @@ handle_event(_, _, State, Data) ->
<type>
<v>
CallbackMode =
- <seealso marker="#type-callback_mode">callback_mode()</seealso>
+ <seealso marker="#type-callback_mode">callback_mode()</seealso> |
+ [ <seealso marker="#type-callback_mode">callback_mode()</seealso>
+ | state_entry_events ]
</v>
</type>
<desc>
@@ -1313,12 +1360,35 @@ handle_event(_, _, State, Data) ->
<seealso marker="#Module:code_change/4"><c>Module:code_change/4</c></seealso>
returns.
</p>
+ <p>
+ The <c>CallbackMode</c> is either just
+ <seealso marker="#type-callback_mode">callback_mode()</seealso>
+ or a list containing
+ <seealso marker="#type-callback_mode">callback_mode()</seealso>
+ and possibly the atom
+ <seealso marker="#type-state_entry_mode"><c>state_entry_events</c></seealso>.
+ </p>
+ <p>
+ If the atom <c>state_entry_events</c> is present in the list,
+ the <c>gen_statem</c> engine will, at every state change,
+ insert an event of type
+ <seealso marker="#type-event_type">enter</seealso>
+ with content <c>OldState</c>. This event will be inserted
+ before all other events such as those generated by
+ <seealso marker="#type-action"><c>action()</c></seealso>
+ <c>next_event</c>.
+ </p>
+ <p>
+ No state entry event will be inserted after a
+ <seealso marker="#Module:code_change/4"><c>Module:code_change/4</c></seealso>
+ since transforming the state to a newer version is regarded
+ as staying in the same state even if the newer version state
+ should have a different name.
+ </p>
<note>
<p>
- If this function's body does not consist of solely one of two
- possible
- <seealso marker="#type-callback_mode">atoms</seealso>
- the callback module is doing something strange.
+ If this function's body does not return an inline constant
+ value the callback module is doing something strange.
</p>
</note>
</desc>
diff --git a/lib/stdlib/src/gen_statem.erl b/lib/stdlib/src/gen_statem.erl
index 46c0e92a9b..7f437404ed 100644
--- a/lib/stdlib/src/gen_statem.erl
+++ b/lib/stdlib/src/gen_statem.erl
@@ -53,7 +53,7 @@
action/0]).
%% Fix problem for doc build
--export_type([transition_option/0]).
+-export_type([state_entry_mode/0,transition_option/0]).
%%%==========================================================================
%%% Interface functions.
@@ -72,9 +72,10 @@
-type event_type() ::
{'call',From :: from()} | 'cast' |
- 'info' | 'timeout' | 'internal'.
+ 'info' | 'timeout' | 'enter' | 'internal'.
-type callback_mode() :: 'state_functions' | 'handle_event_function'.
+-type state_entry_mode() :: 'state_entry_events'.
-type transition_option() ::
postpone() | hibernate() | event_timeout().
@@ -183,7 +184,9 @@
%%
%% It is called once after init/0 and code_change/4 but before
%% the first state callback StateName/3 or handle_event/4.
--callback callback_mode() -> callback_mode().
+-callback callback_mode() ->
+ callback_mode() |
+ [callback_mode() | state_entry_mode()].
%% Example state callback for StateName = 'state_name'
%% when callback_mode() =:= state_functions.
@@ -556,19 +559,27 @@ enter(Module, Opts, State, Data, Server, Actions, Parent) ->
end,
S = #{
callback_mode => undefined,
+ state_entry_events => false,
module => Module,
name => Name,
- %% All fields below will be replaced according to the arguments to
+ %% The rest of the fields are set from to the arguments to
%% loop_event_actions/10 when it finally loops back to loop/3
- state => State,
- data => Data,
- postponed => P,
- hibernate => false,
- timer => undefined},
+ %% in loop_events_done/8
+ %%
+ %% Marker for initial state, cleared immediately when used
+ init_state => true
+ },
NewDebug = sys_debug(Debug, S, State, {enter,Event,State}),
- loop_event_actions(
- Parent, NewDebug, S, Events,
- State, Data, P, Event, State, NewActions).
+ case call_callback_mode(S) of
+ {ok,NewS} ->
+ loop_event_actions(
+ Parent, NewDebug, NewS, Events,
+ State, Data, P, Event, State, NewActions);
+ {Class,Reason,Stacktrace} ->
+ terminate(
+ Class, Reason, Stacktrace,
+ NewDebug, S, [Event|Events], State, Data, P)
+ end.
%%%==========================================================================
%%% gen callbacks
@@ -866,13 +877,93 @@ loop_events(
loop_events_done(Parent, Debug, S, Timer, State, Data, P, Hibernate) ->
NewS =
S#{
- state := State,
- data := Data,
- postponed := P,
- hibernate := Hibernate,
- timer := Timer},
+ state => State,
+ data => Data,
+ postponed => P,
+ hibernate => Hibernate,
+ timer => Timer},
loop(Parent, Debug, NewS).
+
+
+parse_callback_mode([], CBMode, SEntry) ->
+ {CBMode,SEntry};
+parse_callback_mode([H|T], CBMode, SEntry) ->
+ case callback_mode(H) of
+ true ->
+ parse_callback_mode(T, H, SEntry);
+ false ->
+ case H of
+ state_entry_events ->
+ parse_callback_mode(T, CBMode, true);
+ _ ->
+ {undefined,SEntry}
+ end
+ end;
+parse_callback_mode(_, _CBMode, SEntry) ->
+ {undefined,SEntry}.
+
+call_callback_mode(S, CallbackMode) ->
+ case
+ parse_callback_mode(
+ if
+ is_atom(CallbackMode) ->
+ [CallbackMode];
+ true ->
+ CallbackMode
+ end, undefined, false)
+ of
+ {undefined,_} ->
+ {error,
+ {bad_return_from_callback_mode,CallbackMode},
+ ?STACKTRACE()};
+ {CBMode,SEntry} ->
+ {ok,
+ S#{
+ callback_mode := CBMode,
+ state_entry_events := SEntry}}
+ end.
+
+call_callback_mode(#{module := Module} = S) ->
+ try Module:callback_mode() of
+ CallbackMode ->
+ call_callback_mode(S, CallbackMode)
+ catch
+ CallbackMode ->
+ call_callback_mode(S, CallbackMode);
+ error:undef ->
+ %% Process undef to check for the simple mistake
+ %% of calling a nonexistent state function
+ %% to make the undef more precise
+ case erlang:get_stacktrace() of
+ [{Module,callback_mode,[]=Args,_}
+ |Stacktrace] ->
+ {error,
+ {undef_callback,{Module,callback_mode,Args}},
+ Stacktrace};
+ Stacktrace ->
+ {error,undef,Stacktrace}
+ end;
+ Class:Reason ->
+ {Class,Reason,erlang:get_stacktrace()}
+ end.
+
+loop_event(
+ Parent, Debug,
+ #{callback_mode := undefined} = S,
+ Events,
+ State, Data, P, Event, Hibernate) ->
+ %% This happens after code_change/4
+ case call_callback_mode(S) of
+ {ok,NewS} ->
+ loop_event(
+ Parent, Debug, NewS, Events,
+ State, Data, P, Event, Hibernate);
+ {Class,Reason,Stacktrace} ->
+ terminate(
+ Class, Reason, Stacktrace,
+ Debug, S, [Event|Events], State, Data, P)
+ end;
loop_event(
Parent, Debug,
#{callback_mode := CallbackMode,
@@ -891,24 +982,16 @@ loop_event(
%%
try
case CallbackMode of
- undefined ->
- Module:callback_mode();
state_functions ->
erlang:apply(Module, State, [Type,Content,Data]);
handle_event_function ->
Module:handle_event(Type, Content, State, Data)
end
of
- Result when CallbackMode =:= undefined ->
- loop_event_callback_mode(
- Parent, Debug, S, Events, State, Data, P, Event, Result);
Result ->
loop_event_result(
Parent, Debug, S, Events, State, Data, P, Event, Result)
catch
- Result when CallbackMode =:= undefined ->
- loop_event_callback_mode(
- Parent, Debug, S, Events, State, Data, P, Event, Result);
Result ->
loop_event_result(
Parent, Debug, S, Events, State, Data, P, Event, Result);
@@ -936,14 +1019,6 @@ loop_event(
%% of calling a nonexistent state function
%% to make the undef more precise
case erlang:get_stacktrace() of
- [{Module,callback_mode,[]=Args,_}
- |Stacktrace]
- when CallbackMode =:= undefined ->
- terminate(
- error,
- {undef_callback,{Module,callback_mode,Args}},
- Stacktrace,
- Debug, S, [Event|Events], State, Data, P);
[{Module,State,[Type,Content,Data]=Args,_}
|Stacktrace]
when CallbackMode =:= state_functions ->
@@ -972,25 +1047,6 @@ loop_event(
Debug, S, [Event|Events], State, Data, P)
end.
-%% Interpret callback_mode() result
-loop_event_callback_mode(
- Parent, Debug, S, Events, State, Data, P, Event, CallbackMode) ->
- case callback_mode(CallbackMode) of
- true ->
- Hibernate = false, % We have already GC:ed recently
- loop_event(
- Parent, Debug,
- S#{callback_mode := CallbackMode},
- Events,
- State, Data, P, Event, Hibernate);
- false ->
- terminate(
- error,
- {bad_return_from_callback_mode,CallbackMode},
- ?STACKTRACE(),
- Debug, S, [Event|Events], State, Data, P)
- end.
-
%% Interpret all callback return variants
loop_event_result(
Parent, Debug, S, Events, State, Data, P, Event, Result) ->
@@ -1174,7 +1230,7 @@ loop_event_actions(
%%
%% End of actions list
loop_event_actions(
- Parent, Debug, S, Events,
+ Parent, Debug, #{state_entry_events := SEEvents} = S, Events,
State, NewData, P0, Event, NextState, [],
Postpone, Hibernate, Timeout, NextEvents) ->
%%
@@ -1196,7 +1252,25 @@ loop_event_actions(
{lists:reverse(P1, Events),[]}
end,
%% Place next events first in queue
- Q = lists:reverse(NextEvents, Q2),
+ Q3 = lists:reverse(NextEvents, Q2),
+ %% State entry events
+ Q =
+ case SEEvents of
+ true ->
+ %% Generate state entry events
+ case
+ (NextState =/= State)
+ orelse maps:is_key(init_state, S)
+ of
+ true ->
+ %% State change or initial state
+ [{enter,State}|Q3];
+ false ->
+ Q3
+ end;
+ false ->
+ Q3
+ end,
%%
NewDebug =
sys_debug(
@@ -1208,7 +1282,15 @@ loop_event_actions(
{consume,Event,NextState}
end),
loop_events(
- Parent, NewDebug, S, Q, NextState, NewData, P, Hibernate, Timeout).
+ Parent, NewDebug,
+ %% Avoid infinite loop in initial state with state entry events
+ case maps:is_key(init_state, S) of
+ true ->
+ maps:remove(init_state, S);
+ false ->
+ S
+ end,
+ Q, NextState, NewData, P, Hibernate, Timeout).
%%---------------------------------------------------------------------------
%% Server helpers
@@ -1285,7 +1367,9 @@ terminate(
error_info(
Class, Reason, Stacktrace,
- #{name := Name, callback_mode := CallbackMode},
+ #{name := Name,
+ callback_mode := CallbackMode,
+ state_entry_events := SEEvents},
Q, P, FmtData) ->
{FixedReason,FixedStacktrace} =
case Stacktrace of
@@ -1312,6 +1396,13 @@ error_info(
end;
_ -> {Reason,Stacktrace}
end,
+ CBMode =
+ case SEEvents of
+ true ->
+ [CallbackMode,state_entry_events];
+ false ->
+ CallbackMode
+ end,
error_logger:format(
"** State machine ~p terminating~n" ++
case Q of
@@ -1338,8 +1429,9 @@ error_info(
[] -> [];
[Event|_] -> [Event]
end] ++
- [FmtData,Class,FixedReason,
- CallbackMode] ++
+ [FmtData,
+ Class,FixedReason,
+ CBMode] ++
case Q of
[_|[_|_] = Events] -> [Events];
_ -> []
diff --git a/lib/stdlib/test/gen_statem_SUITE.erl b/lib/stdlib/test/gen_statem_SUITE.erl
index e092940174..eef8f265c4 100644
--- a/lib/stdlib/test/gen_statem_SUITE.erl
+++ b/lib/stdlib/test/gen_statem_SUITE.erl
@@ -37,7 +37,7 @@ all() ->
{group, stop_handle_event},
{group, abnormal},
{group, abnormal_handle_event},
- shutdown, stop_and_reply, event_order, code_change,
+ shutdown, stop_and_reply, enter_events, event_order, code_change,
{group, sys},
hibernate, enter_loop].
@@ -556,7 +556,8 @@ stop_and_reply(_Config) ->
{stop_and_reply,Reason,
[R1,{reply,From2,Reply2}]}
end},
- {ok,STM} = gen_statem:start_link(?MODULE, {map_statem,Machine}, []),
+ {ok,STM} =
+ gen_statem:start_link(?MODULE, {map_statem,Machine,[]}, []),
Self = self(),
Tag1 = make_ref(),
@@ -581,6 +582,61 @@ stop_and_reply(_Config) ->
+enter_events(_Config) ->
+ process_flag(trap_exit, true),
+ Self = self(),
+
+ Machine =
+ %% Abusing the internal format of From...
+ #{init =>
+ fun () ->
+ {ok,start,1}
+ end,
+ start =>
+ fun (enter, Prev, N) ->
+ Self ! {enter,start,Prev,N},
+ {keep_state,N + 1};
+ (internal, Prev, N) ->
+ Self ! {internal,start,Prev,N},
+ {keep_state,N + 1};
+ ({call,From}, echo, N) ->
+ {next_state,wait,N + 1,{reply,From,{echo,start,N}}};
+ ({call,From}, {stop,Reason}, N) ->
+ {stop_and_reply,Reason,[{reply,From,{stop,N}}],N + 1}
+ end,
+ wait =>
+ fun (enter, Prev, N) ->
+ Self ! {enter,wait,Prev,N},
+ {keep_state,N + 1};
+ ({call,From}, echo, N) ->
+ {next_state,start,N + 1,
+ [{next_event,internal,wait},
+ {reply,From,{echo,wait,N}}]}
+ end},
+ {ok,STM} =
+ gen_statem:start_link(
+ ?MODULE, {map_statem,Machine,[state_entry_events]}, []),
+
+ [{enter,start,start,1}] = flush(),
+ {echo,start,2} = gen_statem:call(STM, echo),
+ [{enter,wait,start,3}] = flush(),
+ {wait,[4|_]} = sys:get_state(STM),
+ {echo,wait,4} = gen_statem:call(STM, echo),
+ [{enter,start,wait,5},{internal,start,wait,6}] = flush(),
+ {stop,7} = gen_statem:call(STM, {stop,bye}),
+ [{'EXIT',STM,bye}] = flush(),
+
+ {noproc,_} =
+ ?EXPECT_FAILURE(gen_statem:call(STM, hej), Reason),
+ case flush() of
+ [] ->
+ ok;
+ Other2 ->
+ ct:fail({unexpected,Other2})
+ end.
+
+
+
event_order(_Config) ->
process_flag(trap_exit, true),
@@ -623,7 +679,7 @@ event_order(_Config) ->
Result
end},
- {ok,STM} = gen_statem:start_link(?MODULE, {map_statem,Machine}, []),
+ {ok,STM} = gen_statem:start_link(?MODULE, {map_statem,Machine,[]}, []),
Self = self(),
Tag1 = make_ref(),
gen_statem:cast(STM, {reply,{Self,Tag1},ok1}),
@@ -1315,9 +1371,9 @@ init({callback_mode,CallbackMode,Arg}) ->
ets:new(?MODULE, [named_table,private]),
ets:insert(?MODULE, {callback_mode,CallbackMode}),
init(Arg);
-init({map_statem,#{init := Init}=Machine}) ->
+init({map_statem,#{init := Init}=Machine,Modes}) ->
ets:new(?MODULE, [named_table,private]),
- ets:insert(?MODULE, {callback_mode,handle_event_function}),
+ ets:insert(?MODULE, {callback_mode,[handle_event_function|Modes]}),
case Init() of
{ok,State,Data,Ops} ->
{ok,State,[Data|Machine],Ops};
generated by cgit v1.2.3 (git 2.25.1) at 2024-11-14 07:16:25 +0000