sys
A functional interface to system messages.
This module contains functions for sending system messages used by programs, and messages used for debugging purposes.
Functions used for implementation of processes are also expected to
understand system messages, such as debug messages and code change. These
functions must be used to implement the use of system messages for a
process; either directly, or through standard behaviors, such as
gen_server
.
The default time-out is 5000 ms, unless otherwise specified.
timeout
defines the time to wait for the process to
respond to a request. If the process does not respond, the
function evaluates exit({timeout, {M, F, A}})
.
The functions make references to a debug structure.
The debug structure is a list of dbg_opt()
, which is an internal
data type used by function
handle_system_msg/6
. No debugging is performed if it is
an empty list.
System Messages
Processes that are not implemented as one of the standard behaviors must still understand system messages. The following three messages must be understood:
-
Plain system messages. These are received as
{system, From, Msg}
. The content and meaning of this message are not interpreted by the receiving process module. When a system message is received, functionhandle_system_msg/6
is called to handle the request. -
Shutdown messages. If the process traps exits, it must be able to handle a shutdown request from its parent, the supervisor. The message
{'EXIT', Parent, Reason}
from the parent is an order to terminate. The process must terminate when this message is received, normally with the sameReason
asParent
. -
If the modules used to implement the process change dynamically during runtime, the process must understand one more message. An example is the
gen_event
processes. The message is{get_modules, From}
. The reply to this message isFrom ! {modules, Modules}
, whereModules
is a list of the currently active modules in the process.This message is used by the release handler to find which processes that execute a certain module. The process can later be suspended and ordered to perform a code change for one of its modules.
System Events
When debugging a process with the functions of this
module, the process generates system_events, which are
then treated in the debug function. For example, trace
formats the system events to the terminal.
Three predefined system events are used when a process receives or sends a message. The process can also define its own system events. It is always up to the process itself to format these events.
Types
name() = pid() | atom() | {global, atom()}
system_event() =
{in, Msg :: term()} |
{in, Msg :: term(), From :: term()} |
{out, Msg :: term(), To :: term()} |
term()
dbg_opt()
See the introduction of this manual page.
dbg_fun() =
fun((FuncState :: term(),
Event :: system_event(),
ProcState :: term()) ->
done | (NewFuncState :: term()))
format_fun() =
fun((Device :: io:device() | file:io_device(),
Event :: system_event(),
Extra :: term()) ->
any())
Functions
change_code(Name, Module, OldVsn, Extra) -> ok | {error, Reason}
Name = name()
Module = module()
OldVsn = undefined | term()
Extra = Reason = term()
change_code(Name, Module, OldVsn, Extra, Timeout) ->
ok | {error, Reason}
Name = name()
Module = module()
OldVsn = undefined | term()
Extra = term()
Timeout = timeout()
Reason = term()
Tells the process to change code. The process must be
suspended to handle this message. Argument
is reserved for each process to use as its own. Function
is called.
is the old version of the
.
get_state(Name) -> State
Name = name()
State = term()
get_state(Name, Timeout) -> State
Name = name()
Timeout = timeout()
State = term()
Gets the state of the process.
Note!
These functions are intended only to help with debugging. They are
provided for convenience, allowing developers to avoid having to
create their own state extraction functions and also avoid having
to interactively extract the state from the return values of
get_status/1
or
get_status/2
while debugging.
The value of
varies for different types of
processes, as follows:
-
For a
gen_server
process, the returned
is the state of the callback module.State -
For a
gen_fsm
process,
is the tupleState {CurrentStateName, CurrentStateData}
. -
For a
gen_statem
process,
is the tupleState {CurrentState,CurrentData}
. -
For a
gen_event
process,
is a list of tuples, where each tuple corresponds to an event handler registered in the process and containsState {Module, Id, HandlerState}
, as follows:Module
The module name of the event handler.
Id
The ID of the handler (which is
false
if it was registered without an ID).HandlerState
The state of the handler.
If the callback module exports a function system_get_state/1
,
it is called in the target process to get its state. Its argument is
the same as the Misc
value returned by
get_status/1,2
, and
function
Module:system_get_state/1
is expected to extract the
state of the callback module from it. Function
system_get_state/1
must return {ok, State}
, where
State
is the state of the callback module.
If the callback module does not export a system_get_state/1
function, get_state/1,2
assumes that the Misc
value is
the state of the callback module and returns it directly instead.
If the callback module's system_get_state/1
function crashes
or throws an exception, the caller exits with error
{callback_failed, {Module, system_get_state}, {Class, Reason}}
,
where Module
is the name of the callback module and
Class
and Reason
indicate details of the exception.
Function system_get_state/1
is primarily useful for
user-defined behaviors and modules that implement OTP
special processes.
The gen_server
, gen_fsm
,
gen_statem
, and gen_event
OTP
behavior modules export this function, so callback modules for those
behaviors need not to supply their own.
For more information about a process, including its state, see
get_status/1
and
get_status/2
.
get_status(Name) -> Status
Name = name()
Status =
{status, Pid :: pid(), {module, Module :: module()}, [SItem]}SItem =
(PDict :: [{Key :: term(), Value :: term()}]) |
(SysState :: running | suspended) |
(Parent :: pid()) |
(Dbg :: [dbg_opt()]) |
(Misc :: term())
get_status(Name, Timeout) -> Status
Name = name()
Timeout = timeout()
Status =
{status, Pid :: pid(), {module, Module :: module()}, [SItem]}SItem =
(PDict :: [{Key :: term(), Value :: term()}]) |
(SysState :: running | suspended) |
(Parent :: pid()) |
(Dbg :: [dbg_opt()]) |
(Misc :: term())
Gets the status of the process.
The value of
varies for different types of
processes, for example:
-
A
gen_server
process returns the state of the callback module. -
A
gen_fsm
process returns information, such as its current state name and state data. -
A
gen_statem
process returns information, such as its current state name and state data. -
A
gen_event
process returns information about each of its registered handlers.
Callback modules for gen_server
,
gen_fsm
, gen_statem
, and gen_event
can also change the value of
by exporting a function format_status/2
, which contributes
module-specific information. For details, see
gen_server:format_status/2
,
gen_fsm:format_status/2
,
gen_statem:format_status/2
, and
gen_event:format_status/2
.
install(Name, FuncSpec) -> ok
install(Name, FuncSpec, Timeout) -> ok
Enables installation of alternative debug functions. An example of such a function is a trigger, a function that waits for some special event and performs some action when the event is generated. For example, turning on low-level tracing.
is called whenever a system event is
generated. This function is to return done
, or a new
Func
state. In the first case, the function is removed. It is
also removed if the function fails.
log(Name, Flag) -> ok | {ok, [system_event()]}
Name = name()
Flag = true | {true, N :: integer() >= 1} | false | get | print
log(Name, Flag, Timeout) -> ok | {ok, [system_event()]}
Name = name()
Flag = true | {true, N :: integer() >= 1} | false | get | print
Timeout = timeout()
Turns the logging of system events on or off. If on, a
maximum of
events are kept in the
debug structure (default is 10).
If
is get
, a list of all logged
events is returned.
If
is print
, the logged events
are printed to standard_io
.
The events are formatted with a function that is defined by the
process that generated the event (with a call to
handle_debug/4
).
log_to_file(Name, Flag) -> ok | {error, open_file}
Name = name()
Flag = (FileName :: string()) | false
log_to_file(Name, Flag, Timeout) -> ok | {error, open_file}
Name = name()
Flag = (FileName :: string()) | false
Timeout = timeout()
Enables or disables the logging of all system events in text
format to the file. The events are formatted with a function that is
defined by the process that generated the event (with a call to
handle_debug/4
).
no_debug(Name) -> ok
Name = name()
no_debug(Name, Timeout) -> ok
Name = name()
Timeout = timeout()
Turns off all debugging for the process. This includes
functions that are installed explicitly with function
install/2,3
,
for example, triggers.
remove(Name, Func) -> ok
remove(Name, Func, Timeout) -> ok
Removes an installed debug function from the
process.
must be the same as previously
installed.
replace_state(Name, StateFun) -> NewState
Name = name()
StateFun = fun((State :: term()) -> NewState :: term())
NewState = term()
replace_state(Name, StateFun, Timeout) -> NewState
Name = name()
StateFun = fun((State :: term()) -> NewState :: term())
Timeout = timeout()
NewState = term()
Replaces the state of the process, and returns the new state.
Note!
These functions are intended only to help with debugging, and are not to be called from normal code. They are provided for convenience, allowing developers to avoid having to create their own custom state replacement functions.
Function
provides a new state for the
process. Argument
and the
return value of
vary for different types of
processes as follows:
-
For a
gen_server
process,
is the state of the callback module andState
is a new instance of that state.NewState -
For a
gen_fsm
process,
is the tupleState {CurrentStateName, CurrentStateData}
, and
is a similar tuple, which can contain a new state name, new state data, or both.NewState -
For a
gen_statem
process,
is the tupleState {CurrentState,CurrentData}
, and
is a similar tuple, which can contain a new current state, new state data, or both.NewState -
For a
gen_event
process,
is the tupleState {Module, Id, HandlerState}
as follows:Module
The module name of the event handler.
Id
The ID of the handler (which is
false
if it was registered without an ID).HandlerState
The state of the handler.
is a similar tuple whereNewState Module
andId
are to have the same values as in
, but the value ofState HandlerState
can be different. Returning a
, whoseNewState Module
orId
values differ from those of
, leaves the state of the event handler unchanged. For aState gen_event
process,
is called once for each event handler registered in theStateFun gen_event
process.
If a
function decides not to effect any
change in process state, then regardless of process type, it can
return its
argument.
If a
function crashes or throws an
exception, the original state of the process is unchanged for
gen_server
, gen_fsm
, and gen_statem
processes.
For gen_event
processes, a crashing or
failing
function
means that only the state of the particular event handler it was
working on when it failed or crashed is unchanged; it can still
succeed in changing the states of other event
handlers registered in the same gen_event
process.
If the callback module exports a
system_replace_state/2
function, it is called in the
target process to replace its state using StateFun
. Its two
arguments are StateFun
and Misc
, where
Misc
is the same as the Misc
value returned by
get_status/1,2
.
A system_replace_state/2
function is expected to return
{ok, NewState, NewMisc}
, where NewState
is the new state
of the callback module, obtained by calling StateFun
, and
NewMisc
is
a possibly new value used to replace the original Misc
(required as Misc
often contains the state of the callback
module within it).
If the callback module does not export a
system_replace_state/2
function,
replace_state/2,3
assumes that Misc
is the state of the callback module,
passes it to StateFun
and uses the return value as
both the new state and as the new value of Misc
.
If the callback module's function system_replace_state/2
crashes or throws an exception, the caller exits with error
{callback_failed, {Module, system_replace_state}, {Class,
Reason}}
, where Module
is the name of the callback module
and Class
and Reason
indicate details of the exception.
If the callback module does not provide a
system_replace_state/2
function and StateFun
crashes or
throws an exception, the caller exits with error
{callback_failed, StateFun, {Class, Reason}}
.
Function system_replace_state/2
is primarily useful for
user-defined behaviors and modules that implement OTP
special processes. The
OTP behavior modules gen_server
,
gen_fsm
, gen_statem
, and gen_event
export this function, so callback modules for those
behaviors need not to supply their own.
resume(Name) -> ok
Name = name()
resume(Name, Timeout) -> ok
Name = name()
Timeout = timeout()
Resumes a suspended process.
statistics(Name, Flag) -> ok | {ok, Statistics}
Name = name()
Flag = true | false | get
Statistics = [StatisticsTuple] | no_statistics
StatisticsTuple =
{start_time, DateTime1} |
{current_time, DateTime2} |
{reductions, integer() >= 0} |
{messages_in, integer() >= 0} |
{messages_out, integer() >= 0}DateTime1 = DateTime2 = file:date_time()
statistics(Name, Flag, Timeout) -> ok | {ok, Statistics}
Name = name()
Flag = true | false | get
Statistics = [StatisticsTuple] | no_statistics
StatisticsTuple =
{start_time, DateTime1} |
{current_time, DateTime2} |
{reductions, integer() >= 0} |
{messages_in, integer() >= 0} |
{messages_out, integer() >= 0}DateTime1 = DateTime2 = file:date_time()
Timeout = timeout()
Enables or disables the collection of statistics. If
is get
,
the statistical collection is returned.
suspend(Name) -> ok
Name = name()
suspend(Name, Timeout) -> ok
Name = name()
Timeout = timeout()
Suspends the process. When the process is suspended, it only responds to other system messages, but not other messages.
terminate(Name, Reason) -> ok
Name = name()
Reason = term()
terminate(Name, Reason, Timeout) -> ok
Name = name()
Reason = term()
Timeout = timeout()
Orders the process to terminate with the
specified
. The termination is done
asynchronously, so it is not guaranteed that the process is
terminated when the function returns.
trace(Name, Flag) -> ok
Name = name()
Flag = boolean()
trace(Name, Flag, Timeout) -> ok
Name = name()
Flag = boolean()
Timeout = timeout()
Prints all system events on standard_io
. The events are
formatted with a function that is defined by the process that
generated the event (with a call to
handle_debug/4
).
Process Implementation Functions
The following functions are used when implementing a special process. This is an ordinary process, which does not use a standard behavior, but a process that understands the standard system messages.
Functions
debug_options(Options) -> [dbg_opt()]
Options = [Opt]
Opt =
trace |
log |
{log, integer() >= 1} |
statistics |
{log_to_file, FileName} |
{install, FuncSpec}FileName = file:name()
FuncSpec = {Func, FuncState}
Func = dbg_fun()
FuncState = term()
Can be used by a process that initiates a debug
structure from a list of options. The values of argument
are the same as for the corresponding
functions.
get_debug(Item, Debug, Default) -> term()
Item = log | statistics
Debug = [dbg_opt()]
Default = term()
Gets the data associated with a debug option.
is returned if
is not found. Can be
used by the process to retrieve debug data for printing before it
terminates.
handle_debug(Debug, FormFunc, Extra, Event) -> [dbg_opt()]
Debug = [dbg_opt()]
FormFunc = format_fun()
Extra = term()
Event = system_event()
This function is called by a process when it generates a
system event.
is a formatting
function, called as
to print the events,
which is necessary if tracing is activated.
is any extra information that the
process needs in the format function, for example, the process
name.
handle_system_msg(Msg, From, Parent, Module, Debug, Misc) ->
no_return()
Msg = term()
From = {pid(), Tag :: term()}
Parent = pid()
Module = module()
Debug = [dbg_opt()]
Misc = term()
This function is used by a process module to take care of system
messages. The process receives a
{system,
message and
passes
and
to this
function.
This function never returns. It calls either of the following functions:
-
, where the process continues the execution.Module :system_continue(Parent , NDebug,Misc ) -
, if the process is to terminate.Module :system_terminate(Reason,Parent ,Debug ,Misc )
must export the following:
system_continue/3
system_terminate/4
system_code_change/4
system_get_state/1
system_replace_state/2
Argument
can be used to save internal data
in a process, for example, its state. It is sent to
or
.
print_log(Debug) -> ok
Debug = [dbg_opt()]
Prints the logged system events in the debug structure,
using FormFunc
as defined when the event was
generated by a call to
handle_debug/4
.
Module:system_code_change(Misc, Module, OldVsn, Extra) -> {ok, NMisc}
Misc = term()
OldVsn = undefined | term()
Module = atom()
Extra = term()
NMisc = term()
Called from
handle_system_msg/6
when the process is to perform a
code change. The code change is used when the
internal data structure has changed. This function
converts argument Misc
to the new data
structure. OldVsn
is attribute vsn of the
old version of the Module
. If no such attribute is
defined, the atom undefined
is sent.
Module:system_continue(Parent, Debug, Misc) -> none()
Parent = pid()
Debug = [dbg_opt()]
Misc = term()
Called from
handle_system_msg/6
when the process is to continue
its execution (for example, after it has been
suspended). This function never returns.
Module:system_get_state(Misc) -> {ok, State}
Misc = term()
State = term()
Called from
handle_system_msg/6
when the process is to return a term that reflects its current state.
State
is the value returned by
get_state/2
.
Module:system_replace_state(StateFun, Misc) -> {ok, NState, NMisc}
StateFun = fun((State :: term()) -> NState)
Misc = term()
NState = term()
NMisc = term()
Called from
handle_system_msg/6
when the process is to replace
its current state. NState
is the value returned by
replace_state/3
.
Module:system_terminate(Reason, Parent, Debug, Misc) -> none()
Reason = term()
Parent = pid()
Debug = [dbg_opt()]
Misc = term()
Called from
handle_system_msg/6
when the process is to terminate.
For example, this function is called when
the process is suspended and its parent orders shutdown.
It gives the process a chance to do a cleanup. This function never
returns.