File: sys.html

package info (click to toggle)
erlang-doc-html 1%3A8.0-1
links: PTS
area: main
in suites: woody
size: 18,028 kB
ctags: 7,419
sloc: perl: 1,841; ansic: 323; erlang: 155
file content (402 lines) | stat: -rw-r--r-- 16,706 bytes
<HTML>
<HEAD>
<!-- refpage -->
<TITLE>sys</TITLE>
</HEAD>
<BODY BGCOLOR="#FFFFFF">
<CENTER>


<A HREF="http://www.erlang.se"><IMG BORDER=0 ALT="[Erlang Systems]" SRC="min_head.gif"></A>
<H1>sys</H1>
</CENTER>
<H3>MODULE</H3>
<UL>
sys</UL>
<H3>MODULE SUMMARY</H3>
<UL>
A Functional Interface to System Messages</UL>
<H3>DESCRIPTION</H3>
<UL>
<P>This module contains functions for sending system messages used by programs, and messaged used for debugging purposes.

<P>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 <CODE>gen_server</CODE>.<P>The following types are used in the functions defined below:
<P><UL>
<LI><CODE>Name = pid() | atom() | {global, atom()}</CODE>
<BR>
</LI><BR>
<LI><CODE>Timeout = int() &#62;= 0 | infinity</CODE>
<BR>
</LI><BR>
<LI><CODE>system_event() = {in, Msg} | {in, Msg, From} | {out,
         Msg, To} | term()</CODE>
<BR>
</LI><BR>
</UL>
<P>The default timeout is 5000 ms, unless otherwise specified. The
<CODE>timeout</CODE> defines the time period to wait for the process to
respond to a request. If the process does not respond, the
function evaluates <CODE>exit({timeout, {M, F, A}})</CODE>.

<P>The functions make reference to a debug structure.
The debug structure is a list of <CODE>dbg_opt()</CODE>.
<CODE>dbg_opt()</CODE> is an internal data type used by the
<CODE>handle_system_msg/6</CODE> function. No debugging is performed if it is an empty list.

</UL>
<H3>System Messages</H3>
<UL>
<P>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:

<P><UL>
<LI>Plain system messages. These are received as
         <CODE>{system, From, Msg}</CODE>. The content and meaning of
         this message are not interpreted by the
         receiving process module. When a system message has been
         received, the function <CODE>sys:handle_system_msg/6</CODE>
         is called in order to handle the request.

<BR>
</LI><BR>
<LI>Shutdown messages. If the process traps exits, it must
         be able to handle an shut-down request from its parent, the
         supervisor. The message <CODE>{'EXIT', Parent, Reason}</CODE>
         from the parent is an order to terminate. The process must terminate when this message is received, normally with the
         same <CODE>Reason</CODE> as <CODE>Parent</CODE>.

<BR>
</LI><BR>
<LI>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 <CODE>gen_event</CODE> processes. This message is <CODE>{get_modules, From}</CODE>. The reply to this message is <CODE>From ! {modules, Modules}</CODE>,
where <CODE>Modules</CODE> is a list of the currently active modules in the process.

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

<BR>
</LI><BR>
</UL>
</UL>
<H3>System Events</H3>
<UL>
<P>When debugging a process with the functions of this
module, the process generates <STRONG>system_events</STRONG> which are
then treated in the debug function. For example, <CODE>trace</CODE>
formats the system events to the tty.

<P>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.
</UL>
<H3>EXPORTS</H3>
<P><A NAME="log%2"><STRONG><CODE>log(Name,Flag)</CODE></STRONG></A><BR>
<A NAME="log%3"><STRONG><CODE>log(Name,Flag,Timeout) -&#62; ok | {ok, [system_event()]}</CODE></STRONG></A><BR>
<P><UL>Types:
<UL>
<STRONG><CODE>Flag = true | {true, N} | false | get | print</CODE></STRONG><BR>
<STRONG><CODE>N = integer() &#62; 0</CODE></STRONG><BR>
</UL>
</UL>
<UL>
<P>Turns the logging of system events On or Off. If On, a
        maximum of <CODE>N</CODE> events are kept in the
        debug structure (the default is 10). If <CODE>Flag</CODE> is <CODE>get</CODE>, a list of all
        logged events is returned. If <CODE>Flag</CODE> is <CODE>print</CODE>, the
        logged events are printed to <CODE>standard_io</CODE>. The events are
        formatted with a function that is defined by the process that
        generated the event (with a call to
        <CODE>sys:handle_debug/4</CODE>).
