table of contents
other versions
- jessie 1:17.3-dfsg-4+deb8u2
- jessie-backports 1:19.2.1+dfsg-2+deb9u1~bpo8+1
- stretch 1:19.2.1+dfsg-2+deb9u2
- testing 1:21.2.5+dfsg-1
- unstable 1:21.2.6+dfsg-1
- experimental 1:22.0~rc1+dfsg-1
other sections
sys(3erl) | Erlang Module Definition | sys(3erl) |
NAME¶
sys - A Functional Interface to System MessagesDESCRIPTION¶
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 function sys: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 same Reason as Parent.
- *
- 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 is From ! {modules, Modules}, 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 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.DATA 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())
EXPORTS¶
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 (the 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 sys:handle_debug/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 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}
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()
| {current_time, DateTime2}
| {reductions, integer() >= 0}
| {messages_in, integer() >= 0}
| {messages_out, integer() >= 0}
Enables or disables the collection of statistics. If Flag is get,
the statistical collection is returned.
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 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
no_debug(Name, Timeout) -> ok
Types:
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
suspend(Name, Timeout) -> ok
Types:
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
resume(Name, Timeout) -> ok
Types:
Name = name()
Timeout = timeout()
Resumes a suspended process.
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. The Extra argument is reserved for each process to use as its
own. The function Module:system_code_change/4 is called. OldVsn
is the old version of the Module.
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())
{status, Pid :: pid(), {module, Module :: module()}, [SItem]}
| (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 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
Misc 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
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 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 State varies for different types of processes. For a
gen_server process, the returned State is simply the callback
module's state. For a gen_fsm process, State is the tuple
{CurrentStateName, CurrentStateData}. For a gen_event process,
State 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
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 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 StateFun function provides a new state for the process. The
State argument and NewState return value of StateFun vary
for different types of processes. For a gen_server process,
State is simply the callback module's state, and NewState is a
new instance of that state. For a gen_fsm process, State is the
tuple {CurrentStateName, CurrentStateData}, and NewState is a
similar tuple that may contain a new state name, new state data, or both. For
a gen_event process, State 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.
NewState is a similar tuple where Module and Id shall
have the same values as in State but the value of HandlerState
may be different. Returning a NewState whose Module or Id
values differ from those of State will result in the event handler's
state remaining 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 may simply return its State
argument.
If a StateFun 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
StateFun 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
Types:
Name = name()
FuncSpec = {Func, FuncState}
Func = dbg_fun()
FuncState = term()
Timeout = timeout()
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.
Func 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
Types:
Name = name()
Func = dbg_fun()
Timeout = timeout()
Removes a previously installed debug function from the process. Func must
be the same as previously installed.
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.EXPORTS¶
debug_options(Options) -> [dbg_opt()]
Types:
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()
| log
| {log, integer() >= 1}
| statistics
| {log_to_file, FileName}
| {install, FuncSpec}
This function can be used by a process that initiates a debug structure from a
list of options. The values of the Opt argument are the same as the
corresponding functions.
get_debug(Item, Debug, Default) -> term()
Types:
Item = log | statistics
Debug = [ dbg_opt()]
Default = term()
This function gets the data associated with a debug option. Default is
returned if the Item 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()]
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 which is called as
FormFunc(Device, Event, Extra) in order to print the events, which is
necessary if tracing is activated. Extra 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()
Types:
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, From, Msg} message and passes
the Msg and From to this function.
This function never returns. It calls the function
Module:system_continue(Parent, NDebug, Misc) where the process
continues the execution, or Module:system_terminate(Reason, Parent, Debug,
Misc) if the process should terminate. The Module must export
system_continue/3, system_terminate/4,
system_code_change/4, system_get_state/1 and
system_replace_state/2 (see below).
The Misc argument 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.
Mod:system_continue(Parent, Debug, Misc) -> none()
Types:
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()
Types:
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}
Types:
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}
Types:
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}
Types:
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.
stdlib 2.2 | Ericsson AB |