sys(3erl) Erlang Module Definition sys(3erl)
NAME
sys - A functional interface to system messages.
DESCRIPTION
This module contains functions for sending system messages used by pro-
grams, and messages used for debugging purposes.
Functions used for implementation of processes are also expected to un-
derstand 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, func-
tion handle_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 mes-
sage {'EXIT', Parent, Reason} from the parent is an order to termi-
nate. The process must terminate when this message is received,
normally with the same Reason as Parent.
* 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 {_Label, {From,
Ref}, get_modules}. The reply to this message is From ! {Ref, Mod-
ules}, where Modules 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.
Four predefined system events are used when a process receives or sends
a message. The process can also define its own system events. It is al-
ways up to the process itself to format these events.
DATA TYPES
name() =
pid() | atom() | {global, term()} | {via, module(), term()}
system_event() =
{in, Msg :: term()} |
{in, Msg :: term(), State :: term()} |
{out, Msg :: term(), To :: term()} |
{out, Msg :: term(), To :: term(), State :: term()} |
{noreply, State :: term()} |
{continue, Continuation :: term()} |
{code_change, Event :: term(), State :: term()} |
{postpone,
Event :: term(),
State :: term(),
NextState :: term()} |
{consume,
Event :: term(),
State :: term(),
NextState :: term()} |
{start_timer, Action :: term(), State :: term()} |
{insert_timeout, Event :: term(), State :: term()} |
{enter, State :: term()} |
{terminate, Reason :: term(), State :: term()} |
term()
{in,Msg}:
Is produced by gen_server and gen_event when the message Msg
arrives.
{in,Msg,State}:
Is produced by gen_statem when the message Msg arrives in
state State.
For gen_statem the Msg term is an {EventType,EventContent}
tuple.
{out,Msg,To}:
Is produced by gen_statem when the reply Msg is sent back to
To by returning a {reply,To,Msg} action from the callback
module.
To is of the same type as the first argument to
gen_statem:reply/2.
{out,Msg,To,State}:
Is produced by gen_server when the reply Msg is sent back to
To by returning a {reply,...} tuple from the callback mod-
ule.
To is of the same type as the first argument to
gen_server:reply/2.
State is the new server state.
{noreply,State}:
Is produced by gen_server when a {noreply,...} tuple is re-
turned from the callback module.
State is the new server state.
{continue,Continuation}:
Is produced by gen_server when a {continue,Continuation} tu-
ple is returned from the callback module.
{code_change,Event,State}:
Is produced by gen_statem when the message Event arrives in
state State as the first event after a code change.
Event is an {EventType,EventContent} tuple.
{postpone,Event,State,NextState} :
Is produced by gen_statem when the message Event is post-
poned in state State. NextState is the new state.
Event is an {EventType,EventContent} tuple.
{consume,Event,State,NextState} :
Is produced by gen_statem when the message Event is consumed
in state State. NextState is the new state.
Event is an {EventType,EventContent} tuple.
{start_timer,Action,State} :
Is produced by gen_statem when the action Action starts a
timer in state State.
{insert_timeout,Event,State} :
Is produced by gen_statem when a timeout zero action inserts
event Event in state State.
Event is an {EventType,EventContent} tuple.
{enter,State} :
Is produced by gen_statem when the first state State is en-
tered.
{terminate,Reason,State} :
Is produced by gen_statem when it terminates with reason
Reason in state State.
dbg_opt()
See the introduction of this manual page.
dbg_fun() =
fun((FuncState :: term(),
Event :: system_event(),
ProcState :: term()) ->
done | (NewFuncState :: term()))
debug_option() =
trace | log |
{log, N :: integer() >= 1} |
statistics |
{log_to_file, FileName :: file:name()} |
{install,
{Func :: dbg_fun(), FuncState :: term()} |
{FuncId :: term(), Func :: dbg_fun(), FuncState :: term()}}
format_fun() =
fun((Device :: io:device() | file:io_device(),
Event :: system_event(),
Extra :: term()) ->
any())
EXPORTS
change_code(Name, Module, OldVsn, Extra) -> ok | {error, Reason}
change_code(Name, Module, OldVsn, Extra, Timeout) ->
ok | {error, Reason}
Types:
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 Extra is reserved for each
process to use as its own. Function Module:system_code_change/4
is called. OldVsn is the old version of the Module.
get_state(Name) -> State
get_state(Name, Timeout) -> State
Types:
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 hav-
ing 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 State varies for different types of processes, as
follows:
* For a gen_server process, the returned State is the state of
the callback module.
* For a gen_statem process, State is the tuple {Cur-
rentState,CurrentData}.
* For a gen_event process, State is a list of tuples, where
each tuple corresponds to an event handler registered in the
process and contains {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 sys-
tem_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 {call-
back_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_statem, and gen_event OTP behavior modules ex-
port 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
get_status(Name, Timeout) -> Status
Types:
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 Misc varies for different types of processes, for
example:
* A gen_server process returns the state of the callback mod-
ule.
* A gen_statem process returns information, such as its cur-
rent state name and state data.
* A gen_event process returns information about each of its
registered handlers.
Callback modules for gen_server, gen_statem, and gen_event can
also change the value of Misc by exporting a function for-
mat_status/2, which contributes module-specific information. For
details, see gen_server:format_status/2, gen_statem:format_sta-
tus/2, and gen_event:format_status/2.
install(Name, FuncSpec) -> ok
install(Name, FuncSpec, Timeout) -> ok
Types:
Name = name()
FuncSpec = {Func, FuncState} | {FuncId, Func, FuncState}
FuncId = term()
Func = dbg_fun()
FuncState = term()
Timeout = timeout()
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 gener-
ated. For example, turning on low-level tracing.
Func is called whenever a system event is generated. This func-
tion 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. If one debug function should be installed more times, a
unique FuncId must be specified for each installation.
log(Name, Flag) -> ok | {ok, [system_event()]}
log(Name, Flag, Timeout) -> ok | {ok, [system_event()]}
Types:
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 N events are kept in the debug structure (default is 10).
If Flag is get, a list of all logged events is returned.
If Flag 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_de-
bug/4).
log_to_file(Name, Flag) -> ok | {error, open_file}
log_to_file(Name, Flag, Timeout) -> ok | {error, open_file}
Types:
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). The file is opened with encoding UTF-8.
no_debug(Name) -> ok
no_debug(Name, Timeout) -> ok
Types:
Name = name()
Timeout = timeout()
Turns off all debugging for the process. This includes functions
that are installed explicitly with function install/2,3, for ex-
ample, triggers.
remove(Name, FuncOrFuncId :: Func | FuncId) -> ok
remove(Name, FuncOrFuncId :: Func | FuncId, Timeout) -> ok
Types:
Name = name()
Func = dbg_fun()
FuncId = term()
Timeout = timeout()
Removes an installed debug function from the process. Func or
FuncId must be the same as previously installed.
replace_state(Name, StateFun) -> NewState
replace_state(Name, StateFun, Timeout) -> NewState
Types:
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 StateFun provides a new state for the process. Argument
State and the NewState return value of StateFun vary for differ-
ent types of processes as follows:
* For a gen_server process, State is the state of the callback
module and NewState is a new instance of that state.
* For a gen_statem process, State is the tuple {Cur-
rentState,CurrentData}, and NewState is a similar tuple,
which can contain a new current state, new state data, or
both.
* For a gen_event process, State is the tuple {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.
NewState is a similar tuple where Module and Id are to have
the same values as in State, but the value of HandlerState
can be different. Returning a NewState, whose Module or Id
values differ from those of State, leaves the state of the
event handler unchanged. For a gen_event process, StateFun
is called once for each event handler registered in the
gen_event process.
If a StateFun function decides not to effect any change in
process state, then regardless of process type, it can return
its State argument.
If a StateFun function crashes or throws an exception, the orig-
inal state of the process is unchanged for gen_server, and
gen_statem processes. For gen_event processes, a crashing or
failing StateFun function means that only the state of the par-
ticular 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 func-
tion, 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, New-
State, 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 {call-
back_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-de-
fined behaviors and modules that implement OTP special pro-
cesses. The OTP behavior modules gen_server, gen_statem, and
gen_event export this function, so callback modules for those
behaviors need not to supply their own.
resume(Name) -> ok
resume(Name, Timeout) -> ok
Types:
Name = name()
Timeout = timeout()
Resumes a suspended process.
statistics(Name, Flag) -> ok | {ok, Statistics}
statistics(Name, Flag, Timeout) -> ok | {ok, Statistics}
Types:
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 Flag is
get, the statistical collection is returned.
suspend(Name) -> ok
suspend(Name, Timeout) -> ok
Types:
Name = name()
Timeout = timeout()
Suspends the process. When the process is suspended, it only re-
sponds to other system messages, but not other messages.
terminate(Name, Reason) -> ok
terminate(Name, Reason, Timeout) -> ok
Types:
Name = name()
Reason = term()
Timeout = timeout()
Orders the process to terminate with the specified Reason. The
termination is done asynchronously, so it is not guaranteed that
the process is terminated when the function returns.
trace(Name, Flag) -> ok
trace(Name, Flag, Timeout) -> ok
Types:
Name = name()
Flag = boolean()
Timeout = timeout()
Prints all system events on standard_io. The events are format-
ted with a function that is defined by the process that gener-
ated 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.
EXPORTS
debug_options(Options :: [Opt :: debug_option()]) -> [dbg_opt()]
Can be used by a process that initiates a debug structure from a
list of options. The values of argument Opt are the same as for
the corresponding functions.
get_debug(Item, Debug, Default) -> term()
Types:
Item = log | statistics
Debug = [dbg_opt()]
Default = term()
Warning:
get_debug/3 is deprecated since it returns data of an internal
type only useful for debugging.
Gets the data associated with a debug option. Default is re-
turned if Item is not found. Can be used by the process to re-
trieve debug data for printing before it terminates.
handle_debug(Debug, FormFunc, Extra, Event) -> [dbg_opt()]
Types:
Debug = [dbg_opt()]
FormFunc = format_fun()
Extra = term()
Event = system_event()
This function is called by a process when it generates a system
event. FormFunc is a formatting function, called as FormFunc(De-
vice, Event, Extra) to print the events, which is necessary if
tracing is activated. Extra 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()
Types:
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, From, Msg} message and
passes Msg and From to this function.
This function never returns. It calls either of the following
functions:
* Module:system_continue(Parent, NDebug, Misc), where the
process continues the execution.
* Module:system_terminate(Reason, Parent, Debug, Misc), if the
process is to terminate.
Module must export the following:
* system_continue/3
* system_terminate/4
* system_code_change/4
* system_get_state/1
* system_replace_state/2
Argument Misc can be used to save internal data in a process,
for example, its state. It is sent to Module:system_continue/3
or Module:system_terminate/4.
print_log(Debug) -> ok
Types:
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.
get_log(Debug) -> [system_event()]
Types:
Debug = [dbg_opt()]
Returns the logged system events in the debug structure, that is
the last argument to handle_debug/4.
Module:system_code_change(Misc, Module, OldVsn, Extra) -> {ok, NMisc}
Types:
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 ver-
sion of the Module. If no such attribute is defined, the atom
undefined is sent.
Module:system_continue(Parent, Debug, Misc) -> none()
Types:
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}
Types:
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 re-
turned by get_state/2.
Module:system_replace_state(StateFun, Misc) -> {ok, NState, NMisc}
Types:
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 re-
place_state/3.
Module:system_terminate(Reason, Parent, Debug, Misc) -> none()
Types:
Reason = term()
Parent = pid()
Debug = [dbg_opt()]
Misc = term()
Called from handle_system_msg/6 when the process is to termi-
nate. 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.
Ericsson AB stdlib 3.13 sys(3erl)