</UL>
<P><A NAME="log_to_file%2"><STRONG><CODE>log_to_file(Name,Flag)</CODE></STRONG></A><BR>
<A NAME="log_to_file%3"><STRONG><CODE>log_to_file(Name,Flag,Timeout) -&#62; ok | {error, open_file}</CODE></STRONG></A><BR>
<P><UL>Types:
<UL>
<STRONG><CODE>Flag = FileName | false</CODE></STRONG><BR>
<STRONG><CODE>FileName = string()</CODE></STRONG><BR>
</UL>
</UL>
<UL>
<P>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 <CODE>sys:handle_debug/4</CODE>).
</UL>
<P><A NAME="statistics%2"><STRONG><CODE>statistics(Name,Flag)</CODE></STRONG></A><BR>
<A NAME="statistics%3"><STRONG><CODE>statistics(Name,Flag,Timeout) -&#62; ok | {ok, Statistics} </CODE></STRONG></A><BR>
<P><UL>Types:
<UL>
<STRONG><CODE>Flag = true | false | get</CODE></STRONG><BR>
<STRONG><CODE>Statistics = [{start_time, {Date1, Time1}}, {current_time,
{Date, Time2}}, {reductions, integer()}, {messages_in,
integer()}, {messages_out, integer()}]</CODE></STRONG><BR>
<STRONG><CODE>Date1 = Date2 = {Year, Month, Day}</CODE></STRONG><BR>
<STRONG><CODE>Time1 = Time2 = {Hour, Min, Sec}</CODE></STRONG><BR>
</UL>
</UL>
<UL>
<P>Enables or disables the collection of statistics. If <CODE>Flag</CODE> is
        <CODE>get</CODE>, the statistical collection is returned.
</UL>
<P><A NAME="trace%2"><STRONG><CODE>trace(Name,Flag)</CODE></STRONG></A><BR>
<A NAME="trace%3"><STRONG><CODE>trace(Name,Flag,Timeout) -&#62; void()</CODE></STRONG></A><BR>
<P><UL>Types:
<UL>
<STRONG><CODE>Flag = boolean()</CODE></STRONG><BR>
</UL>
</UL>
<UL>
<P>Prints all system events on <CODE>standard_io</CODE>. The events are
        formatted with a function that is defined by the process that
        generated the event (with a call to
        <CODE>sys:handle_debug/4</CODE>).
</UL>
<P><A NAME="no_debug%1"><STRONG><CODE>no_debug(Name)</CODE></STRONG></A><BR>
<A NAME="no_debug%2"><STRONG><CODE>no_debug(Name,Timeout) -&#62; void()</CODE></STRONG></A><BR>
<UL>
<P>Turns off all debugging for the process. This includes
        functions that have been installed explicitly with the
        <CODE>install</CODE> function, for example triggers.
</UL>
<P><A NAME="suspend%1"><STRONG><CODE>suspend(Name)</CODE></STRONG></A><BR>
<A NAME="suspend%2"><STRONG><CODE>suspend(Name,Timeout) -&#62; void()</CODE></STRONG></A><BR>
<UL>
<P>Suspends the process. When the process is suspended, it
        will only respond to other system messages, but not other
        messages.
</UL>
<P><A NAME="resume%1"><STRONG><CODE>resume(Name)</CODE></STRONG></A><BR>
<A NAME="resume%2"><STRONG><CODE>resume(Name,Timeout) -&#62; void()</CODE></STRONG></A><BR>
<UL>
<P>Resumes a suspended process.
</UL>
<P><A NAME="change_code%4"><STRONG><CODE>change_code(Name, Module, OldVsn, Extra)</CODE></STRONG></A><BR>
<A NAME="change_code%5"><STRONG><CODE>change_code(Name, Module, OldVsn, Extra, Timeout) -&#62; ok | {error, Reason}</CODE></STRONG></A><BR>
<P><UL>Types:
<UL>
<STRONG><CODE>OldVsn = undefined | term()</CODE></STRONG><BR>
<STRONG><CODE>Module = atom()</CODE></STRONG><BR>
<STRONG><CODE>Extra = term()</CODE></STRONG><BR>
</UL>
</UL>
<UL>
<P>Tells the process to change code. The process must be
suspended to handle this message. The <CODE>Extra</CODE> argument is
reserved for each process to use as its own. The function
<CODE>Mod:system_code_change/4</CODE> is called. <CODE>OldVsn</CODE> is
the old version of the <CODE>Module</CODE>.
</UL>
<P><A NAME="get_status%1"><STRONG><CODE>get_status(Name)</CODE></STRONG></A><BR>
<A NAME="get_status%2"><STRONG><CODE>get_status(Name,Timeout) -&#62; {status, Pid, {module,
Mod}, [PDict, SysState, Parent, Dbg, Misc]}
</CODE></STRONG></A><BR>
<P><UL>Types:
<UL>
<STRONG><CODE>PDict = [{Key, Value}]</CODE></STRONG><BR>
<STRONG><CODE>SysState = running | suspended</CODE></STRONG><BR>
<STRONG><CODE>Parent = pid()</CODE></STRONG><BR>
<STRONG><CODE>Dbg = [dbg_opt()]</CODE></STRONG><BR>
<STRONG><CODE>Misc = term()</CODE></STRONG><BR>
</UL>
</UL>
<UL>
<P>Gets the status of the process.
</UL>
<P><A NAME="install%3"><STRONG><CODE>install(Name,{Func,FuncState})</CODE></STRONG></A><BR>
<A NAME="install%4"><STRONG><CODE>install(Name,{Func,FuncState},Timeout)</CODE></STRONG></A><BR>
<P><UL>Types:
<UL>
<STRONG><CODE>Func = dbg_fun()</CODE></STRONG><BR>
<STRONG><CODE>dbg_fun() = fun(FuncState, Event, ProcState) -&#62; done |
        NewFuncState</CODE></STRONG><BR>
