![[Ericsson AB]](min_head.gif)
This module contains functions for sending system messages used by programs, and messaged 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 following types are used in the functions defined below:
Name = pid() | atom() | {global, atom()}
Timeout = int() >= 0 | infinity
system_event() = {in, Msg} | {in, Msg, From} | {out,
Msg, To} | term()
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.
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:
{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.
{'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.
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.
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.
log(Name,Flag)
log(Name,Flag,Timeout) -> ok | {ok, [system_event()]}
Types:
Flag = true | {true, N} | false | get | print
N = integer() > 0
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)
log_to_file(Name,Flag,Timeout) -> ok | {error, open_file}
Types:
Flag = FileName | false
FileName = string()
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)
statistics(Name,Flag,Timeout) -> ok | {ok, Statistics}
Types:
Flag = true | false | get
Statistics = [{start_time, {Date1, Time1}}, {current_time,
{Date, Time2}}, {reductions, integer()}, {messages_in,
integer()}, {messages_out, integer()}]
Date1 = Date2 = {Year, Month, Day}
Time1 = Time2 = {Hour, Min, Sec}
Enables or disables the collection of statistics. If Flag is
get, the statistical collection is returned.
trace(Name,Flag)
trace(Name,Flag,Timeout) -> void()
Types:
Flag = boolean()
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)
no_debug(Name,Timeout) -> void()
Turns off all debugging for the process. This includes
functions that have been installed explicitly with the
install function, for example triggers.
suspend(Name)
suspend(Name,Timeout) -> void()
Suspends the process. When the process is suspended, it will only respond to other system messages, but not other messages.
resume(Name)
resume(Name,Timeout) -> void()
Resumes a suspended process.
change_code(Name, Module, OldVsn, Extra)
change_code(Name, Module, OldVsn, Extra, Timeout) -> ok | {error, Reason}
Types:
OldVsn = undefined | term()
Module = atom()
Extra = 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
Mod:system_code_change/4 is called. OldVsn is
the old version of the Module.
get_status(Name)
get_status(Name,Timeout) -> {status, Pid, {module,
Mod}, [PDict, SysState, Parent, Dbg, Misc]}
Types:
PDict = [{Key, Value}]
SysState = running | suspended
Parent = pid()
Dbg = [dbg_opt()]
Misc = term()
Gets the status of the process.
install(Name,{Func,FuncState})
install(Name,{Func,FuncState},Timeout)
Types:
Func = dbg_fun()
dbg_fun() = fun(FuncState, Event, ProcState) -> done |
NewFuncState
FuncState = term()
Event = system_event()
ProcState = term()
NewFuncState = term()
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)
remove(Name,Func,Timeout) -> void()
Types:
Func = dbg_fun()
Removes a previously installed debug function from the
process. Func must be the same as previously
installed.
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.
debug_options(Options) -> [dbg_opt()]
Types:
Options = [Opt]
Opt = trace | log | statistics | {log_to_file, FileName} |
{install, {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
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([dbg_opt()],FormFunc,Extra,Event) ->
[dbg_opt()]
Types:
FormFunc = dbg_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)
Types:
Msg = term()
From = pid()
Parent = pid()
Module = atom()
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, 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
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)
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)
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.