[Openmcl-cvs-notifications] r14634 - in /trunk/source: doc/src/profile.xml doc/src/using.xml library/chud-metering.txt
gb at clozure.com
gb at clozure.com
Thu Feb 3 01:43:20 CST 2011
Author: gb
Date: Thu Feb 3 01:43:20 2011
New Revision: 14634
Log:
Document new CHUD stuff, :NATIVE arg to SAVE-APPLICATION.
Modified:
trunk/source/doc/src/profile.xml
trunk/source/doc/src/using.xml
trunk/source/library/chud-metering.txt
Modified: trunk/source/doc/src/profile.xml
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D
--- trunk/source/doc/src/profile.xml (original)
+++ trunk/source/doc/src/profile.xml Thu Feb 3 01:43:20 2011
@@ -1,5 +1,6 @@
<?xml version=3D"1.0" encoding=3D"utf-8"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.=
oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY rest "<varname>&rest</varname>">
<!ENTITY key "<varname>&key</varname>">
<!ENTITY optional "<varname>&optional</varname>">
@@ -8,98 +9,126 @@
<!ENTITY allow-other-keys "<varname>&allow-other-keys</varname>">
<!ENTITY CCL "Clozure CL">
]>
-
- <chapter id=3D"Profiling">
- <title>Profiling</title>
-
- <sect1 id=3D"Profiling-Using-the-Linux-oprofile-system-level-profiler">
- <title>Using the Linux oprofile system-level profiler</title>
-
- <para><ulink url=3D"http://oprofile.sourceforge.net"><code>oprofile<=
/code></ulink> is
- a system-level profiler that's available for most modern Linux distr=
ibutions.</para>
-
- <para>Use of oprofile and its companion programs isn't really docume=
nted here; what
- is described is a way of generating symbolic information that enable=
s profiling
- summaries generated by the <code>opreport</code> program to identify=
lisp functions
- meaningfully.</para>
-
- <sect2 id=3D"Profiling-oprofile-generating-a-lisp-image-for-use-with=
-oprofile">
- <title>Generating a lisp image for use with oprofile</title>
-
- <para>Modern Linux uses the 'ELF" (Executable and Linking Format) object =
file
- format; the oprofile tools can associate symbolic names with addresses in=
a
- memory-mapped file if that file appears to be an ELF object file and if it
- contains ELF symbol information that describes those memory regions. So,=
the
- general idea is to make a lisp heap image that looks enough like an ELF s=
hared
- library to fool the <code>oprofile</code> tools (we don't actually load h=
eap
- images via ELF dynamic linking technology, but we can make it look like we
- did.)</para>
-
- </sect2>
- <sect2 id=3D"Profiling-oprofile-prerequisites">
- <title>Prerequisites</title>
-
- <itemizedlist>
- <listitem>
- <para><code>oprofile</code> itself, which is almost certainly availab=
le via
- your distribution's package management system if not already
- preinstalled.</para>
- </listitem>
- <listitem>
- <para><code>libelf</code>, which provides utilities for reading and w=
riting
- ELF files (and is likewise likely preinstalled or readily installable=
.)</para>
- </listitem>
- </itemizedlist>
- </sect2>
- <sect2 id=3D"Profiling-oprofile-generating-elf-symbols-for-lisp-func=
tions">
- <title>Generating ELF symbols for Lisp functions</title>
-
- <para>In order to create a lisp heap image which can be used for
- <code>oprofile</code>- based profiling, we need to:</para>
- <orderedlist>
- <listitem>
- <para>load any code that we want to profile</para>
- </listitem>
- <listitem>
- <para>generate a file that contains ELF symbol information describing=
the
- names and addresses of all lisp functions.</para>
- <para>This step involves doing (from within &CCL;)</para>
- <programlisting>
+<chapter id=3D"Profiling">
+ <title>Profiling</title>
+
+ <sect1 id=3D"Profiling-Using-the-Linux-oprofile-system-level-profiler">
+ <title>Using the Linux oprofile system-level profiler</title>
+
+ <para><ulink
+ url=3D"http://oprofile.sourceforge.net"><code>oprofile</code></ulink> =
is a
+ system-level profiler that's available for most modern Linux
+ distributions.</para>
+
+ <para>Use of oprofile and its companion programs isn't really document=
ed
+ here; what is described is a way of generating symbolic information th=
at
+ enables profiling summaries generated by the <code>opreport</code> pro=
gram
+ to identify lisp functions meaningfully.</para>
+
+ <sect2 id=3D"Profiling-oprofile-generating-a-lisp-image-for-use-with-o=
profile">
+ <title>Generating a lisp image for use with oprofile</title>
+
+ <para>Modern Linux uses the 'ELF" (Executable and Linking Format) ob=
ject
+ file format; the oprofile tools can associate symbolic names with
+ addresses in a memory-mapped file if that file appears to be an ELF
+ object file and if it contains ELF symbol information that describes
+ those memory regions. So, the general idea is to make a lisp heap im=
age
+ that looks enough like an ELF shared library to fool the
+ <code>oprofile</code> tools (we don't actually load heap images via =
ELF
+ dynamic linking technology, but we can make it look like we did.)</p=
ara>
+ </sect2>
+
+ <sect2 id=3D"Profiling-oprofile-prerequisites">
+ <title>Prerequisites</title>
+
+ <itemizedlist>
+ <listitem>
+ <para><code>oprofile</code> itself, which is almost certainly
+ available via your distribution's package management system if n=
ot
+ already preinstalled.</para>
+ </listitem>
+
+ <listitem>
+ <para><code>libelf</code>, which provides utilities for reading =
and
+ writing ELF files (and is likewise likely preinstalled or readily
+ installable.) Somewhat confusingly, there are two libelf
+ implementations in widespread use on Linux, and different
+ distributions refer to them by different names (they may be
+ available as part of an 'elfutils' package.) The oprofile inster=
face
+ was designed to work with a libelf implementation whose version
+ number is currently around 147; the other (incompatible) libelf
+ implementation has a version number around 0.8. It may be necess=
ary
+ to install the corresponding development package (-dev or -devel,
+ usuallly) in order to actually be able to use the libelf shared
+ library.</para>
+ </listitem>
+ </itemizedlist>
+ </sect2>
+
+ <sect2 id=3D"Profiling-oprofile-generating-elf-symbols-for-lisp-functi=
ons">
+ <title>Generating ELF symbols for Lisp functions</title>
+
+ <para>In order to create a lisp heap image which can be used for
+ <code>oprofile</code>- based profiling, we need to:</para>
+
+ <orderedlist>
+ <listitem>
+ <para>load any code that we want to profile</para>
+ </listitem>
+
+ <listitem>
+ <para>generate a file that contains ELF symbol information
+ describing the names and addresses of all lisp functions.</para>
+
+ <para>This step involves doing (from within &CCL;)</para>
+
+ <programlisting>
? (require "ELF")
"ELF"
("ELF")
=
? (ccl::write-elf-symbols-to-file "home:elf-symbols")
</programlisting>
- <para>The argument to CCL::WRITE-ELF-SYMBOLS-TO-FILE can be any writa=
ble
- pathname. The function will do whatever's necessary to nail lisp fun=
ctions
- down in memory (so that they aren't moved by GC), then write an ELF o=
bject
- file to the indicated pathname. This typically takes a few seconds.<=
/para>
- </listitem>
- <listitem>
- <para>Generate a lisp heap image in which the ELF symbols generated i=
n the
- previous step are prepended.</para>
- <para>The function CCL:SAVE-APPLICATION provides a :PREPEND-KERNEL ar=
gument,
- which is ordinarily used to save a standalone application in which th=
e kernel
- and heap image occupy a single file. :PREPEND-KERNEL doesn't really =
care what
- it's prepending to the image, and we can just as easily ask it to pre=
pend the
- ELF symbol file generated in the previous step.</para>
- <programlisting>
+
+ <para>The argument to CCL::WRITE-ELF-SYMBOLS-TO-FILE can be any
+ writable pathname. The function will do whatever's necessary to =
nail
+ lisp functions down in memory (so that they aren't moved by GC),
+ then write an ELF object file to the indicated pathname. This
+ typically takes a few seconds.</para>
+ </listitem>
+
+ <listitem>
+ <para>Generate a lisp heap image in which the ELF symbols genera=
ted
+ in the previous step are prepended.</para>
+
+ <para>The function CCL:SAVE-APPLICATION provides a :PREPEND-KERN=
EL
+ argument, which is ordinarily used to save a standalone applicat=
ion
+ in which the kernel and heap image occupy a single file.
+ :PREPEND-KERNEL doesn't really care what it's prepending to the
+ image, and we can just as easily ask it to prepend the ELF symbol
+ file generated in the previous step.</para>
+
+ <programlisting>
? (save-application "somewhere/image-for-profiling"
:prepend-kernel "home:elf-symbols")
</programlisting>
- <para>If you then run</para>
- <programlisting>
-shell> ccl64 somewhare/image-for-profiling
+
+ <para>If you then run</para>
+
+ <programlisting>
+shell> ccl64 somewhare/image-for-profiling
</programlisting>
- <para>any lisp code sampled by oprofile in that image will be identif=
ied
- "symbolically" by <code>opreport</code>.</para>
- </listitem>
- </orderedlist>
- </sect2>
- <sect2 id=3D"Profiling-oprofile-example">
- <title>Example</title>
- <programlisting>
+
+ <para>any lisp code sampled by oprofile in that image will be
+ identified "symbolically" by <code>opreport</code>.</para>
+ </listitem>
+ </orderedlist>
+ </sect2>
+
+ <sect2 id=3D"Profiling-oprofile-example">
+ <title>Example</title>
+
+ <programlisting>
;;; Define some lisp functions that we want to profile and save
;;; a profiling-enabled image. In this case, we just want to =
;;; define the FACTORIAL funcion, to keep things simple.
@@ -119,11 +148,11 @@
;;; Note that use of 'opcontrol' generally requires root access, e.g.,
;;; 'sudo' or equivalent:
=
-[~] gb at rinpoche> sudo opcontrol --no-vmlinux --setup
+[~] gb at rinpoche> sudo opcontrol --no-vmlinux --setup
=
;;; Start the profiler
=
-[~] gb at rinpoche> sudo opcontrol --start
+[~] gb at rinpoche> sudo opcontrol --start
Using 2.6+ OProfile kernel interface.
Using log file /var/lib/oprofile/samples/oprofiled.log
Daemon started.
@@ -132,7 +161,7 @@
;;; Start CCL with the "profiled-ccl" image created above.
;;; Invoke "(FACT 10000)"
=
-[~] gb at rinpoche> ccl64 profiled-ccl =
+[~] gb at rinpoche> ccl64 profiled-ccl =
Welcome to Clozure Common Lisp Version 1.2-r9198M-trunk (LinuxX8664)!
? (null (fact 10000))
NIL
@@ -141,13 +170,13 @@
;;; We could stop the profiler (opcontrol --stop) here; instead,
;;; we simply flush profiling data to disk, where 'opreport' can
;;; find it.
-
-[~] gb at rinpoche> sudo opcontrol --dump
+<token></token>
+[~] gb at rinpoche> sudo opcontrol --dump
=
;;; Ask opreport to show us where we were spending time in the
;;; 'profiled-ccl' image.
=
-[~] gb at rinpoche> opreport -l profiled-ccl | head
+[~] gb at rinpoche> opreport -l profiled-ccl | head
CPU: Core 2, speed 1596 MHz (estimated)
Counted CPU_CLK_UNHALTED events (Clock cycles when not halted) with a unit=
mask of 0x00 (Unhalted core cycles) count 100000
samples % symbol name
@@ -159,218 +188,228 @@
7 0.0712 <Compiled-function.%NANOSLEEP.0x30004040385F>
7 0.0712 <Compiled-function.%ZERO-TRAILING-SIGN-DIGITS.0x30004=
0030F3F>
</programlisting>
- </sect2>
- <sect2 id=3D"Profiling-oprofile-Issues">
- <title>Issues</title>
- <para>CCL::WRITE-ELF-SYMBOLS-TO-FILE currently only works on x86-64; it c=
ertainly
- -could- be made to work on ppc32/ppc64 as well.</para>
-
- <para>So far, no one has been able to make oprofile/opreport options that=
're
- supposed to generate call-stack info generate meaningful call-stack info.=
</para>
-
- <para>As of a few months ago, there was an attempt to provide symbol info=
for
- oprofile/opreport "on the fly", e.g., for use in JIT compilation or other
- incremental compilations scenarios. That's obviously more nearly The Rig=
ht Thing,
- but it might be awhile before that experimental code makes it into widesp=
read
- use.</para>
- </sect2>
- </sect1>
-
- <sect1 id=3D"Profiling-Using-Apples-CHUD-metering-tools">
- <title>Using Apple's CHUD metering tools</title>
- =
- <sect2 id=3D"Profiling-CHUD-prerequisites">
- <title>Prerequisites</title>
-
- <para>Apple's CHUD metering tools are available (as of this writing) from=
:</para>
-
- <para><ulink url=3D"ftp://ftp.apple.com/developer/Tool_Chest/Testing_-_De=
bugging/Performance_tools/">
- ftp://ftp.apple.com/developer/Tool_Chest/Testing_-_Debugging/Performanc=
e_tools/</ulink>.</para>
-
- <para>The CHUD tools are also generally bundled with Apple's XCode tools.=
CHUD
- 4.5.0 (which seems to be bundled with XCode 3.0) seems to work well with =
this
- interface; later versions may have problems. Versions of CHUD as old as =
4.1.1 may
- work with 32-bit PPC versions of CCL; later versions (not sure exactly -w=
hat-
- versions) added x86, ppc64, and x86-64 support.</para>
-
- <para>One way to tell whether any version of the CHUD tools is installed =
is to try
- to invoke the "shark" command-line program (/usr/bin/shark) from the shel=
l:</para>
- <programlisting>
-shell> shark --help
- </programlisting>
- <para>and verifying that that prints a usage summary.</para>
-
- <para>CHUD consists of several components, including command-line program=
s, GUI
- applications, kernel extensions, and "frameworks" (collections of librari=
es,
- headers, and other resources which applications can use to access functio=
nality
- provided by the other components.) Past versions of &CCL;/OpenMCL have u=
sed the
- CHUD framework libraries to control the CHUD profiler. Even though the r=
est of
- CHUD is currently 64-bit aware, the frameworks are unfortunately still on=
ly
- available as 32-bit libraries, so the traditional way of controlling the =
profiling
- facility from &CCL; has only worked from DarwinPPC32 versions.</para>
-
- <para>Two of the CHUD component programs are of particular interest:</par=
a>
-
- <orderedlist>
- <listitem>
- <para>The "Shark" application (often installed in
- "/Developer/Applications/Performance Tools/Shark.app"), which provide=
s a
- graphical user interface for exploring and analyzing profiling result=
s and
- provides tools for creating "sampling configurations" (see below), am=
ong other
- things.</para>
- </listitem>
- <listitem>
- <para>The "shark" program ("/usr/bin/shark"), which can be used to co=
ntrol the
- CHUD profiling facility and to collect sampling data, which can then =
be
- displayed and analyzed in Shark.app.</para>
- </listitem>
- </orderedlist>
-
- <para>The fact that these two (substantially different) programs have nam=
es that
- differ only in alphabetic case may be confusing. The discussion below tr=
ies to
- consistently distinguish between "the shark program" and "the Shark
- application".</para>
-
- </sect2>
- <sect2 id=3D"Profiling-CHUD-usage-synopsis">
- <title>Usage synopsis</title>
- <programlisting>
-? (defun fact (n) (if (zerop n) 1 (* n (fact (1- n)))))
+ </sect2>
+
+ <sect2 id=3D"Profiling-oprofile-Issues">
+ <title>Issues</title>
+
+ <para>CCL::WRITE-ELF-SYMBOLS-TO-FILE currently only works on x86-64;=
it
+ certainly -could- be made to work on ppc32/ppc64 as well.</para>
+
+ <para>So far, no one has been able to make oprofile/opreport options
+ that're supposed to generate call-stack info generate meaningful
+ call-stack info.</para>
+
+ <para>As of a few months ago, there was an attempt to provide symbol
+ info for oprofile/opreport "on the fly", e.g., for use in JIT
+ compilation or other incremental compilation scenarios. That's obvio=
usly
+ more nearly The Right Thing, but it might be awhile before that
+ experimental code makes it into widespread use.</para>
+ </sect2>
+ </sect1>
+
+ <sect1 id=3D"Profiling-Using-Apples-CHUD-metering-tools">
+ <title>Using Apple's CHUD metering tools</title>
+
+ <para>Apple's CHUD package provides libraries, kernel extensions, and a
+ set of graphical and command-line programs that can be used to measure
+ many aspects of application and system performance.</para>
+
+ <para>One of these programs is the Shark application (often installed =
in
+ "/Developer/Applications/Performance Tools/Shark.app"), which provides=
a
+ graphical user interface for exploring and analyzing profiling results=
and
+ provides tools for creating "sampling configurations" (see below), amo=
ng
+ other things. Use of Shark isn't really documented here (a Shark manua=
l is
+ available at "Developer/Documentation/CHUD/Shark/ SharkUserGuide.pdf");
+ what is described is a way of providing information about Lisp function
+ names and addresses so that Shark can meaningly identify those functio=
ns
+ in its output.</para>
+
+ <sect2 id=3D"Profiling-CHUD-prerequisites">
+ <title>Prerequisites</title>
+
+ <para>Apple's CHUD tools have been distributed with the last several
+ XCode releases. One way to determine whether or not the tools are
+ installed is to run:</para>
+
+ <programlisting>$ /usr/bin/shark -v</programlisting>
+
+ <para>in a terminal or Emacs shell buffer. If that returns output
+ like</para>
+
+ <programlisting>shark 4.7.3 (365)</programlisting>
+
+ <para>then the CHUD package is installed. Output like</para>
+
+ <programlisting>shark: Command not found.</programlisting>
+
+ <para>strongly suggests that it isn't ...</para>
+ </sect2>
+
+ <sect2>
+ <title>Generating a lisp image for use with Shark</title>
+
+ <para>Shark can only properly identify functions that're defined in a
+ shared library that's loaded by the target application. (Any other
+ functions will be identified by a hex address described as being in =
an
+ "Unknown Library"; the hex address is generally somewhat near the ac=
tual
+ function, but it's determined heuristically and isn't always
+ accurate.)</para>
+
+ <para>For those reasons, it's desirable to load the code that you wi=
sh
+ to profile in one lisp session, save a native (Mach-O library) image,
+ and invoke Shark in a new session which uses that native image. (It =
may
+ also be useful to load the CHUD-METERING module, which defines
+ CHUD:METER and friends.</para>
+
+ <para></para>
+ </sect2>
+
+ <sect2 id=3D"Profiling-CHUD-usage-synopsis">
+ <title>Usage synopsis</title>
+
+ <programlisting>[src/ccl-dev] gb at antinomial> ccl64
+Welcome to Clozure Common Lisp Version 1.7-dev-r14624M-trunk (DarwinX8664=
)!
+? (defun fact(n) (if (zerop n) 1 (* n (fact (1- n)))))
FACT
? (require "CHUD-METERING")
"CHUD-METERING"
("CHUD-METERING")
-? (chud:meter (null (fact 10000)))
-NIL ; since that large number is not NULL
- </programlisting>
-
- <para>and, a few seconds after the result is returned, a file whose nam=
e is of
- the form "session_nnn.mshark" will open in Shark.app.</para>
-
- <para>The fist time that CHUD:METER is used in a lisp session, it'll do=
a few
- things to prepare subsequent profiling sessions. Those things include:=
</para>
-
- <itemizedlist>
- <listitem>
- <para>creating a directory to store files that are related to using=
the CHUD
- tools in this lisp session. This directory is created in the user'=
s home
- directory and has a name of the form:</para>
-
- <programlisting>
+? (save-application "ccl:dx86cl64.dylib" :native t)
+[src/ccl-dev] gb at antinomial> ccl64 -I dx86cl64.dylib
+Welcome to Clozure Common Lisp Version 1.7-dev-r14624M-trunk (DarwinX8664=
)!
+? (chud:meter (dotimes (i 1000) (fact 1000)))
+;;; Waiting for shark to process samples ...done.
+NIL</programlisting>
+
+ <para>and, a few seconds after the result is returned, a file whose =
name
+ is of the form "session_nnn.mshark" will open in Shark.app.</para>
+
+ <para></para>
+
+ <para>The fist time that CHUD:METER is used in a lisp session, it'll=
do
+ a few things to prepare subsequent profiling sessions. Those things
+ include:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>creating a directory to store files that are related to us=
ing
+ the CHUD tools in this lisp session. This directory is created in
+ the user's home directory and has a name of the form:</para>
+
+ <programlisting>
profiling-session-<lisp-kernel>-<pid>_<mm>-<dd>-&l=
t;yyyy>_<h>.<m>.<s>
</programlisting>
-
- <para>where <pid> is the lisp's process id, <lisp-kernel&g=
t; is the
- name of the lisp kernel (of all things ...), and the other values p=
rovide a
- timestamp.</para>
- </listitem>
- <listitem>
- <para>does whatever needs to be done to ensure that currently-defin=
ed lisp
- functions don't move around as the result of GC activity, then writ=
es a text
- file describing the names and addresses of those functions to the
- profiling-session directory created above. (The naming conventions=
for and
- format of that file are described in</para>
- <para>
- <ulink url=3D"http://developer.apple.com/documentation/DeveloperToo=
ls/Conceptual/SharkUserGuide/MiscellaneousTopics/chapter_951_section_4.html=
#//apple_ref/doc/uid/TP40005233-CH14-DontLinkElementID_42">http://developer=
.apple.com/documentation/DeveloperTools/Conceptual/SharkUserGuide/Miscellan=
eousTopics/chapter_951_section_4.html#//apple_ref/doc/uid/TP40005233-CH14-D=
ontLinkElementID_42</ulink></para>
- </listitem>
- <listitem>
- <para>run the shark program ("/usr/bin/shark") and wait until it's =
ready to
- receive signals that control its operation.</para>
- </listitem>
- </itemizedlist>
-
- <para>This startup activity typically takes a few seconds; after it's b=
een
- completed, subsequent use of CHUD:METER doesn't involve that overhead. =
(See the
- discussion of :RESET below.)</para>
-
- <para>After any startup activity is complete, CHUD:METER arranges to se=
nd a
- "start profiling" signal to the running shark program, executes the for=
m, sends
- a "stop profiling" signal to the shark program, and reads its diagnosti=
c output,
- looking for the name of the ".mshark" file it produces. If it's able t=
o find
- this filename, it arranges for "Shark.app" to open it.</para>
- </sect2>
-
- <sect2 id=3D"Profiling-CHUD-profiling-configurations">
- <title>Profiling "configurations"</title>
-
- <para>By default, a shark profiling session will:</para>
- <itemizedlist>
- <listitem>
- <para>use "time based" sampling, to periodically interrupt the lisp
- process and note the value of the program counter and at least a few =
levels of
- call history.</para>
- </listitem>
- <listitem>
- <para>do this sampling once every millisecond</para>
- </listitem>
- <listitem>
- <para>run for up to 30 seconds, unless told to stop earlier.</para>
- </listitem>
- </itemizedlist>
-
- <para>This is known as "the default configuration"; it's possible to us=
e items
- on the "Config" menu in the Shark application to create alternate confi=
gurations
- which provide different kinds of profiling parameters and to save these
- configurations in files for subsequent reuse. (The set of things that =
CHUD
- knows how to monitor is large and interesting.)</para>
-
- <para>You use alternate profiling configurations (created and "exported=
" via
- Shark.app) with CHUD:METER, but the interface is a little awkward.</par=
a>
- </sect2>
-
- <sect2 id=3D"Profiling-CHUD-Reference">
- <title>Reference</title>
-
- <para>
- <indexterm zone=3D"chud_shark-config-file"/>
- <command><varname id=3D"chud_shark-config-file">CHUD:*SHARK-CONFIG-FI=
LE*</varname> [Variable]</command>
- </para>
-
- <para>When non-null, this should be the pathname of an alternate profil=
ing
- configuration file created by the "Config Editor" in Shark.app.</para>
-
- <para>
- <indexterm zone=3D"chud_meter"/>
- <command><varname id=3D"chud_meter">CHUD:METER</varname> form &key; (=
reset nil) (debug-output nil) [Macro]</command>
- </para>
- =
- <para>Executes FORM (an arbitrary lisp form) and returns whatever resul=
t(s) it
- returns, with CHUD profiling enabled during the form's execution. Trie=
s to
- determine the name of the session file (*.mshark) to which the shark pr=
ogram
- wrote profiling data and opens this file in the Shark application.</par=
a>
- =
- <para>Arguments:</para>
-
- <variablelist>
- <varlistentry>
- <term><varname>debug-output</varname></term>
- <listitem>
- <para>when non-nil, causes output generated by the shark program to be
- echoed to *TERMINAL-IO*. For debugging.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><varname>reset</varname></term>
- <listitem>
- <para>when non-nil, terminates any running instance of the shark program
- created by previous invocations of CHUD:METER in this lisp session,
- generates a new .spatch file (describing the names and addresses of lisp
- functions), and starts a new instance of the shark program; if
- CHUD:*SHARK-CONFIG-FILE* is non-NIL when this new instance is started,
- that instance is told to use the specified config file for profiling (in
- lieu of the default profiling configuration.)</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </sect2>
-
- <sect2 id=3D"Profiling-CHUD-Acknowledgments">
- <title>Acknowledgement</title>
- <para>Both Dan Knapp and Hamilton Link have posted similar CHUD interfa=
ces to
- openmcl-devel in the past; Hamilton's also reported bugs in the spatch =
mechanism
- to CHUD developers (and gotten those bugs fixed.)</para>
- </sect2>
-
- </sect1>
-
- </chapter>
+ </listitem>
+
+ <listitem>
+ <para>run the shark program ("/usr/bin/shark") and wait until it=
's
+ ready to receive signals that control its operation.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>This startup activity typically takes a few seconds; after it's
+ been completed, subsequent use of CHUD:METER doesn't involve that
+ overhead. (See the discussion of :RESET below.)</para>
+
+ <para>After any startup activity is complete, CHUD:METER arranges to
+ send a "start profiling" signal to the running shark program, execut=
es
+ the form, sends a "stop profiling" signal to the shark program, and
+ reads its diagnostic output, looking for the name of the ".mshark" f=
ile
+ it produces. If it's able to find this filename, it arranges for
+ "Shark.app" to open it.</para>
+ </sect2>
+
+ <sect2 id=3D"Profiling-CHUD-profiling-configurations">
+ <title>Profiling "configurations"</title>
+
+ <para>By default, a shark profiling session will:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>use "time based" sampling, to periodically interrupt the l=
isp
+ process and note the value of the program counter and at least a=
few
+ levels of call history.</para>
+ </listitem>
+
+ <listitem>
+ <para>do this sampling once every millisecond</para>
+ </listitem>
+
+ <listitem>
+ <para>run for up to 30 seconds, unless told to stop earlier.</pa=
ra>
+ </listitem>
+ </itemizedlist>
+
+ <para>This is known as "the default configuration"; it's possible to=
use
+ items on the "Config" menu in the Shark application to create altern=
ate
+ configurations which provide different kinds of profiling parameters=
and
+ to save these configurations in files for subsequent reuse. (The set=
of
+ things that CHUD knows how to monitor is large and interesting.)</pa=
ra>
+
+ <para>You use alternate profiling configurations (created and "expor=
ted"
+ via Shark.app) with CHUD:METER, but the interface is a little
+ awkward.</para>
+ </sect2>
+
+ <sect2 id=3D"Profiling-CHUD-Reference">
+ <title>Reference</title>
+
+ <para><indexterm zone=3D"chud_shark-config-file"></indexterm>
+ <command><varname
+ id=3D"chud_shark-config-file">CHUD:*SHARK-CONFIG-FILE*</varname>
+ [Variable]</command></para>
+
+ <para>When non-null, this should be the pathname of an alternate
+ profiling configuration file created by the "Config Editor" in
+ Shark.app.</para>
+
+ <para><indexterm zone=3D"chud_meter"></indexterm> <command><varname
+ id=3D"chud_meter">CHUD:METER</varname> form &key; (reset nil)
+ (debug-output nil) [Macro]</command></para>
+
+ <para>Executes FORM (an arbitrary lisp form) and returns whatever
+ result(s) it returns, with CHUD profiling enabled during the form's
+ execution. Tries to determine the name of the session file (*.mshark=
) to
+ which the shark program wrote profiling data and opens this file in =
the
+ Shark application.</para>
+
+ <para>Arguments:</para>
+
+ <variablelist>
+ <varlistentry>
+ <term><varname>debug-output</varname></term>
+
+ <listitem>
+ <para>when non-nil, causes output generated by the shark progr=
am
+ to be echoed to *TERMINAL-IO*. For debugging.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>reset</varname></term>
+
+ <listitem>
+ <para>when non-nil, terminates any running instance of the sha=
rk
+ program created by previous invocations of CHUD:METER in this =
lisp
+ session, generates a new .spatch file (describing the names and
+ addresses of lisp functions), and starts a new instance of the
+ shark program; if CHUD:*SHARK-CONFIG-FILE* is non-NIL when this
+ new instance is started, that instance is told to use the
+ specified config file for profiling (in lieu of the default
+ profiling configuration.)</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </sect2>
+
+ <sect2 id=3D"Profiling-CHUD-Acknowledgments">
+ <title>Acknowledgement</title>
+
+ <para>Both Dan Knapp and Hamilton Link have posted similar CHUD
+ interfaces to openmcl-devel in the past; Hamilton's also reported bu=
gs
+ in the spatch mechanism to CHUD developers (and gotten those bugs
+ fixed.)</para>
+ </sect2>
+ </sect1>
+</chapter>
Modified: trunk/source/doc/src/using.xml
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D
--- trunk/source/doc/src/using.xml (original)
+++ trunk/source/doc/src/using.xml Thu Feb 3 01:43:20 2011
@@ -1917,8 +1917,8 @@
tool that runs the same way any command-line program
does. Alternatively, if you choose not to prepend the kernel, you
can save an image and then later run it by passing it as a
- command-line parameter to the <literal>opencml</literal>
- or <literal>opencml64</literal> script.</para>
+ command-line parameter to the <literal>ccl</literal>
+ or <literal>ccl64</literal> script.</para>
=
<para>
<indexterm zone=3D"save-application"/>
@@ -1934,6 +1934,7 @@
<parameter>impurify</parameter>
<parameter>(mode #o644)</parameter>
<parameter>prepend-kernel</parameter>
+ <parameter>native</parameter>
[Function]</command>
</para>
=
@@ -2008,6 +2009,15 @@
CLOS caches are clear when the image starts up, you can pass
any true value.</para>
</listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><varname>native</varname></term>
+ <listitem>
+ <para>If true, saves the image as a native (ELF, Mach-O, PE)
+ shared library. (On platforms where this isn't yet supported,
+ a warning is issued and the option is ignored.)
+ </para>
+ </listitem>
</varlistentry>
=
=
Modified: trunk/source/library/chud-metering.txt
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D
--- trunk/source/library/chud-metering.txt (original)
+++ trunk/source/library/chud-metering.txt Thu Feb 3 01:43:20 2011
@@ -1,157 +1,1 @@
-Using Apple's CHUD metering tools from CCL
-=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
-
-Prerequisites
--------------
-
-Apple's CHUD metering tools are available (as of this writing) from:
-
-<ftp://ftp.apple.com/developer/Tool_Chest/Testing_-_Debugging/Performance_=
tools/>. =
-
-The CHUD tools are also generally bundled with Apple's XCode tools.
-CHUD 4.5.0 (which seems to be bundled with XCode 3.0) seems to work
-well with this interface; later versions may have problems.
-Versions of CHUD as old as 4.1.1 may work with 32-bit PPC versions
-of CCL; later versions (not sure exactly -what- versions) added
-x86, ppc64, and x86-64 support.
-
-One way to tell whether any version of the CHUD tools is installed
-is to try to invoke the "shark" command-line program (/usr/bin/shark)
-from the shell:
-
-shell> shark --help
-
-and verifying that that prints a usage summary.
-
-CHUD consists of several components, including command-line programs,
-GUI applications, kernel extensions, and "frameworks" (collections of
-libraries, headers, and other resources which applications can use to
-access functionality provided by the other components.) Past versions
-of CCL/OpenMCL have used the CHUD framework libraries to control the
-CHUD profiler. Even though the rest of CHUD is currently 64-bit aware,
-the frameworks are unfortunately still only available as 32-bit libraries,
-so the traditional way of controlling the profiling facility from OpenMCL
-has only worked from DarwinPPC32 versions.
-
-Two of the CHUD component programs are of particular interest:
-
-1) The "Shark" application (often installed in
-"/Developer/Applications/Performance Tools/Shark.app"), which provides
-a graphical user interface for exploring and analyzing profiling results
-and provides tools for creating "sampling configurations" (see below),
-among other things.
-
-2) the "shark" program ("/usr/bin/shark"), which can be used to control
-the CHUD profiling facility and to collect sampling data, which can then
-be displayed and analyzed in Shark.app.
-
-The fact that these two (substantially different) programs have names that
-differ only in alphabetic case may be confusing. The discussion below
-tries to consistently distinguish between "the shark program" and "the
-Shark application".
-
-Usage synopsis
---------------
-
-? (defun fact (n) (if (zerop n) 1 (* n (fact (1- n)))))
-FACT
-? (require "CHUD-METERING")
-"CHUD-METERING"
-("CHUD-METERING")
-? (chud:meter (null (fact 10000)))
-NIL ; since that large number is not NULL
-
-and, a few seconds after the result is returned, a file whose
-name is of the form "session_nnn.mshark" will open in Shark.app.
-
-The fist time that CHUD:METER is used in a lisp session, it'll do a
-few things to prepare subsequent profiling sessions. Those things
-include:
-
-1) creating a directory to store files that are related to using
-the CHUD tools in this lisp session. This directory is created in
-the user's home directory and has a name of the form:
-
-profiling-session-<lisp-kernel>-<pid>_<mm>-<dd>-<yyyy>_<h>.<m>.<s>
-
-where <pid> is the lisp's process id, <lisp-kernel> is the name of
-the lisp kernel (of all things ...), and the other values provide
-a timestamp.
-
-2) does whatever needs to be done to ensure that currently-defined
-lisp functions don't move around as the result of GC activity, then
-writes a text file describing the names and addresses of those functions
-to the profiling-session directory created above. (The naming conventions
-for and format of that file are described in
-
-<http://developer.apple.com/documentation/DeveloperTools/Conceptual/SharkU=
serGuide/MiscellaneousTopics/chapter_951_section_4.html#//apple_ref/doc/uid=
/TP40005233-CH14-DontLinkElementID_42>
-
-3) run the shark program ("/usr/bin/shark") and wait until it's ready to
-receive signals that control its operation.
-
-This startup activity typically takes a few seconds; after it's been
-completed, subsequent use of CHUD:METER doesn't involve that overhead.
-(See the discussion of :RESET below.)
-
-After any startup activity is complete, CHUD:METER arranges to send
-a "start profiling" signal to the running shark program, executes
-the form, sends a "stop profiling" signal to the shark program, and
-reads its diagnostic output, looking for the name of the ".mshark"
-file it produces. If it's able to find this filename, it arranges
-for "Shark.app" to open it
-
-Profiling "configurations".
---------------------------
-
-By default, a shark profiling session will:
-a) use "time based" sampling, to periodically interrupt the lisp
- process and note the value of the program counter and at least
- a few levels of call history.
-b) do this sampling once every millisecond
-c) run for up to 30 seconds, unless told to stop earlier.
-
-This is known as "the default configuration"; it's possible to use
-items on the "Config" menu in the Shark application to create alternate
-configurations which provide different kinds of profiling parameters
-and to save these configurations in files for subsequent reuse.
-(The set of things that CHUD knows how to monitor is large and interesting=
.)
-
-You use alternate profiling configurations (created and "exported" via
-Shark.app) with CHUD:METER, but the interface is a little awkward.
-
-Reference
----------
-
-CHUD:*SHARK-CONFIG-FILE* [Variable]
-
-When non-null, this should be the pathname of an alternate profiling
-configuration file created by the "Config Editor" in Shark.app.
-
-(CHUD:METER form &key (reset nil) (debug-output nil)) [Macro]
-
-Executes FORM (an arbitrary lisp form) and returns whatever result(s)
-it returns, with CHUD profiling enabled during the form's execution.
-Tries to determine the name of the session file (*.mshark) to which
-the shark program wrote profiling data and opens this file in the
-Shark application.
-
-Arguments:
-
-debug-output - when non-nil, causes output generated by the shark progra=
m to
- be echoed to *TERMINAL-IO*. For debugging.
-reset - when non-nil, terminates any running instance of the
- shark program created by previous invocations of CHUD:MET=
ER
- in this lisp session, generates a new .spatch file =
- (describing the names and addresses of lisp functions),
- and starts a new instance of the shark program; if
- CHUD:*SHARK-CONFIG-FILE* is non-NIL when this new instance
- is started, that instance is told to use the specified
- config file for profiling (in lieu of the default profili=
ng
- configuration.)
-
-Acknowledgments
----------------
-
-Both Dan Knapp and Hamilton Link have posted similar CHUD interfaces
-to openmcl-devel in the past; Hamilton's also reported bugs in the
-spatch mechanism to CHUD developers (and gotten those bugs fixed.)
+See section 11.2 of the Clozure CL manual.
More information about the Openmcl-cvs-notifications
mailing list