<STRONG><CODE>FuncState = term()</CODE></STRONG><BR>
<STRONG><CODE>Event = system_event()</CODE></STRONG><BR>
<STRONG><CODE>ProcState = term()</CODE></STRONG><BR>
<STRONG><CODE>NewFuncState = term()</CODE></STRONG><BR>
</UL>
</UL>
<UL>
<P>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.

<P><CODE>Func</CODE> is called whenever a system event is
generated. This function should return <CODE>done</CODE>, or a new
func state. In the first case, the function is removed. It is removed 
if the function fails.
</UL>
<P><A NAME="remove%2"><STRONG><CODE>remove(Name,Func)</CODE></STRONG></A><BR>
<A NAME="remove%3"><STRONG><CODE>remove(Name,Func,Timeout) -&#62; void()</CODE></STRONG></A><BR>
<P><UL>Types:
<UL>
<STRONG><CODE>Func = dbg_fun()</CODE></STRONG><BR>
</UL>
</UL>
<UL>
<P>Removes a previously installed debug function from the
        process. <CODE>Func</CODE> must be the same as previously
        installed.
</UL>
<H3>Process Implementation Functions</H3>
<UL>
<P>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.
</UL>
<H3>EXPORTS</H3>
<P><A NAME="debug_options%1"><STRONG><CODE>debug_options(Options) -&#62; [dbg_opt()]</CODE></STRONG></A><BR>
<P><UL>Types:
<UL>
<STRONG><CODE>Options = [Opt]</CODE></STRONG><BR>
<STRONG><CODE>Opt = trace | log | statistics | {log_to_file, FileName} |
{install, {Func, FuncState}}</CODE></STRONG><BR>
<STRONG><CODE>Func = dbg_fun()</CODE></STRONG><BR>
<STRONG><CODE>FuncState = term()</CODE></STRONG><BR>
</UL>
</UL>
<UL>
<P>This function can be used by a process that initiates a debug
        structure from a list of options. The values of the
        <CODE>Opt</CODE> argument are the same as the corresponding
        functions.
</UL>
<P><A NAME="get_debug%3"><STRONG><CODE>get_debug(Item,Debug,Default) -&#62; term()</CODE></STRONG></A><BR>
<P><UL>Types:
<UL>
<STRONG><CODE>Item = log | statistics</CODE></STRONG><BR>
<STRONG><CODE>Debug = [dbg_opt()]</CODE></STRONG><BR>
<STRONG><CODE>Default = term()</CODE></STRONG><BR>
</UL>
</UL>
<UL>
<P>This function gets the data associated with a debug option. <CODE>Default</CODE> is returned if the
        <CODE>Item</CODE> is not found. Can be
        used by the process to retrieve debug data for printing
        before it terminates.
</UL>
<P><A NAME="handle_debug%1"><STRONG><CODE>handle_debug([dbg_opt()],FormFunc,Extra,Event) -&#62;
[dbg_opt()]</CODE></STRONG></A><BR>
<P><UL>Types:
<UL>
<STRONG><CODE>FormFunc = dbg_fun()</CODE></STRONG><BR>
<STRONG><CODE>Extra = term()</CODE></STRONG><BR>
<STRONG><CODE>Event = system_event()</CODE></STRONG><BR>
</UL>
</UL>
<UL>
<P>This function is called by a process when it generates a system event. <CODE>FormFunc</CODE> is a formatting function which is called as <CODE>FormFunc(Device, Event, Extra)</CODE> in order to print the events, which is necessary if tracing is activated. <CODE>Extra</CODE> is any
extra information which the process needs in the format function, for example the name of the process.
</UL>
<P><A NAME="handle_system_msg%6"><STRONG><CODE>handle_system_msg(Msg,From,Parent,Module,Debug,Misc)</CODE></STRONG></A><BR>
<P><UL>Types:
<UL>
<STRONG><CODE>Msg = term()</CODE></STRONG><BR>
<STRONG><CODE>From = pid()</CODE></STRONG><BR>
<STRONG><CODE>Parent = pid()</CODE></STRONG><BR>
<STRONG><CODE>Module = atom()</CODE></STRONG><BR>
<STRONG><CODE>Debug = [dbg_opt()]</CODE></STRONG><BR>
<STRONG><CODE>Misc = term()</CODE></STRONG><BR>
</UL>
</UL>
<UL>
<P>This function is used by a process module that wishes to take care of system
messages. The process receives a <CODE>{system, From, Msg}</CODE>
message and passes the <CODE>Msg</CODE> and <CODE>From</CODE> to this
function.

