The R13B03 release.OTP_R13B03

1 files changed, 371 insertions, 0 deletions

diff --git a/lib/pman/doc/src/pman_chapter.xml b/lib/pman/doc/src/pman_chapter.xml
new file mode 100644
index 0000000000..141b488415
--- /dev/null
+++ b/lib/pman/doc/src/pman_chapter.xml
@@ -0,0 +1,371 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE chapter SYSTEM "chapter.dtd">
+
+<chapter>
+  <header>
+    <copyright>
+      <year>1996</year><year>2009</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.
+    
+    </legalnotice>
+
+    <title>Pman</title>
+    <prepared></prepared>
+    <docno></docno>
+    <date></date>
+    <rev></rev>
+    <file>pman_chapter.xml</file>
+  </header>
+  <marker id="here"></marker>
+
+  <section>
+    <title>Introduction</title>
+    <p>The process manager Pman is a tool for viewing processes executing
+      locally or on remote nodes. Its main purpose is to locate
+      erroneous code by inspecting the state of the processes and by tracing
+      events. Bottlenecks, unread messages, and bad memory handling are 
+      some of the problems that can be solved with Pman.</p>
+    <p>Processes may be inspected individually in a process trace
+      window. There the user may dynamically follow the execution of a
+      process by getting trace output for sent and received messages
+      as well as for called functions and some other process
+      events. Information about source code modules executed by the
+      processes is also accessible. Note that Pman has some effect on
+      the real time behavior of a running system.</p>
+  </section>
+
+  <section>
+    <title>Getting Started with Pman</title>
+    <p>Start Pman by calling <c>pman:start()</c>. It will start
+      the <seealso marker="#main_win">Main Window</seealso>, showing an
+      overview of all processes running at the current node.</p>
+    <p>To trace a certain process, select it by clicking on its line and
+      then chose Trace-&gt;Selected Process, or simply double-click it. This
+      will open a <seealso marker="#trace_win">Trace Window</seealso>.
+      In the Trace Window, there is some information about the process
+      and traced events are added dynamically.</p>
+    <p>Which events to trace are selected in
+      the <seealso marker="#options_win">Options Window</seealso> which
+      is opened by choosing File-&gt;Options... in the Main Window or in a
+      Trace Window. Currently supported trace events are message sending,
+      message receiving, function calls and process events.</p>
+    <p>It is possible to by-pass the Main Window and open a Trace
+      Window directly for the process <c>Pid</c> by calling
+      <c>pman:proc(Pid)</c>.</p>
+  </section>
+
+  <section>
+    <marker id="main_win"></marker>
+    <title>The Main Window</title>
+    <p>The Main Window shows all processes running at the displayed node.
+      The window is automatically updated every 5 seconds.
+      Select which node to display in the window by choosing the node name
+      from the Nodes menu.</p>
+    <image file="main_window.gif">
+      <icaption>The Main Window.</icaption>
+    </image>
+    <p>A process can be selected by clicking on its line. The selected
+      process is highlighted. Use the arrow keys to move up and down in
+      the process overview.</p>
+    <p>The following information is displayed for each process:</p>
+    <list type="bulleted">
+      <item>Pid - process identifier.</item>
+      <item>Current Function - the function (<c>Module:Function/Arity</c>)
+       the process is currently executing.</item>
+      <item>Name - registered name of the process, if any.</item>
+      <item>Msgs - number of messages in the process' mailbox.</item>
+      <item>Reds - number of reductions performed. Gives a rough estimate
+       of the process' work load.</item>
+      <item>Size - estimated size of the process, in words, calculated by
+       adding the stack size and the heap size.</item>
+    </list>
+    <p>At the bottom of the window the following functions and
+      information can be found:</p>
+    <taglist>
+      <tag><em>Hide System Processes</em></tag>
+      <item>This check button controls the display of what Pman consider
+      <em>system processes</em>, that is, processes Pman knows are part
+       of Erlang/OTP rather than the user's application.
+       If the button is selected, these system processes will not be
+       shown.</item>
+      <tag><em>Auto-Hide New</em></tag>
+      <item>This check button controls the treatment of newly created
+       processes. If it is selected, new processes will not be shown.</item>
+      <tag><em># Hidden</em></tag>
+      <item>This label displays the number of processes currently
+       executing that are not shown in the process overview.</item>
+    </taglist>
+
+    <section>
+      <title>The File Menu</title>
+      <taglist>
+        <tag><em>Options...</em></tag>
+        <item>Open the <seealso marker="#options_win">Options Window</seealso>
+         which allows the user to set the trace options to use.</item>
+        <tag><em>Save Options</em></tag>
+        <item>Save the options set using the Options Window. The options are
+         stored to the file <c>HOME/.erlang_tools/pman.opts</c>, where
+        <c>HOME</c> is the user's home directory, and are automatically
+         loaded the next time Pman is started.</item>
+        <tag><em>Exit</em></tag>
+        <item>Stop Pman.</item>
+      </taglist>
+    </section>
+
+    <section>
+      <title>The View Menu</title>
+      <p>This menu mainly contains buttons for controlling what to
+        display in the Main Window. Note that the View Menu overrides
+        the settings of the check buttons (Hide System processes, Auto-Hide
+        new) in the Main Window.</p>
+      <taglist>
+        <tag><em>Hide All Processes</em></tag>
+        <item>Hide all processes.</item>
+        <tag><em>Hide Modules...</em></tag>
+        <item>Opens a dialog window with all loaded modules. If the user
+         selects a window and clicks OK, the process overview will not
+         show any processes running code from those modules.</item>
+        <tag><em>Hide Selected Processs</em></tag>
+        <item>Hide the selected process.</item>
+        <tag><em>Module Info...</em></tag>
+        <item>Given a selected process currently executing a function in
+         the module <c>Module</c>, this menu button opens a window
+         showing information about the module as returned from
+        <c>Module:module_info()</c>.</item>
+        <tag><em>Refresh</em></tag>
+        <item>Updates the process overview.</item>
+        <tag><em>Show All Processes</em></tag>
+        <item>Show all processes, except system processes and/or new
+         processes if <em>Hide System Processes</em> and/or
+        <em>Auto-Hide New</em> is selected.</item>
+        <tag><em>Show Processes...</em></tag>
+        <item>Opens a dialog window with all hidden processes. If
+         the user selects a process and clicks OK, the process
+         overview will show that process.</item>
+      </taglist>
+    </section>
+
+    <section>
+      <title>The Trace Menu</title>
+      <taglist>
+        <tag><em>Kill</em></tag>
+        <item>Terminates the selected process by calling
+        <c>exit(Pid,kill)</c>.</item>
+        <tag><em>Trace Selected Process</em></tag>
+        <item>Opens a Trace Window for the selected process. Tracing
+         will start immediately with the default trace flags set from
+         the Main Window.</item>
+        <tag><em>Shell Process</em></tag>
+        <item>Opens a Trace Window for the shell process of node Pman
+         was started at (not the displayed node). If the shell process
+         dies, the opened Trace Window will find the pid of
+         the automatically started new shell process, and continue to
+         trace that process.</item>
+      </taglist>
+    </section>
+
+    <section>
+      <title>The Nodes Menu</title>
+      <p>The Nodes menu contains one entry for each known node.
+        By selecting a node from the Nodes menu, the process overview
+        window will change its view, and display the processes running
+        on that node.</p>
+    </section>
+
+    <section>
+      <title>The Help Menu</title>
+      <taglist>
+        <tag><em>Help</em></tag>
+        <item>Selecting Help from the Help menu will cause the HTML
+         version of the Pman User's Guide (this document) to be
+         displayed. Currently this function requires Netscape to be up
+         and running.</item>
+      </taglist>
+    </section>
+  </section>
+
+  <section>
+    <marker id="trace_win"></marker>
+    <title>The Trace Window</title>
+    <p>A Trace Window outputs trace information for a traced process.
+      A Trace Window automatically uses the trace options set in
+      the Main Window, but it is also possible to change the options for
+      each Trace Window individually.</p>
+    <image file="trace.gif">
+      <icaption>The Trace Window.</icaption>
+    </image>
+    <p>There is no limit to how many Trace Windows can be open at the same
+      time. However, notice that if more processes are traced,
+      the performance degradation of the system will be more noticeable.</p>
+    <p>The following information is displayed, where applicable:</p>
+    <list type="bulleted">
+      <item>initial call - the function (<c>Module:Function/Arity</c>)
+       the process started executing in.</item>
+      <item>current function - the function (<c>Module:Function/Arity</c>)
+       the process is currently executing.</item>
+      <item>messages - the messages in the mailbox.</item>
+      <item>dictionary - the contents of the process dictionary.</item>
+      <item>heap size - heap size in words.</item>
+      <item>stack size - stack size in words.</item>
+      <item>reductions - number of reductions performed. Gives a rough
+       estimate of the process' work load.</item>
+      <item>links - list of pids the process is linked to.</item>
+      <item>trap_exit - <c>true</c> if the process trap exit signals,
+      <c>false</c> otherwise.</item>
+    </list>
+    <p>In the Trace Window, trace output is continuously added. First in
+      each trace message is the pid of the traced process.
+      Note that if the inheritance flags for tracing are set, the trace
+      output for the spawned/linked processes will be shown in the same
+      window as the spawning/linking process.</p>
+    <p>Each trace message also has a mnemonic tag:</p>
+    <taglist>
+      <tag><em>!</em></tag>
+      <item>This tag indicates that a message has been sent. Following
+       the <c>To:</c> tag will be a pid/name of the receiver. Next,
+       following the <c>Msg:</c> tag will be the sent message.</item>
+      <tag><em>rec</em></tag>
+      <item>This tag indicates that a message has been received.
+       Following this will be the received message.</item>
+      <tag><em>call</em></tag>
+      <item>This tag indicates a call to a function. Following this will be
+       the actual call, with all the arguments.</item>
+      <tag><em>link</em></tag>
+      <item>This tag indicates that a link between the traced process and
+       another process has been created. Following this will be the pid
+       of the other process.</item>
+      <tag><em>spawn</em></tag>
+      <item>This tag indicates that the traced process has spawned another
+       process. Following this will be the pid of the spawned process.</item>
+      <tag><em>exit</em></tag>
+      <item>This tag indicates that traced process has exited. Following
+       this will be the exit reason.</item>
+    </taglist>
+
+    <section>
+      <title>The File Menu</title>
+      <taglist>
+        <tag><em>Options...</em></tag>
+        <item>Opens the <seealso marker="#options_win">Options Window</seealso>
+         which allows the user to set the trace options to use for this
+         specific Trace Window.</item>
+        <tag><em>Save Buffer...</em></tag>
+        <item>Opens a dialog that prompts the user for a file name to
+         save the current Trace Window contents in.</item>
+        <tag><em>Close</em></tag>
+        <item>Stops tracing of the process, and closes the Trace Window.</item>
+      </taglist>
+    </section>
+
+    <section>
+      <title>The View Menu</title>
+      <taglist>
+        <tag><em>Clear Buffer</em></tag>
+        <item>Clears the contents of the Trace Window.</item>
+        <tag><em>Module Info</em></tag>
+        <item>Opens a window showing information about the module
+         the process is currently executing code from, as returned from
+        <c>Module:module_info()</c>.</item>
+      </taglist>
+    </section>
+
+    <section>
+      <title>The Trace Menu</title>
+      <taglist>
+        <tag><em>All Linked Processes</em></tag>
+        <item>Opens a Trace Window for each of the processes linked to the
+         process being traced in the current Trace Window.</item>
+        <tag><em>Linked Process -></em></tag>
+        <item>The Linked Process submenu has one entry for each process
+         linked to the process being traced in the current Trace Window.
+         Select one of the processes to open a new Trace Window for that
+         process.</item>
+        <tag><em>Kill</em></tag>
+        <item>Terminates the process being traced in the current Trace
+         Window by calling <c>exit(Pid,kill)</c>.</item>
+      </taglist>
+    </section>
+
+    <section>
+      <title>The Help Menu</title>
+      <taglist>
+        <tag><em>Help</em></tag>
+        <item>Selecting Help from the Help menu will cause the HTML version
+         of the Pman User's Guide (this document) to be displayed.
+         Currently this function requires Netscape to be up and running.</item>
+      </taglist>
+    </section>
+  </section>
+
+  <section>
+    <marker id="options_win"></marker>
+    <title>The Options Window</title>
+    <p>The Options Window allows the user to specify the amount of output,
+      and the destination of output for traced processes.</p>
+    <image file="options.gif">
+      <icaption>The Options Window.</icaption>
+    </image>
+    <p>In the upper left corner of the Options Window, there are check
+      buttons for determining what to output in the Trace Window:</p>
+    <taglist>
+      <tag><em>Trace send</em></tag>
+      <item>Select this check button to display information about sent
+       messages.</item>
+      <tag><em>Trace receive</em></tag>
+      <item>Select this check button to display information about received
+       messages.</item>
+      <tag><em>Trace functions</em></tag>
+      <item>Select this check button to display information about
+       function calls.</item>
+      <tag><em>Trace events</em></tag>
+      <item>Select this check button to display information about process
+       events, such as spawn, link and exit.</item>
+    </taglist>
+    <p>In the upper right corner of the dialog, there are options for
+      controlling the behaviour of spawned or linked processes:</p>
+    <taglist>
+      <tag><em>Inherit on spawn</em></tag>
+      <item>
+        <p>The user may select if spawned processes shall also be traced.
+          And if so, if all spawned processes should be traced, or just
+          the first spawned process.</p>
+        <p>If a spawned process is traced, it will get the same trace
+          options that are set for the spawning process. And the output
+          will be shown in the same Trace Window as that of the spawning
+          process.</p>
+        <p>.</p>
+      </item>
+      <tag><em>Inherit on link</em></tag>
+      <item>
+        <p>The user may select if a process that is being linked to
+          shall be traced. And if so, if all linked processes shall be
+          traced, or just the first one linked to.</p>
+        <p>If a linked process is traced, it will get the same trace
+          options that are set for the linking process. And the output
+          will be shown in the same Trace Window as that of the linked
+          process.</p>
+      </item>
+    </taglist>
+    <p>In the lower part of the Options Dialog, the user may select
+      whether the trace information shall be output to a file, or appear in
+      the trace window.</p>
+    <p>Sending trace information to a file is more efficient than displaying
+      it in the Trace Window. Furthermore, if the amount of trace data is
+      large, it will not be lost if tracing to a file. The trace information
+      in the Trace Window has an upper limit (approx. 10,000 lines), after
+      which the output buffer will be cleared.</p>
+  </section>
+</chapter>
+