[commit: ghc] ghc-7.4: Update the user guide with details on new flag +RTS -lu (49b9a36)

[Paolo Capriotti]

Repository : ssh://darcs.haskell.org//srv/darcs/ghc

On branch  : ghc-7.4

http://hackage.haskell.org/trac/ghc/changeset/49b9a36c1c8e390d5b4f79606e4cb8a813179b9d

>---------------------------------------------------------------

commit 49b9a36c1c8e390d5b4f79606e4cb8a813179b9d
Author: Duncan Coutts <duncan at well-typed.com>
Date:   Thu Mar 22 23:24:57 2012 +0000

    Update the user guide with details on new flag +RTS -lu
    
    It's for user events emitted from Haskell code, like traceEvent.
    Fixes #5790
    
    MERGED from commit 050f714150282695746534174c4550c90c2d9f4e

>---------------------------------------------------------------

 docs/users_guide/runtime_control.xml |   43 +++++++++++++++++++--------------
 1 files changed, 25 insertions(+), 18 deletions(-)

diff --git a/docs/users_guide/runtime_control.xml b/docs/users_guide/runtime_control.xml
index 5870092..bc50f28 100644
--- a/docs/users_guide/runtime_control.xml
+++ b/docs/users_guide/runtime_control.xml
@@ -1119,38 +1119,35 @@ $ ./prog -f +RTS -H32m -S -RTS -h foo bar
             For some special use cases you may want more control over which
             events are included. The <replaceable>flags</replaceable> is a
             sequence of zero or more characters indicating which classes of
-            events to log. Currently there are four classes of events that can
+            events to log. Currently these the classes of events that can
             be enabled/disabled:
             <simplelist>
               <member>
                 <option>s</option> &#8212; scheduler events, including Haskell
-                thread creation and start/stop events
+                thread creation and start/stop events. Enabled by default.
               </member>
               <member>
-                <option>g</option> &#8212; GC events, including GC start/stop
+                <option>g</option> &#8212; GC events, including GC start/stop.
+                Enabled by default.
               </member>
               <member>
-                <option>p</option> &#8212; parallel sparks (sampled)
+                <option>p</option> &#8212; parallel sparks (sampled).
+                Enabled by default.
               </member>
               <member>
-                <option>f</option> &#8212; parallel sparks (fully accurate)
+                <option>f</option> &#8212; parallel sparks (fully accurate).
+                Disabled by default.
+              </member>
+              <member>
+                <option>u</option> &#8212; user events. These are events emitted
+                from Haskell code using functions such as 
+                <literal>Debug.Trace.traceEvent</literal>. Enabled by default.
               </member>
             </simplelist>
           </para>
 
           <para>            
-            For spark events there are two modes: sampled and fully accurate.
-            There are various events in the life cycle of each spark, usually
-            just creating and running, but there are some more exceptional
-            possibilities. In the sampled mode the number of occurrences of each
-            kind of spark event is sampled at frequent intervals. In the fully
-            accurate mode every spark event is logged individually. The latter
-            has a higher runtime overhead and is not enabled by default.
-          </para>
-
-          <para>            
-            The initial enabled event classes are 's', 'g' and 'p'. In addition
-            you can disable specific classes, or enable/disable all classes at
+            You can disable specific classes, or enable/disable all classes at
             once:
             <simplelist>
               <member>
@@ -1167,13 +1164,23 @@ $ ./prog -f +RTS -H32m -S -RTS -h foo bar
           </para>
 
           <para>
+            For spark events there are two modes: sampled and fully accurate.
+            There are various events in the life cycle of each spark, usually
+            just creating and running, but there are some more exceptional
+            possibilities. In the sampled mode the number of occurrences of each
+            kind of spark event is sampled at frequent intervals. In the fully
+            accurate mode every spark event is logged individually. The latter
+            has a higher runtime overhead and is not enabled by default.
+          </para>
+
+          <para>
             The format of the log file is described by the header
             <filename>EventLogFormat.h</filename> that comes with
             GHC, and it can be parsed in Haskell using
             the <ulink url="http://hackage.haskell.org/package/ghc-events">ghc-events</ulink>
             library.  To dump the contents of
             a <literal>.eventlog</literal> file as text, use the
-            tool <literal>ghc-events-show</literal> that comes with
+            tool <literal>ghc-events show</literal> that comes with
             the <ulink url="http://hackage.haskell.org/package/ghc-events">ghc-events</ulink>
             package.
           </para>