[svn:parrot] r42984 - trunk/docs/dev

[cotto at svn.parrot.org]

Author: cotto
Date: Fri Dec 11 09:58:22 2009
New Revision: 42984
URL: https://trac.parrot.org/parrot/changeset/42984

Log:
[docs] flesh out the profiling docs a bit

Modified:
   trunk/docs/dev/profiling.pod

Modified: trunk/docs/dev/profiling.pod
==============================================================================
--- trunk/docs/dev/profiling.pod	Fri Dec 11 09:38:15 2009	(r42983)
+++ trunk/docs/dev/profiling.pod	Fri Dec 11 09:58:22 2009	(r42984)
@@ -11,6 +11,50 @@
 
 =head2 Summary
 
-It does some stuff.
+The profiling runcore is built as part of Parrot and is designed to allow
+discovery of bottlenecks in PIR code.  It is also being instrumented to support
+HLL profiling, but this support is currently limited.  Code can be run under
+the profiling runcore by passing C<-Rprofiling> or C<--runcore profiling> to
+the C<parrot> binary.  The location and format of the output file are
+determined by environment variables as documented below.  If the profiling
+runcore does not detect any relevant environment variables, it will use the
+defaults described below.
+
+=head2 Environment Variables
+
+=over 4
+
+=item C<PARROT_PROFILING_FILENAME>
+
+This determines the full name of the file where the output will be written, if
+any.  Parrot does not check if the filename exists before opening it for
+writing and will happily overwrite any existing files, including previous profiles.
+
+If no value is specified, Parrot will write to a file named C<parrot.pprof.X>,
+where X is the PID of the Parrot process.  When the profiling runcore exits, it
+will print a message announcing where the profile was written.
+
+This variable can also have the special values C<stdout> and C<stderr>.  When
+either of these values are detected (case-insensitively), Parrot will print its
+profiling output the stdout or stderr.
+
+=item C<PARROT_PROFILING_OUTPUT>
+
+This determines the type of output which will contain the profile.  Current
+options are C<pprof> and C<none>.  C<pprof> is the default and is a ascii-based
+human-readable format.  It can be post-processed into a Callgrind-compatible
+format by tools/dev/pprof2cg.pl.  C<none> writes nothing to the output file.
+It is most useful for testing and optimizing the profiling runcore itself.  It
+is expected to be of little interest to users wishing to profile PIR and HLL
+code.
+
+=item C<PARROT_PROFILING_ANNOTATIONS>
+
+This determines whether PIR annotations will be recorded as part of the
+profile.  Annotations are necessary when profiling HLL code, but will cause the
+profiling runcore to run more slowly.  By default, they are disabled.  Set this
+value to enable them.
+
+=back
 
 =cut