The R13B03 release.OTP_R13B03

1 files changed, 429 insertions, 0 deletions

diff --git a/lib/stdlib/doc/src/sys.xml b/lib/stdlib/doc/src/sys.xml
new file mode 100644
index 0000000000..a395a8a415
--- /dev/null
+++ b/lib/stdlib/doc/src/sys.xml
@@ -0,0 +1,429 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE erlref SYSTEM "erlref.dtd">
+
+<erlref>
+  <header>
+    <copyright>
+      <year>1996</year>
+      <year>2007</year>
+      <holder>Ericsson AB, All Rights Reserved</holder>
+    </copyright>
+    <legalnotice>
+  The contents of this file are subject to the Erlang Public License,
+  Version 1.1, (the "License"); you may not use this file except in
+  compliance with the License. You should have received a copy of the
+  Erlang Public License along with this software. If not, it can be
+  retrieved online at http://www.erlang.org/.
+
+  Software distributed under the License is distributed on an "AS IS"
+  basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
+  the License for the specific language governing rights and limitations
+  under the License.
+
+  The Initial Developer of the Original Code is Ericsson AB.
+    </legalnotice>
+
+    <title>sys</title>
+    <prepared>Martin Bj&ouml;rklund</prepared>
+    <responsible>Bjarne D&auml;cker</responsible>
+    <docno></docno>
+    <approved>Bjarne D&auml;cker</approved>
+    <checked></checked>
+    <date>1996-06-06</date>
+    <rev></rev>
+    <file>sys.sgml</file>
+  </header>
+  <module>sys</module>
+  <modulesummary>A Functional Interface to System Messages</modulesummary>
+  <description>
+    <p>This module contains functions for sending system messages used by programs, and messaged used for debugging purposes.
+      </p>
+    <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 <c>gen_server</c>.</p>
+    <p>The following types are used in the functions defined below:</p>
+    <list type="bulleted">
+      <item>
+        <p><c>Name = pid() | atom() | {global, atom()}</c></p>
+      </item>
+      <item>
+        <p><c>Timeout = int() >= 0 | infinity</c></p>
+      </item>
+      <item>
+        <p><c>system_event() = {in, Msg} | {in, Msg, From} | {out, Msg, To} | term()</c></p>
+      </item>
+    </list>
+    <p>The default timeout is 5000 ms, unless otherwise specified. The
+      <c>timeout</c> defines the time period to wait for the process to
+      respond to a request. If the process does not respond, the
+      function evaluates <c>exit({timeout, {M, F, A}})</c>.
+      </p>
+    <p>The functions make reference to a debug structure.
+      The debug structure is a list of <c>dbg_opt()</c>.
+      <c>dbg_opt()</c> is an internal data type used by the
+      <c>handle_system_msg/6</c> function. No debugging is performed if it is an empty list.
+      </p>
+  </description>
+
+  <section>
+    <title>System Messages</title>
+    <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>
+    <list type="bulleted">
+      <item>
+        <p>Plain system messages. These are received as
+          <c>{system, From, Msg}</c>. The content and meaning of
+          this message are not interpreted by the
+          receiving process module. When a system message has been
+          received, the function <c>sys:handle_system_msg/6</c>
+          is called in order to handle the request.
+          </p>
+      </item>
+      <item>
+        <p>Shutdown messages. If the process traps exits, it must
+          be able to handle an shut-down request from its parent, the
+          supervisor. The message <c>{'EXIT', Parent, Reason}</c>
+          from the parent is an order to terminate.  The process must terminate when this message is received, normally with the
+          same <c>Reason</c> as <c>Parent</c>.
+          </p>
+      </item>
+      <item>
+        <p>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 <c>gen_event</c> processes. This message is <c>{get_modules, From}</c>. The reply to this message is <c>From ! {modules, Modules}</c>,
+          where <c>Modules</c> is a list of the currently active modules in the process.
+          </p>
+        <p>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.
+          </p>
+      </item>
+    </list>
+  </section>
+
+  <section>
+    <title>System Events</title>
+    <p>When debugging a process with the functions of this
+      module, the process generates <em>system_events</em> which are
+      then treated in the debug function. For example, <c>trace</c>
+      formats the system events to the tty.
+      </p>
+    <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.</p>
+  </section>
+  <funcs>
+    <func>
+      <name>log(Name,Flag)</name>
+      <name>log(Name,Flag,Timeout) -> ok | {ok, [system_event()]}</name>
+      <fsummary>Log system events in memory</fsummary>
+      <type>
+        <v>Flag = true | {true, N} | false | get | print</v>
+        <v>N = integer() > 0</v>
+      </type>
+      <desc>
+        <p>Turns the logging of system events On or Off. If On, a
+          maximum of <c>N</c>  events are kept in the
+          debug structure (the default is 10). If <c>Flag</c> is <c>get</c>, a list of all
+          logged events is returned. If <c>Flag</c> is <c>print</c>, the
+          logged events are printed to <c>standard_io</c>. The events are
+          formatted with a function that is defined by the process that
+          generated the event (with a call to
+          <c>sys:handle_debug/4</c>).</p>
+      </desc>
+    </func>
+    <func>
+      <name>log_to_file(Name,Flag)</name>
+      <name>log_to_file(Name,Flag,Timeout) -> ok | {error, open_file}</name>
+      <fsummary>Log system events to the specified file</fsummary>
+      <type>
+        <v>Flag = FileName | false</v>
+        <v>FileName = string()</v>
+      </type>
+      <desc>
+        <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 <c>sys:handle_debug/4</c>).</p>
+      </desc>
+    </func>
+    <func>
+      <name>statistics(Name,Flag)</name>
+      <name>statistics(Name,Flag,Timeout) -> ok | {ok, Statistics} </name>
+      <fsummary>Enable or disable the collections of statistics</fsummary>
+      <type>
+        <v>Flag = true | false | get</v>
+        <v>Statistics = [{start_time, {Date1, Time1}}, {current_time, {Date, Time2}}, {reductions, integer()}, {messages_in, integer()}, {messages_out, integer()}]</v>
+        <v>Date1 = Date2 = {Year, Month, Day}</v>
+        <v>Time1 = Time2 = {Hour, Min, Sec}</v>
+      </type>
+      <desc>
+        <p>Enables or disables the collection of statistics. If <c>Flag</c> is
+          <c>get</c>, the statistical collection is returned.</p>
+      </desc>
+    </func>
+    <func>
+      <name>trace(Name,Flag)</name>
+      <name>trace(Name,Flag,Timeout) -> void()</name>
+      <fsummary>Print all system events on <c>standard_io</c></fsummary>
+      <type>
+        <v>Flag = boolean()</v>
+      </type>
+      <desc>
+        <p>Prints all system events on <c>standard_io</c>. The events are
+          formatted with a function that is defined by the process that
+          generated the event (with a call to
+          <c>sys:handle_debug/4</c>).</p>
+      </desc>
+    </func>
+    <func>
+      <name>no_debug(Name)</name>
+      <name>no_debug(Name,Timeout) -> void()</name>
+      <fsummary>Turn off debugging</fsummary>
+      <desc>
+        <p>Turns off all debugging for the process. This includes
+          functions that have been installed explicitly with the
+          <c>install</c> function, for example triggers.</p>
+      </desc>
+    </func>
+    <func>
+      <name>suspend(Name)</name>
+      <name>suspend(Name,Timeout) -> void()</name>
+      <fsummary>Suspend the process</fsummary>
+      <desc>
+        <p>Suspends the process. When the process is suspended, it
+          will only respond to other system messages, but not other
+          messages.</p>
+      </desc>
+    </func>
+    <func>
+      <name>resume(Name)</name>
+      <name>resume(Name,Timeout) -> void()</name>
+      <fsummary>Resume a suspended process</fsummary>
+      <desc>
+        <p>Resumes a suspended process.</p>
+      </desc>
+    </func>
+    <func>
+      <name>change_code(Name, Module, OldVsn, Extra)</name>
+      <name>change_code(Name, Module, OldVsn, Extra, Timeout) -> ok | {error, Reason}</name>
+      <fsummary>Send the code change system message to the process</fsummary>
+      <type>
+        <v>OldVsn = undefined | term()</v>
+        <v>Module = atom()</v>
+        <v>Extra = term()</v>
+      </type>
+      <desc>
+        <p>Tells the process to change code. The process must be
+          suspended to handle this message. The <c>Extra</c> argument is
+          reserved for each process to use as its own. The function
+          <c>Mod:system_code_change/4</c> is called. <c>OldVsn</c> is
+          the old version of the <c>Module</c>.</p>
+      </desc>
+    </func>
+    <func>
+      <name>get_status(Name)</name>
+      <name>get_status(Name,Timeout) -> {status, Pid, {module, Mod}, [PDict, SysState, Parent, Dbg, Misc]}</name>
+      <fsummary>Get the status of the process</fsummary>
+      <type>
+        <v>PDict = [{Key, Value}]</v>
+        <v>SysState = running | suspended</v>
+        <v>Parent = pid()</v>
+        <v>Dbg = [dbg_opt()]</v>
+        <v>Misc = term()</v>
+      </type>
+      <desc>
+        <p>Gets the status of the process.</p>
+      </desc>
+    </func>
+    <func>
+      <name>install(Name,{Func,FuncState})</name>
+      <name>install(Name,{Func,FuncState},Timeout)</name>
+      <fsummary>Install a debug function in the process</fsummary>
+      <type>
+        <v>Func = dbg_fun()</v>
+        <v>dbg_fun() = fun(FuncState, Event, ProcState) -> done | NewFuncState</v>
+        <v>FuncState = term()</v>
+        <v>Event = system_event()</v>
+        <v>ProcState = term()</v>
+        <v>NewFuncState = term()</v>
+      </type>
+      <desc>
+        <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>
+        <p><c>Func</c> is called whenever a system event is
+          generated. This function should return <c>done</c>, or a new
+          func state. In the first case, the function is removed. It is removed 
+          if the function fails.</p>
+      </desc>
+    </func>
+    <func>
+      <name>remove(Name,Func)</name>
+      <name>remove(Name,Func,Timeout) -> void()</name>
+      <fsummary>Remove a debug function from the process</fsummary>
+      <type>
+        <v>Func = dbg_fun()</v>
+      </type>
+      <desc>
+        <p>Removes a previously installed debug function from the
+          process. <c>Func</c> must be the same as previously
+          installed.</p>
+      </desc>
+    </func>
+  </funcs>
+
+  <section>
+    <title>Process Implementation Functions</title>
+    <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.</p>
+  </section>
+  <funcs>
+    <func>
+      <name>debug_options(Options) -> [dbg_opt()]</name>
+      <fsummary>Convert a list of options to a debug structure</fsummary>
+      <type>
+        <v>Options = [Opt]</v>
+        <v>Opt = trace | log | statistics | {log_to_file, FileName} | {install, {Func, FuncState}}</v>
+        <v>Func = dbg_fun()</v>
+        <v>FuncState = term()</v>
+      </type>
+      <desc>
+        <p>This function can be used by a process that initiates a debug
+          structure from a list of options. The values of the
+          <c>Opt</c> argument are the same as the corresponding
+          functions.</p>
+      </desc>
+    </func>
+    <func>
+      <name>get_debug(Item,Debug,Default) -> term()</name>
+      <fsummary>Get the data associated with a debug option</fsummary>
+      <type>
+        <v>Item = log | statistics</v>
+        <v>Debug = [dbg_opt()]</v>
+        <v>Default = term()</v>
+      </type>
+      <desc>
+        <p>This function gets the data associated with a debug option. <c>Default</c> is returned if the
+          <c>Item</c> is not found.  Can be
+          used by the process to retrieve debug data for printing
+          before it terminates.</p>
+      </desc>
+    </func>
+    <func>
+      <name>handle_debug([dbg_opt()],FormFunc,Extra,Event) -> [dbg_opt()]</name>
+      <fsummary>Generate a system event</fsummary>
+      <type>
+        <v>FormFunc = dbg_fun()</v>
+        <v>Extra = term()</v>
+        <v>Event = system_event()</v>
+      </type>
+      <desc>
+        <p>This function is called by a process when it generates a system event. <c>FormFunc</c> is a formatting function which is called as <c>FormFunc(Device, Event, Extra)</c> in order to print the events, which is necessary if tracing is activated. <c>Extra</c> is any
+          extra information which the process needs in the format function, for example the name of the process.</p>
+      </desc>
+    </func>
+    <func>
+      <name>handle_system_msg(Msg,From,Parent,Module,Debug,Misc)</name>
+      <fsummary>Take care of system messages</fsummary>
+      <type>
+        <v>Msg = term()</v>
+        <v>From = pid()</v>
+        <v>Parent = pid()</v>
+        <v>Module = atom()</v>
+        <v>Debug = [dbg_opt()]</v>
+        <v>Misc = term()</v>
+      </type>
+      <desc>
+        <p>This function is used by a process module that wishes to take care of system
+          messages. The process receives a <c>{system, From, Msg}</c>
+          message and passes the <c>Msg</c> and <c>From</c> to this
+          function.
+          </p>
+        <p>This function <em>never</em> returns. It calls the function
+          <c>Module:system_continue(Parent, NDebug, Misc)</c> where the
+          process continues the execution, or
+          <c>Module:system_terminate(Reason, Parent, Debug, Misc)</c> if
+          the process should terminate. The <c>Module</c> must export
+          <c>system_continue/3</c>, <c>system_terminate/4</c>, and
+          <c>system_code_change/4</c> (see below).
+          </p>
+        <p>The <c>Misc</c> argument can be used to save internal data
+          in a process, for example its state. It is sent to
+          <c>Module:system_continue/3</c> or
+          <c>Module:system_terminate/4</c></p>
+      </desc>
+    </func>
+    <func>
+      <name>print_log(Debug) -> void()</name>
+      <fsummary>Print the logged events in the debug structure</fsummary>
+      <type>
+        <v>Debug = [dbg_opt()]</v>
+      </type>
+      <desc>
+        <p>Prints the logged system events in the debug structure
+          using <c>FormFunc</c> as defined when the event was
+          generated by a call to <c>handle_debug/4</c>.</p>
+      </desc>
+    </func>
+    <func>
+      <name>Mod:system_continue(Parent, Debug, Misc)</name>
+      <fsummary>Called when the process should continue its execution</fsummary>
+      <type>
+        <v>Parent = pid()</v>
+        <v>Debug = [dbg_opt()]</v>
+        <v>Misc = term()</v>
+      </type>
+      <desc>
+        <p>This function is called from <c>sys:handle_system_msg/6</c> when the process
+          should continue its execution (for example after it has been
+          suspended). This function never returns.</p>
+      </desc>
+    </func>
+    <func>
+      <name>Mod:system_terminate(Reason, Parent, Debug, Misc)</name>
+      <fsummary>Called when the process should terminate</fsummary>
+      <type>
+        <v>Reason = term()</v>
+        <v>Parent = pid()</v>
+        <v>Debug = [dbg_opt()]</v>
+        <v>Misc = term()</v>
+      </type>
+      <desc>
+        <p>This function is called from <c>sys:handle_system_msg/6</c> 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.</p>
+      </desc>
+    </func>
+    <func>
+      <name>Mod:system_code_change(Misc, Module, OldVsn, Extra) -> {ok, NMisc}</name>
+      <fsummary>Called when the process should perform a code change</fsummary>
+      <type>
+        <v>Misc = term()</v>
+        <v>OldVsn = undefined | term()</v>
+        <v>Module = atom()</v>
+        <v>Extra = term()</v>
+        <v>NMisc = term()</v>
+      </type>
+      <desc>
+        <p>Called from <c>sys:handle_system_msg/6</c> when the process
+          should perform a code change. The code change is used when the
+          internal data structure has changed. This function
+          converts the <c>Misc</c> argument to the new data
+          structure. <c>OldVsn</c> is the <em>vsn</em> attribute of the
+          old version of the <c>Module</c>. If no such attribute was
+          defined, the atom <c>undefined</c> is sent.</p>
+      </desc>
+    </func>
+  </funcs>
+</erlref>
+