Install Now
sys - A functional interface to system messages.
Contents
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 module.
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 returned from the callback module.
State is the new server state.
{continue,Continuation}:
Is produced by gen_server when a {continue,Continuation} tuple 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
postponed 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 entered.
{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())
Description
This module contains functions for sending system messages used by programs, and messages used for
debugging purposes.
Functions used for implementation of processes are also expected to understand 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.
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 returned if 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, called as FormFunc(Device,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 version 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 returned 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 replace_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 terminate. 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.17 sys(3erl)
Name
sys - A functional interface to system messages.
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.
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 always up to the process itself to format these events.
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,
function 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 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.
* 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,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 that execute a certain module.
The process can later be suspended and ordered to perform a code change for one of its modules.
PNG Icons