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 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.

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}

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).

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.

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

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.

replace_state(Name, StateFun, Timeout) -> NewState

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.

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.

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.

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.

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, and
system_code_change/4 (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

Mod:system_terminate(Reason, Parent, Debug, Misc) -> none()

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.