<P>This function <STRONG>never</STRONG> returns. It calls the function
<CODE>Module:system_continue(Parent, NDebug, Misc)</CODE> where the
process continues the execution, or
<CODE>Module:system_terminate(Reason, Parent, Debug, Misc)</CODE> if
the process should terminate. The <CODE>Module</CODE> must export
<CODE>system_continue/3</CODE>, <CODE>system_terminate/4</CODE>, and
<CODE>system_code_change/4</CODE> (see below).

<P>The <CODE>Misc</CODE> argument can be used to save internal data
in a process, for example its state. It is sent to
<CODE>Module:system_continue/3</CODE> or
<CODE>Module:system_terminate/4</CODE>
</UL>
<P><A NAME="print_log%1"><STRONG><CODE>print_log(Debug) -&#62; void()</CODE></STRONG></A><BR>
<P><UL>Types:
<UL>
<STRONG><CODE>Debug = [dbg_opt()]</CODE></STRONG><BR>
</UL>
</UL>
<UL>
<P>Prints the logged system events in the debug structure
        using <CODE>FormFunc</CODE> as defined when the event was
        generated by a call to <CODE>handle_debug/4</CODE>.
</UL>
<P><A NAME="Mod:system_continue%3"><STRONG><CODE>Mod:system_continue(Parent, Debug, Misc)</CODE></STRONG></A><BR>
<P><UL>Types:
<UL>
<STRONG><CODE>Parent = pid()</CODE></STRONG><BR>
<STRONG><CODE>Debug = [dbg_opt()]</CODE></STRONG><BR>
<STRONG><CODE>Misc = term()</CODE></STRONG><BR>
</UL>
</UL>
<UL>
<P>This function is called from <CODE>sys:handle_system_msg/6</CODE> when the process
        should continue its execution (for example after it has been
        suspended). This function never returns.
</UL>
<P><A NAME="Mod:system_terminate%4"><STRONG><CODE>Mod:system_terminate(Reason, Parent, Debug, Misc)</CODE></STRONG></A><BR>
<P><UL>Types:
<UL>
<STRONG><CODE>Reason = term()</CODE></STRONG><BR>
<STRONG><CODE>Parent = pid()</CODE></STRONG><BR>
<STRONG><CODE>Debug = [dbg_opt()]</CODE></STRONG><BR>
<STRONG><CODE>Misc = term()</CODE></STRONG><BR>
</UL>
</UL>
<UL>
<P>This function is called from <CODE>sys:handle_system_msg/6</CODE> 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.
</UL>
<P><A NAME="Mod:system_code_change%4"><STRONG><CODE>Mod:system_code_change(Misc, Module, OldVsn, Extra) -&#62; {ok, NMisc}</CODE></STRONG></A><BR>
<P><UL>Types:
<UL>
<STRONG><CODE>Misc = term()</CODE></STRONG><BR>
<STRONG><CODE>OldVsn = undefined | term()</CODE></STRONG><BR>
<STRONG><CODE>Module = atom()</CODE></STRONG><BR>
<STRONG><CODE>Extra = term()</CODE></STRONG><BR>
<STRONG><CODE>NMisc = term()</CODE></STRONG><BR>
</UL>
</UL>
<UL>
<P>Called from <CODE>sys:handle_system_msg/6</CODE> when the process
        should perform a code change. The code change is used when the
        internal data structure has changed. This function
        converts the <CODE>Misc</CODE> argument to the new data
        structure. <CODE>OldVsn</CODE> is the <STRONG>vsn</STRONG> attribute of the
        old version of the <CODE>Module</CODE>. If no such attribute was
        defined, the atom <CODE>undefined</CODE> is sent.
</UL>
<H3>AUTHORS</H3>
<UL>
Martin Bj&#246;rklund - support@erlang.ericsson.se<BR>
Magnus Fr&#246;berg - support@erlang.ericsson.se<BR>
</UL>
<CENTER>
<HR>
<FONT SIZE=-1>stdlib 1.10<BR>
Copyright &copy; 1991-2001
<A HREF="http://www.erlang.se">Ericsson Utvecklings AB</A><BR>
<!--#include virtual="/ssi/otp_footer.html"-->
</FONT>
</CENTER>
</BODY>
</HTML>