Update the user guide with details on new flag +RTS -lu
authorDuncan Coutts <duncan@well-typed.com>
Thu, 22 Mar 2012 23:24:57 +0000 (23:24 +0000)
committerDuncan Coutts <duncan@well-typed.com>
Thu, 22 Mar 2012 23:24:57 +0000 (23:24 +0000)
It's for user events emitted from Haskell code, like traceEvent.
Fixes #5790

docs/users_guide/runtime_control.xml

index 5870092..bc50f28 100644 (file)
@@ -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>
@@ -1166,6 +1163,16 @@ $ ./prog -f +RTS -H32m -S -RTS -h foo bar
             (<option>-a</option>) except for GC events (<option>g</option>).
           </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
@@ -1173,7 +1180,7 @@ $ ./prog -f +RTS -H32m -S -RTS -h foo bar
             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>