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
should also understand system messages such as debugging
messages and code change. These functions must be used to implement the use of system messages for a process; either directly, or through standard behaviours, such as gen_server
.
The default timeout is 5000 ms, unless otherwise specified. The
timeout
defines the time period 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 reference to a debug structure.
The debug structure is a list of dbg_opt()
.
dbg_opt()
is an internal data type used by the
handle_system_msg/6
function. No debugging is performed if it is an empty list.
System Messages
Processes which are not implemented as one of the standard behaviours must still understand system messages. There are three different messages which 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 has been received, the functionsys:handle_system_msg/6
is called in order to handle the request. -
Shutdown messages. If the process traps exits, it must be able to handle an shut-down 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
. -
There is one more message which the process must understand if the modules used to implement the process change dynamically during runtime. An example of such a process is the
gen_event
processes. This 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 execute a certain module. The process may at a later time 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 tty.
There are three predefined system events which 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 above.
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
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 (the 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
sys: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 textual
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 sys:handle_debug/4
).
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.
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
sys: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 have been installed explicitly with the
install
function, for example triggers.
suspend(Name) -> ok
Name = name()
suspend(Name, Timeout) -> ok
Name = name()
Timeout = timeout()
Suspends the process. When the process is suspended, it will only respond to other system messages, but not other messages.
resume(Name) -> ok
Name = name()
resume(Name, Timeout) -> ok
Name = name()
Timeout = timeout()
Resumes a suspended process.
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. The
argument is
reserved for each process to use as its own. The function
is called.
is
the old version of the
.
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 callback module's state, a gen_fsm
process
returns information such as its current state name and state data,
and a gen_event
process returns information about each of its
registered handlers. Callback modules for gen_server
,
gen_fsm
, and gen_event
can also customise the value
of
by exporting a format_status/2
function that contributes module-specific information;
see gen_server:format_status/2,
gen_fsm:format_status/2, and
gen_event:format_status/2
for more details.
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 state from the return values of
get_status/1
or
get_status/2
while debugging.
The value of
varies for different types of
processes. For a gen_server
process, the returned
is simply the callback module's state. For a gen_fsm
process,
is the tuple {CurrentStateName, CurrentStateData}
.
For a gen_event
process,
a list of tuples,
where each tuple corresponds to an event handler registered in the process and contains
{Module, Id, HandlerState}
, where Module
is the event handler's module name,
Id
is the handler's ID (which is the value false
if it was registered without
an ID), and HandlerState
is the handler's state.
If the callback module exports a system_get_state/1
function, it will be 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 the system_get_state/1
function is expected to extract the callback module's state from it. The system_get_state/1
function must return {ok, State}
where State
is the callback module's state.
If the callback module does not export a system_get_state/1
function, get_state/1,2
assumes the Misc
value is the callback module's state 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.
The system_get_state/1
function is primarily useful for user-defined
behaviours and modules that implement OTP special
processes. The gen_server
, gen_fsm
, and gen_event
OTP
behaviour modules export this function, and so callback modules for those behaviours
need not supply their own.
To obtain more information about a process, including its state, see get_status/1 and get_status/2.
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 they should not be be called from normal code. They are provided for convenience, allowing developers to avoid having to create their own custom state replacement functions.
The
function provides a new state for the process.
The
argument and
return value
of
vary for different types of processes. For a
gen_server
process,
is simply the callback module's
state, and
is a new instance of that state. For a
gen_fsm
process,
is the tuple
{CurrentStateName, CurrentStateData}
, and
is a similar tuple that may contain a new state name, new state data, or both.
For a gen_event
process,
is the tuple
{Module, Id, HandlerState}
where Module
is the event handler's module name,
Id
is the handler's ID (which is the value false
if it was registered without
an ID), and HandlerState
is the handler's state.
is a
similar tuple where Module
and Id
shall have the same values as in
but the value of HandlerState
may be different. Returning
a
whose Module
or Id
values differ from those of
will result in the event handler's state remaining unchanged. For a
gen_event
process,
is called once for each event handler
registered in the gen_event
process.
If a
function decides not to effect any change in process
state, then regardless of process type, it may simply return its
argument.
If a
function crashes or throws an exception, then
for gen_server
and gen_fsm
processes, the original state of the process is
unchanged. 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 will be 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 callback module's
new state obtained by calling StateFun
, and NewMisc
is a possibly new value used to
replace the original Misc
(required since Misc
often contains the callback
module's state within it).
If the callback module does not export a system_replace_state/2
function,
replace_state/2,3
assumes the Misc
value is the callback module's state, 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 system_replace_state/2
function 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}}
.
The system_replace_state/2
function is primarily useful for user-defined behaviours and
modules that implement OTP special processes. The
gen_server
, gen_fsm
, and gen_event
OTP behaviour modules export this function,
and so callback modules for those behaviours need not supply their own.
install(Name, FuncSpec) -> ok
install(Name, FuncSpec, Timeout) -> ok
This function makes it possible to install other debug functions than the ones defined above. 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. This could, for example, be turning on low level tracing.
is called whenever a system event is
generated. This function should return done
, or a new
func state. In the first case, the function is removed. It is removed
if the function fails.
remove(Name, Func) -> ok
remove(Name, Func, Timeout) -> ok
Removes a previously installed debug function from the
process.
must be the same as previously
installed.
terminate(Name, Reason) -> ok
Name = name()
Reason = term()
terminate(Name, Reason, Timeout) -> ok
Name = name()
Reason = term()
Timeout = timeout()
This function orders the process to terminate with the
given
. The termination is done
asynchronously, so there is no guarantee that the process is
actually terminated when the function returns.
Process Implementation Functions
The following functions are used when implementing a special process. This is an ordinary process which does not use a standard behaviour, but a process which 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()
This function can be used by a process that initiates a debug
structure from a list of options. The values of the
argument are the same as the corresponding
functions.
get_debug(Item, Debug, Default) -> term()
Item = log | statistics
Debug = [dbg_opt()]
Default = term()
This function gets the data associated with a debug option.
is returned if the
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 which is called as
in order to print
the events, which is necessary if tracing is activated.
is any extra information which the
process needs in the format function, for example the name
of the process.
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 that wishes to take care of system
messages. The process receives a {system,
message and passes the
and
to this
function.
This function never returns. It calls the function
where the
process continues the execution, or
if
the process should terminate. The
must export
system_continue/3
, system_terminate/4
,
system_code_change/4
, system_get_state/1
and
system_replace_state/2
(see below).
The
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
.
Mod:system_continue(Parent, Debug, Misc) -> none()
Parent = pid()
Debug = [dbg_opt()]
Misc = term()
This function is called from sys:handle_system_msg/6
when the process
should continue its execution (for example after it has been
suspended). This function never returns.
Mod:system_terminate(Reason, Parent, Debug, Misc) -> none()
Reason = term()
Parent = pid()
Debug = [dbg_opt()]
Misc = term()
This function is called from sys:handle_system_msg/6
when the process
should terminate. For example, this function is called when
the process is suspended and its parent orders shut-down.
It gives the process a chance to do a clean-up. This function never
returns.
Mod:system_code_change(Misc, Module, OldVsn, Extra) -> {ok, NMisc}
Misc = term()
OldVsn = undefined | term()
Module = atom()
Extra = term()
NMisc = term()
Called from sys:handle_system_msg/6
when the process
should perform a code change. The code change is used when the
internal data structure has changed. This function
converts the Misc
argument to the new data
structure. OldVsn
is the vsn attribute of the
old version of the Module
. If no such attribute was
defined, the atom undefined
is sent.
Mod:system_get_state(Misc) -> {ok, State}
Misc = term()
State = term()
This function is called from sys:handle_system_msg/6
when the process
should return a term that reflects its current state. State
is the
value returned by sys:get_state/2
.
Mod:system_replace_state(StateFun, Misc) -> {ok, NState, NMisc}
StateFun = fun((State :: term()) -> NState)
Misc = term()
NState = term()
NMisc = term()
This function is called from sys:handle_system_msg/6
when the process
should replace its current state. NState
is the value returned by
sys:replace_state/3
.