Previous Section Next Chapter Table of Contents Glossary Index

Chapter 12. Profiling

12.2. Using Apple's CHUD metering tools

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.

One of these programs is the Shark application (often installed in "/Developer/Applications/Performance Tools/"), which provides a graphical user interface for exploring and analyzing profiling results and provides tools for creating "sampling configurations" (see below), among other things. Use of Shark isn't really documented here (a Shark manual 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 functions in its output.

12.2.1. Prerequisites

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:

$ /usr/bin/shark -v

in a terminal or Emacs shell buffer. If that returns output like

shark 4.7.3 (365)

then the CHUD package is installed. Output like

shark: Command not found.

strongly suggests that it isn't ...

12.2.2. Generating a lisp image for use with Shark

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 actual function, but it's determined heuristically and isn't always accurate.)

For those reasons, it's desirable to load the code that you wish 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.

12.2.3. Usage synopsis

[src/ccl-dev] gb@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)))))
? (require "CHUD-METERING")
? (save-application "ccl:dx86cl64.dylib" :native t)
[src/ccl-dev] gb@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.

and, a few seconds after the result is returned, a file whose name is of the form "session_nnn.mshark" will open in

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:

  • 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:

  • 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 "" to open it.

12.2.4. Profiling "configurations"

By default, a shark profiling session will:

  • 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.

  • do this sampling once every millisecond

  • 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 with CHUD:METER, but the interface is a little awkward.

12.2.5. Reference


When non-null, this should be the pathname of an alternate profiling configuration file created by the "Config Editor" in

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.



when non-nil, causes output generated by the shark program to be echoed to *TERMINAL-IO*. For debugging.


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.)

12.2.6. Acknowledgement

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.)

Previous Section Next Chapter Table of Contents Glossary Index