%%
%% %CopyrightBegin%
%%
%% Copyright Ericsson AB 2016. All Rights Reserved.
%%
%% Licensed under the Apache License, Version 2.0 (the "License");
%% you may not use this file except in compliance with the License.
%% You may obtain a copy of the License at
%%
%% http://www.apache.org/licenses/LICENSE-2.0
%%
%% Unless required by applicable law or agreed to in writing, software
%% distributed under the License is distributed on an "AS IS" BASIS,
%% WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
%% See the License for the specific language governing permissions and
%% limitations under the License.
%%
%% %CopyrightEnd%
%%
-module(gen_statem).
%% API
-export(
[start/3,start/4,start_link/3,start_link/4,
stop/1,stop/3,
cast/2,call/2,call/3,
enter_loop/4,enter_loop/5,enter_loop/6,
reply/2]).
%% gen callbacks
-export(
[init_it/6]).
%% sys callbacks
-export(
[system_continue/3,
system_terminate/4,
system_code_change/4,
system_get_state/1,
system_replace_state/2,
format_status/2]).
%% Internal callbacks
-export(
[wakeup_from_hibernate/3]).
%% Fix problem for doc build
-export_type([state_callback_result/0]).
%%%==========================================================================
%%% Interface functions.
%%%==========================================================================
-type client() ::
{To :: pid(), Tag :: term()}. % Reply-to specifier for call
-type state() ::
state_name() | % For state callback function StateName/5
term(). % For state callback function handle_event/5
-type state_name() :: atom().
-type state_data() :: term().
-type event_type() ::
{'call',Client :: client()} | 'cast' |
'info' | 'timeout' | 'internal'.
-type event_predicate() :: % Return true for the event in question
fun((event_type(), term()) -> boolean()).
-type init_option() ::
{'callback_mode', callback_mode()}.
-type callback_mode() :: 'state_functions' | 'handle_event_function'.
-type state_op() ::
%% First NewState and NewStateData are set,
%% then all state_operations() are executed in order of
%% apperance. Postponing the current event is performed
%% (iff state_option() 'postpone' is 'true').
%% Lastly pending events are processed or if there are
%% no pending events the server goes into receive
%% or hibernate (iff state_option() 'hibernate' is 'true')
state_option() | state_operation().
-type state_option() ::
%% The first of each kind in the state_op() list takes precedence
'postpone' | % Postpone the current event to a different (=/=) state
{'postpone', Postpone :: boolean()} |
'hibernate' | % Hibernate the server instead of going into receive
{'hibernate', Hibernate :: boolean()} |
(Timeout :: timeout()) | % {timeout,Timeout}
{'timeout', % Generate a ('timeout', Msg, ...) event after Time
Time :: timeout(), Msg :: term()}.
-type state_operation() ::
%% These can occur multiple times and are executed in order
%% of appearence in the state_op() list
reply_operation() |
{'next_event', % Insert event as the next to handle
EventType :: event_type(),
EventContent :: term()} |
{'remove_event', % Remove the oldest matching (=:=) event
EventType :: event_type(), EventContent :: term()} |
{'remove_event', % Remove the oldest event satisfying predicate
EventPredicate :: event_predicate()} |
{'cancel_timer', % Cancel timer and clean up mess(ages)
TimerRef :: reference()} |
{'demonitor', % Demonitor and clean up mess(ages)
MonitorRef :: reference()} |
{'unlink', % Unlink and clean up mess(ages)
Id :: pid() | port()}.
-type reply_operation() ::
{'reply', % Reply to a client
Client :: client(), Reply :: term()}.
-type state_callback_result() ::
{stop, % Stop the server
Reason :: term(),
NewStateData :: state_data()} |
{stop, % Stop the server
Reason :: term(),
Replies :: [reply_operation()] | reply_operation(),
NewStateData :: state_data()} |
{next_state, % {next_state,NewState,NewStateData,[]}
NewState :: state(),
NewStateData :: state_data()} |
{next_state, % State transition, maybe to the same state
NewState :: state(),
NewStateData :: state_data(),
StateOps :: [state_op()] | state_op()}.
%% The state machine init function. It is called only once and
%% the server is not running until this function has returned
%% an {ok, ...} tuple. Thereafter the state callbacks are called
%% for all events to this server.
-callback init(Args :: term()) ->
{'ok', state(), state_data()} |
{'ok', state(), state_data(), [state_op()|init_option()]} |
'ignore' |
{'stop', Reason :: term()}.
%% Example callback for callback_mode =:= state_functions
%% state name 'state_name'.
%%
%% In this mode all states has to be type state_name() i.e atom().
%%
%% Note that state callbacks and only state callbacks have arity 5
%% and that is intended.
-callback state_name(
event_type(),
EventContent :: term(),
PrevStateName :: state_name() | reference(),
StateName :: state_name(), % Current state
StateData :: state_data()) ->
state_callback_result().
%%
%% Callback for callback_mode =:= handle_event_function.
%%
%% Note that state callbacks and only state callbacks have arity 5
%% and that is intended.
-callback handle_event(
event_type(),
EventContent :: term(),
PrevState :: state(),
State :: state(), % Current state
StateData :: state_data()) ->
state_callback_result().
%% Clean up before the server terminates.
-callback terminate(
Reason :: 'normal' | 'shutdown' | {'shutdown', term()}
| term(),
State :: state(),
StateData :: state_data()) ->
any().
%% Note that the new code can expect to get an OldState from
%% the old code version not only in code_change/4 but in the first
%% state callback function called thereafter
-callback code_change(
OldVsn :: term() | {'down', term()},
OldState :: state(),
OldStateData :: state_data(),
Extra :: term()) ->
{ok, {NewState :: state(), NewStateData :: state_data()}}.
%% Format the callback module state in some sensible that is
%% often condensed way. For StatusOption =:= 'normal' the perferred
%% return term is [{data,[{"State",FormattedState}]}], and for
%% StatusOption =:= 'terminate' it is just FormattedState.
-callback format_status(
StatusOption,
[ [{Key :: term(), Value :: term()}] |
state() |
state_data()]) ->
Status :: term() when
StatusOption :: 'normal' | 'terminate'.
-optional_callbacks(
[format_status/2, % Has got a default implementation
%%
state_name/5, % Example for callback_mode =:= state_functions:
%% there has to be a StateName/5 callback function for every StateName.
%%
handle_event/5]). % For callback_mode =:= handle_event_function
%% Type validation functions
client({Pid,Tag}) when is_pid(Pid), is_reference(Tag) ->
true;
client(_) ->
false.
%%
event_type({call,Client}) ->
client(Client);
event_type(Type) ->
case Type of
cast ->
true;
info ->
true;
timeout ->
true;
internal ->
true;
_ ->
false
end.
-define(
STACKTRACE(),
try throw(ok) catch _ -> erlang:get_stacktrace() end).
-define(
TERMINATE(Reason, Debug, S, Q),
terminate(
exit,
begin Reason end,
?STACKTRACE(),
begin Debug end,
begin S end,
begin Q end)).
%%%==========================================================================
%%% API
-type server_name() ::
{'global', GlobalName :: term()}
| {'via', RegMod :: module(), Name :: term()}
| {'local', atom()}.
-type server_ref() ::
{'global', GlobalName :: term()}
| {'via', RegMod :: module(), ViaName :: term()}
| (LocalName :: atom())
| {Name :: atom(), Node :: atom()}
| pid().
-type debug_opt() ::
{'debug',
Dbgs ::
['trace' | 'log' | 'statistics' | 'debug'
| {'logfile', string()}]}.
-type start_opt() ::
debug_opt()
| {'timeout', Time :: timeout()}
| {'spawn_opt', SOpts :: [proc_lib:spawn_option()]}.
-type start_ret() :: {'ok', pid()} | 'ignore' | {'error', term()}.
%% Start a state machine
-spec start(
Module :: module(), Args :: term(), Options :: [start_opt()]) ->
start_ret().
start(Module, Args, Options) ->
gen:start(?MODULE, nolink, Module, Args, Options).
%%
-spec start(
ServerName :: server_name(),
Module :: module(), Args :: term(), Options :: [start_opt()]) ->
start_ret().
start(ServerName, Module, Args, Options) ->
gen:start(?MODULE, nolink, ServerName, Module, Args, Options).
%% Start and link to a state machine
-spec start_link(
Module :: module(), Args :: term(), Options :: [start_opt()]) ->
start_ret().
start_link(Module, Args, Options) ->
gen:start(?MODULE, link, Module, Args, Options).
%%
-spec start_link(
ServerName :: server_name(),
Module :: module(), Args :: term(), Options :: [start_opt()]) ->
start_ret().
start_link(ServerName, Module, Args, Options) ->
gen:start(?MODULE, link, ServerName, Module, Args, Options).
%% Stop a state machine
-spec stop(ServerRef :: server_ref()) -> ok.
stop(ServerRef) ->
gen:stop(ServerRef).
%%
-spec stop(
ServerRef :: server_ref(),
Reason :: term(),
Timeout :: timeout()) -> ok.
stop(ServerRef, Reason, Timeout) ->
gen:stop(ServerRef, Reason, Timeout).
%% Send an event to a state machine that arrives with type 'event'
-spec cast(ServerRef :: server_ref(), Msg :: term()) -> ok.
cast({global,Name}, Msg) ->
try global:send(Name, cast(Msg)) of
_ -> ok
catch
_:_ -> ok
end;
cast({via,RegMod,Name}, Msg) ->
try RegMod:send(Name, cast(Msg)) of
_ -> ok
catch
_:_ -> ok
end;
cast({Name,Node} = ServerRef, Msg) when is_atom(Name), is_atom(Node) ->
do_send(ServerRef, cast(Msg));
cast(ServerRef, Msg) when is_atom(ServerRef) ->
do_send(ServerRef, cast(Msg));
cast(ServerRef, Msg) when is_pid(ServerRef) ->
do_send(ServerRef, cast(Msg)).
%% Call a state machine (synchronous; a reply is expected) that
%% arrives with type {call,Client}
-spec call(ServerRef :: server_ref(), Request :: term()) -> Reply :: term().
call(ServerRef, Request) ->
call(ServerRef, Request, infinity).
%%
-spec call(
ServerRef :: server_ref(),
Request :: term(),
Timeout :: timeout()) ->
Reply :: term().
call(ServerRef, Request, infinity) ->
try gen:call(ServerRef, '$gen_call', Request, infinity) of
{ok,Reply} ->
Reply
catch
Class:Reason ->
erlang:raise(
Class,
{Reason,{?MODULE,call,[ServerRef,Request,infinity]}},
erlang:get_stacktrace())
end;
call(ServerRef, Request, Timeout) ->
%% Call server through proxy process to dodge any late reply
Ref = make_ref(),
Self = self(),
Pid = spawn(
fun () ->
Self !
try gen:call(
ServerRef, '$gen_call', Request, Timeout) of
Result ->
{Ref,Result}
catch Class:Reason ->
{Ref,Class,Reason,erlang:get_stacktrace()}
end
end),
Mref = monitor(process, Pid),
receive
{Ref,Result} ->
demonitor(Mref, [flush]),
case Result of
{ok,Reply} ->
Reply
end;
{Ref,Class,Reason,Stacktrace} ->
demonitor(Mref, [flush]),
erlang:raise(
Class,
{Reason,{?MODULE,call,[ServerRef,Request,Timeout]}},
Stacktrace);
{'DOWN',Mref,_,_,Reason} ->
%% There is just a theoretical possibility that the
%% proxy process gets killed between try--of and !
%% so this clause is in case of that
exit(Reason)
end.
%% Reply from a state machine callback to whom awaits in call/2
-spec reply(Client :: client(), Reply :: term()) -> ok.
reply({To,Tag}, Reply) ->
Msg = {Tag,Reply},
try To ! Msg of
_ ->
ok
catch
_:_ -> ok
end.
%% Instead of starting the state machine through start/3,4
%% or start_link/3,4 turn the current process presumably
%% started by proc_lib into a state machine using
%% the same arguments as you would have returned from init/1
-spec enter_loop(
Module :: module(), Options :: [debug_opt()],
State :: state(), StateData :: state_data()) ->
no_return().
enter_loop(Module, Options, State, StateData) ->
enter_loop(Module, Options, State, StateData, self()).
%%
-spec enter_loop(
Module :: module(), Options :: [debug_opt()],
State :: state(), StateData :: state_data(),
Server_or_StateOps ::
server_name() | pid() | [state_op()|init_option()]) ->
no_return().
enter_loop(Module, Options, State, StateData, Server_or_StateOps) ->
if
is_list(Server_or_StateOps) ->
enter_loop(
Module, Options, State, StateData,
self(), Server_or_StateOps);
true ->
enter_loop(
Module, Options, State, StateData,
Server_or_StateOps, [])
end.
%%
-spec enter_loop(
Module :: module(), Options :: [debug_opt()],
State :: state(), StateData :: state_data(),
Server :: server_name() | pid(),
StateOps :: [state_op()|init_option()]) ->
no_return().
enter_loop(Module, Options, State, StateData, Server, StateOps) ->
Parent = gen:get_parent(),
enter(Module, Options, State, StateData, Server, StateOps, Parent).
%%---------------------------------------------------------------------------
%% API helpers
cast(Event) ->
{'$gen_cast',Event}.
%% Might actually not send the message in case of caught exception
do_send(Proc, Msg) ->
try erlang:send(Proc, Msg, [noconnect]) of
noconnect ->
_ = spawn(erlang, send, [Proc,Msg]),
ok;
ok ->
ok
catch
_:_ ->
ok
end.
%% Here init_it and all enter_loop functions converge
enter(Module, Options, State, StateData, Server, InitOps, Parent) ->
Name = gen:get_proc_name(Server),
Debug = gen:debug_options(Name, Options),
PrevState = make_ref(),
S = #{
callback_mode => state_functions,
module => Module,
name => Name,
prev_state => PrevState,
state => PrevState,
state_data => StateData,
timer => undefined,
postponed => [],
hibernate => false},
case collect_init_options(InitOps) of
{CallbackMode,StateOps} ->
loop_event_state_ops(
Parent, Debug,
S#{callback_mode := CallbackMode},
[], {event,undefined},
State, StateData,
StateOps++[{postpone,false}]);
[Reason] ->
?TERMINATE(Reason, Debug, S, [])
end.
%%%==========================================================================
%%% gen callbacks
init_it(Starter, Parent, ServerRef, Module, Args, Options) ->
try Module:init(Args) of
Result ->
init_result(Starter, Parent, ServerRef, Module, Result, Options)
catch
Result ->
init_result(Starter, Parent, ServerRef, Module, Result, Options);
Class:Reason ->
gen:unregister_name(ServerRef),
proc_lib:init_ack(Starter, {error,Reason}),
erlang:raise(Class, Reason, erlang:get_stacktrace())
end.
%%---------------------------------------------------------------------------
%% gen callbacks helpers
init_result(Starter, Parent, ServerRef, Module, Result, Options) ->
case Result of
{ok,State,StateData} ->
proc_lib:init_ack(Starter, {ok,self()}),
enter(
Module, Options, State, StateData, ServerRef,
[], Parent);
{ok,State,StateData,StateOps} ->
proc_lib:init_ack(Starter, {ok,self()}),
enter(
Module, Options, State, StateData, ServerRef,
StateOps, Parent);
{stop,Reason} ->
gen:unregister_name(ServerRef),
proc_lib:init_ack(Starter, {error,Reason}),
exit(Reason);
ignore ->
gen:unregister_name(ServerRef),
proc_lib:init_ack(Starter, ignore),
exit(normal);
Other ->
Error = {bad_return_value,Other},
proc_lib:init_ack(Starter, {error,Error}),
exit(Error)
end.
%%%==========================================================================
%%% sys callbacks
system_continue(Parent, Debug, S) ->
loop(Parent, Debug, S).
system_terminate(Reason, _Parent, Debug, S) ->
?TERMINATE(Reason, Debug, S, []).
system_code_change(
#{module := Module,
state := State,
state_data := StateData} = S,
_Mod, OldVsn, Extra) ->
case
try Module:code_change(OldVsn, State, StateData, Extra)
catch
Result -> Result
end
of
{ok,{NewState,NewStateData}} ->
{ok,
S#{
state := NewState,
state_data := NewStateData}};
Error ->
Error
end.
system_get_state(#{state := State, state_data := StateData}) ->
{ok,{State,StateData}}.
system_replace_state(
StateFun,
#{state := State,
state_data := StateData} = S) ->
{NewState,NewStateData} = Result = StateFun({State,StateData}),
{ok,Result,S#{state := NewState, state_data := NewStateData}}.
format_status(
Opt,
[PDict,SysState,Parent,Debug,
#{name := Name, postponed := P} = S]) ->
Header = gen:format_status_header("Status for state machine", Name),
Log = sys:get_debug(log, Debug, []),
[{header,Header},
{data,
[{"Status",SysState},
{"Parent",Parent},
{"Logged Events",Log},
{"Postponed",P}]} |
case format_status(Opt, PDict, S) of
L when is_list(L) -> L;
T -> [T]
end].
%%---------------------------------------------------------------------------
%% Format debug messages. Print them as the call-back module sees
%% them, not as the real erlang messages. Use trace for that.
%%---------------------------------------------------------------------------
print_event(Dev, {in,Event}, #{name := Name}) ->
io:format(
Dev, "*DBG* ~p received ~s~n",
[Name,event_string(Event)]);
print_event(Dev, {out,Reply,{To,_Tag}}, #{name := Name}) ->
io:format(
Dev, "*DBG* ~p sent ~p to ~p~n",
[Name,Reply,To]);
print_event(Dev, {Tag,Event,NewState}, #{name := Name, state := State}) ->
StateString =
case NewState of
State ->
io_lib:format("~p", [State]);
_ ->
io_lib:format("~p => ~p", [State,NewState])
end,
io:format(
Dev, "*DBG* ~p ~w ~s in state ~s~n",
[Name,Tag,event_string(Event),StateString]).
event_string(Event) ->
case Event of
{{call,{Pid,_Tag}},Request} ->
io_lib:format("call ~p from ~w", [Request,Pid]);
{Tag,Content} ->
io_lib:format("~w ~p", [Tag,Content])
end.
sys_debug(Debug, S, Entry) ->
case Debug of
[] ->
Debug;
_ ->
sys:handle_debug(Debug, fun print_event/3, S, Entry)
end.
%%%==========================================================================
%%% Internal callbacks
wakeup_from_hibernate(Parent, Debug, S) ->
%% It is a new message that woke us up so we have to receive it now
loop_receive(Parent, Debug, S).
%%%==========================================================================
%%% STate Machine engine implementation of proc_lib/gen server
%% Server loop, consists of all loop* functions
%% and some detours through sys and proc_lib
%% Entry point for system_continue/3
loop(Parent, Debug, #{hibernate := Hib} = S) ->
case Hib of
true ->
loop_hibernate(Parent, Debug, S);
false ->
loop_receive(Parent, Debug, S)
end.
loop_hibernate(Parent, Debug, S) ->
%% Does not return but restarts process at
%% wakeup_from_hibernate/3 that jumps to loop_receive/3
proc_lib:hibernate(
?MODULE, wakeup_from_hibernate, [Parent,Debug,S]),
error(
{should_not_have_arrived_here_but_instead_in,
{wakeup_from_hibernate,3}}).
%% Entry point for wakeup_from_hibernate/3
loop_receive(Parent, Debug, #{timer := Timer} = S) ->
receive
Msg ->
case Msg of
{system,Pid,Req} ->
%% Does not return but tail recursively calls
%% system_continue/3 that jumps to loop/3
sys:handle_system_msg(
Req, Pid, Parent, ?MODULE, Debug, S,
maps:get(hibernate, S));
{'EXIT',Parent,Reason} = EXIT ->
%% EXIT is not a 2-tuple and therefore
%% not an event and has no event_type(),
%% but this will stand out in the crash report...
?TERMINATE(Reason, Debug, S, [EXIT]);
{timeout,Timer,Content} when Timer =/= undefined ->
loop_receive(
Parent, Debug, S, {timeout,Content}, undefined);
_ ->
Event =
case Msg of
{'$gen_call',Client,Request} ->
{{call,Client},Request};
{'$gen_cast',E} ->
{cast,E};
_ ->
{info,Msg}
end,
loop_receive(Parent, Debug, S, Event, Timer)
end
end.
loop_receive(Parent, Debug, S, Event, Timer) ->
NewDebug = sys_debug(Debug, S, {in,Event}),
%% Here the queue of not yet processed events is created
loop_events(Parent, NewDebug, S, [Event], Timer).
%% Process first event in queue, or if there is none receive a new
%%
%% The loop_event* functions optimize S map handling by dismantling it,
%% passing the parts in arguments to avoid map lookups and construct the
%% new S map in one go on exit. Premature optimization, I know, but
%% there were quite some map lookups repeated in different functions.
loop_events(Parent, Debug, S, [], _Timer) ->
loop(Parent, Debug, S);
loop_events(
Parent, Debug,
#{callback_mode := CallbackMode,
module := Module,
prev_state := PrevState,
state := State,
state_data := StateData} = S,
[{Type,Content} = Event|Events] = Q, Timer) ->
_ = (Timer =/= undefined) andalso
cancel_timer(Timer),
Func =
case CallbackMode of
handle_event_function ->
handle_event;
state_functions ->
State
end,
try Module:Func(Type, Content, PrevState, State, StateData) of
Result ->
loop_event_result(
Parent, Debug, S, Events, Event, Result)
catch
Result ->
loop_event_result(
Parent, Debug, S, Events, Event, Result);
error:undef ->
%% Process an undef to check for the simple mistake
%% of calling a nonexistent state function
case erlang:get_stacktrace() of
[{Module,Func,
[Type,Content,PrevState,State,StateData]=Args,
_}
|Stacktrace] ->
terminate(
error,
{undef_state_function,{Module,State,Args}},
Stacktrace,
Debug, S, Q);
Stacktrace ->
terminate(error, undef, Stacktrace, Debug, S, Q)
end;
Class:Reason ->
Stacktrace = erlang:get_stacktrace(),
terminate(Class, Reason, Stacktrace, Debug, S, Q)
end.
%% Interpret all callback return value variants
loop_event_result(Parent, Debug, S, Events, Event, Result) ->
case Result of
{stop,Reason,NewStateData} ->
?TERMINATE(
Reason, Debug,
S#{state_data := NewStateData},
[Event|Events]);
{stop,Reason,Reply,NewStateData} ->
NewS = S#{state_data := NewStateData},
Q = [Event|Events],
Replies =
if
is_list(Reply) ->
Reply;
true ->
[Reply]
end,
BadReplies =
reply_then_terminate(
exit, Reason, ?STACKTRACE(), Debug, NewS, Q, Replies),
%% Since we got back here Replies was bad
?TERMINATE(
{bad_return_value,{stop,Reason,BadReplies,NewStateData}},
Debug, NewS, Q);
{next_state,NewState,NewStateData} ->
loop_event_state_ops(
Parent, Debug, S, Events, Event,
NewState, NewStateData, []);
{next_state,NewState,NewStateData,StateOps}
when is_list(StateOps) ->
loop_event_state_ops(
Parent, Debug, S, Events, Event,
NewState, NewStateData, StateOps);
_ ->
?TERMINATE(
{bad_return_value,Result}, Debug, S, [Event|Events])
end.
loop_event_state_ops(
Parent, Debug0, #{state := State, postponed := P0} = S, Events, Event,
NewState, NewStateData, StateOps) ->
case collect_state_options(StateOps) of
{Postpone,Hibernate,Timeout,Operations} ->
P1 = % Move current event to postponed if Postpone
case Postpone of
true ->
[Event|P0];
false ->
P0
end,
{Q2,P2} = % Move all postponed events to queue if state change
if
NewState =:= State ->
{Events,P1};
true ->
{lists:reverse(P1, Events),[]}
end,
%%
case process_state_operations(
Operations, Debug0, S, Q2, P2) of
{Debug,Q3,P} ->
NewDebug =
sys_debug(
Debug, S,
case Postpone of
true ->
{postpone,Event,NewState};
false ->
{consume,Event,NewState}
end),
{Timer,Q} =
case Timeout of
undefined ->
{undefined,Q3};
{timeout,0,Msg} ->
%% Pretend the timeout has just been received
{undefined,Q3 ++ [{timeout,Msg}]};
{timeout,Time,Msg} ->
{erlang:start_timer(Time, self(), Msg),
Q3}
end,
loop_events(
Parent, NewDebug,
S#{
prev_state := State,
state := NewState,
state_data := NewStateData,
timer := Timer,
hibernate := Hibernate,
postponed := P},
Q, Timer);
[Reason,Debug] ->
?TERMINATE(Reason, Debug, S, [Event|Events]);
[Class,Reason,Stacktrace,Debug] ->
terminate(
Class, Reason, Stacktrace, Debug, S, [Event|Events])
end;
%%
[Reason] ->
?TERMINATE(Reason, Debug0, S, [Event|Events])
end.
%%---------------------------------------------------------------------------
%% Server helpers
collect_init_options(InitOps) ->
collect_init_options(InitOps, state_functions, []).
%% Keep the last of each kind
collect_init_options([], CallbackMode, StateOps) ->
{CallbackMode,lists:reverse(StateOps)};
collect_init_options([InitOp|InitOps] = IOIOs, CallbackMode, StateOps) ->
case InitOp of
{callback_mode,Mode}
when Mode =:= state_functions;
Mode =:= handle_event_function ->
collect_init_options(InitOps, Mode, StateOps);
{callback_mode,_} ->
[{bad_init_ops,IOIOs}];
_ -> % Collect others as StateOps
collect_init_options(
InitOps, CallbackMode, [InitOp|StateOps])
end.
collect_state_options(StateOps) ->
collect_state_options(StateOps, false, false, undefined, []).
%% Keep the last of each kind
collect_state_options(
[], Postpone, Hibernate, Timeout, Operations) ->
{Postpone,Hibernate,Timeout,lists:reverse(Operations)};
collect_state_options(
[StateOp|StateOps] = SOSOs, Postpone, Hibernate, Timeout, Operations) ->
case StateOp of
postpone ->
collect_state_options(
StateOps, true, Hibernate, Timeout, Operations);
{postpone,NewPostpone} when is_boolean(NewPostpone) ->
collect_state_options(
StateOps, NewPostpone, Hibernate, Timeout, Operations);
{postpone,_} ->
[{bad_state_ops,SOSOs}];
hibernate ->
collect_state_options(
StateOps, Postpone, true, Timeout, Operations);
{hibernate,NewHibernate} when is_boolean(NewHibernate) ->
collect_state_options(
StateOps, Postpone, NewHibernate, Timeout, Operations);
{hibernate,_} ->
[{bad_state_ops,SOSOs}];
{timeout,infinity,_} -> % Ignore since it will never time out
collect_state_options(
StateOps, Postpone, Hibernate, undefined, Operations);
{timeout,Time,_} = NewTimeout when is_integer(Time), Time >= 0 ->
collect_state_options(
StateOps, Postpone, Hibernate, NewTimeout, Operations);
{timeout,_,_} ->
[{bad_state_ops,SOSOs}];
_ -> % Collect others as operations
collect_state_options(
StateOps, Postpone, Hibernate, Timeout, [StateOp|Operations])
end.
process_state_operations([], Debug, _S, Q, P) ->
{Debug,Q,P};
process_state_operations([Operation|Operations] = OOs, Debug, S, Q, P) ->
case Operation of
{reply,{_To,_Tag}=Client,Reply} ->
NewDebug = do_reply(Debug, S, Client, Reply),
process_state_operations(Operations, NewDebug, S, Q, P);
{next_event,Type,Content} ->
case event_type(Type) of
true ->
process_state_operations(
Operations, Debug, S, [{Type,Content}|Q], P);
false ->
[{bad_state_ops,OOs},Debug]
end;
_ ->
%% All others are remove operations
case remove_fun(Operation) of
false ->
process_state_operations(
Operations, Debug, S, Q, P);
undefined ->
[{bad_state_ops,OOs},Debug];
RemoveFun when is_function(RemoveFun, 2) ->
case remove_event(RemoveFun, Q, P) of
{NewQ,NewP} ->
process_state_operations(
Operations, Debug, S, NewQ, NewP);
Error ->
Error ++ [Debug]
end;
Error ->
Error ++ [Debug]
end
end.
reply_then_terminate(Class, Reason, Stacktrace, Debug, S, Q, []) ->
terminate(Class, Reason, Stacktrace, Debug, S, Q);
reply_then_terminate(
Class, Reason, Stacktrace, Debug, S, Q, [R|Rs] = RRs) ->
case R of
{reply,{_To,_Tag}=Client,Reply} ->
NewDebug = do_reply(Debug, S, Client, Reply),
reply_then_terminate(
Class, Reason, Stacktrace, NewDebug, S, Q, Rs);
_ ->
RRs % bad_return_value
end.
do_reply(Debug, S, Client, Reply) ->
reply(Client, Reply),
sys_debug(Debug, S, {out,Reply,Client}).
%% Remove oldest matching event from the queue(s)
remove_event(RemoveFun, Q, P) ->
try
case remove_tail_event(RemoveFun, P) of
false ->
case remove_head_event(RemoveFun, Q) of
false ->
{P,Q};
NewQ ->
{P,NewQ}
end;
NewP ->
{NewP,Q}
end
catch
Class:Reason ->
[Class,Reason,erlang:get_stacktrace()]
end.
%% Do the given state operation and create an event removal predicate fun()
remove_fun({remove_event,Type,Content}) ->
fun (T, C) when T =:= Type, C =:= Content -> true;
(_, _) -> false
end;
remove_fun({remove_event,RemoveFun}) when is_function(RemoveFun, 2) ->
RemoveFun;
remove_fun({cancel_timer,TimerRef}) ->
try cancel_timer(TimerRef) of
false ->
false;
true ->
fun
(info, {timeout,TRef,_})
when TRef =:= TimerRef ->
true;
(_, _) ->
false
end
catch
Class:Reason ->
[Class,Reason,erlang:get_stacktrace()]
end;
remove_fun({demonitor,MonitorRef}) ->
try erlang:demonitor(MonitorRef, [flush,info]) of
false ->
false;
true ->
fun (info, {'DOWN',MRef,_,_,_})
when MRef =:= MonitorRef->
true;
(_, _) ->
false
end
catch
Class:Reason ->
[Class,Reason,erlang:get_stacktrace()]
end;
remove_fun({unlink,Id}) ->
try unlink(Id) of
true ->
receive
{'EXIT',Id,_} ->
ok
after 0 ->
ok
end,
fun (info, {'EXIT',I,_})
when I =:= Id ->
true;
(_, _) ->
false
end
catch
Class:Reason ->
[Class,Reason,erlang:get_stacktrace()]
end;
remove_fun(_) ->
undefined.
%% Cancel a timer and clense the process mailbox returning
%% false if no such timer message can arrive after this or
%% true otherwise
cancel_timer(TimerRef) ->
case erlang:cancel_timer(TimerRef) of
TimeLeft when is_integer(TimeLeft) ->
false;
false ->
receive
{timeout,TimerRef,_} ->
false
after 0 ->
true
end
end.
terminate(
Class, Reason, Stacktrace, Debug,
#{module := Module,
state := State, state_data := StateData} = S,
Q) ->
try Module:terminate(Reason, State, StateData) of
_ -> ok
catch
_ -> ok;
C:R ->
ST = erlang:get_stacktrace(),
error_info(
C, R, ST, Debug, S, Q,
format_status(terminate, get(), S)),
erlang:raise(C, R, ST)
end,
case Reason of
normal -> ok;
shutdown -> ok;
{shutdown,_} -> ok;
_ ->
error_info(
Class, Reason, Stacktrace, Debug, S, Q,
format_status(terminate, get(), S))
end,
case Stacktrace of
[] ->
erlang:Class(Reason);
_ ->
erlang:raise(Class, Reason, Stacktrace)
end.
error_info(
Class, Reason, Stacktrace, Debug,
#{name := Name, callback_mode := CallbackMode,
state := State, postponed := P},
Q, FmtStateData) ->
{FixedReason,FixedStacktrace} =
case Stacktrace of
[{M,F,Args,_}|ST]
when Class =:= error, Reason =:= undef ->
case code:is_loaded(M) of
false ->
{{'module could not be loaded',M},ST};
_ ->
Arity =
if
is_list(Args) ->
length(Args);
is_integer(Args) ->
Args
end,
case erlang:function_exported(M, F, Arity) of
true ->
{Reason,Stacktrace};
false ->
{{'function not exported',{M,F,Arity}},
ST}
end
end;
_ -> {Reason,Stacktrace}
end,
error_logger:format(
"** State machine ~p terminating~n" ++
case Q of
[] ->
"";
_ ->
"** Last event = ~p~n"
end ++
"** When Server state = ~p~n" ++
"** Reason for termination = ~w:~p~n" ++
"** State = ~p~n" ++
"** Callback mode = ~p~n" ++
"** Queued/Posponed = ~w/~w~n" ++
case FixedStacktrace of
[] ->
"";
_ ->
"** Stacktrace =~n"
"** ~p~n"
end,
[Name |
case Q of
[] ->
[];
[Event|_] ->
[Event]
end] ++
[FmtStateData,Class,FixedReason,
State,CallbackMode,length(Q),length(P)] ++
case FixedStacktrace of
[] ->
[];
_ ->
[FixedStacktrace]
end),
sys:print_log(Debug),
ok.
%% Call Module:format_status/2 or return a default value
format_status(
Opt, PDict,
#{module := Module, state := State, state_data := StateData}) ->
case erlang:function_exported(Module, format_status, 2) of
true ->
try Module:format_status(Opt, [PDict,State,StateData])
catch
Result -> Result;
_:_ ->
format_status_default(Opt, State, StateData)
end;
false ->
format_status_default(Opt, State, StateData)
end.
%% The default Module:format_status/2
format_status_default(Opt, State, StateData) ->
SSD = {State,StateData},
case Opt of
terminate ->
SSD;
_ ->
[{data,[{"State",SSD}]}]
end.
%%---------------------------------------------------------------------------
%% Farily general helpers
%% Return the modified list where the first element that satisfies
%% the RemoveFun predicate is removed, or false if no such element exists.
remove_head_event(_RemoveFun, []) ->
false;
remove_head_event(RemoveFun, [{Tag,Content}|Events]) ->
case RemoveFun(Tag, Content) of
false ->
remove_head_event(RemoveFun, Events);
true ->
Events
end.
%% Return the modified list where the last element that satisfies
%% the RemoveFun predicate is removed, or false if no such element exists.
remove_tail_event(_RemoveFun, []) ->
false;
remove_tail_event(RemoveFun, [{Tag,Content} = Event|Events]) ->
case remove_tail_event(RemoveFun, Events) of
false ->
RemoveFun(Tag, Content) andalso Events;
NewEvents ->
[Event|NewEvents]
end.
