[svn:parrot] r42984 - trunk/docs/dev
cotto at svn.parrot.org
cotto at svn.parrot.org
Fri Dec 11 09:58:22 UTC 2009
Date: Fri Dec 11 09:58:22 2009
New Revision: 42984
[docs] flesh out the profiling docs a bit
--- 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 @@
-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
+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.
+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
+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.
More information about the parrot-commits