source: branches/qres/ccl/library/chud-metering.txt @ 13564

Last change on this file since 13564 was 11101, checked in by gz, 11 years ago

Another round of changes from the trunk, mostly just mods in internal mechanisms in support of various recent ports.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 6.6 KB
Line 
1Using Apple's CHUD metering tools from CCL
2==========================================
3
4Prerequisites
5-------------
6
7Apple's CHUD metering tools are available (as of this writing) from:
8
9<ftp://ftp.apple.com/developer/Tool_Chest/Testing_-_Debugging/Performance_tools/>.
10
11The CHUD tools are also generally bundled with Apple's XCode tools.
12CBUD 4.5.0 (which seems to be bundled with XCode 3.0) seems to work
13well with this interface; later versions may have problems.
14Versions of CHUD as old as 4.1.1 may work with 32-bit PPC versions
15of CCL; later versions (not sure exactly -what- versions) added
16x86, ppc64, and x86-64 support.
17
18One way to tell whether any version of the CHUD tools is installed
19is to try to invoke the "shark" command-line program (/usr/bin/shark)
20from the shell:
21
22shell> shark --help
23
24and verifying that that prints a usage summary.
25
26CHUD consists of several components, including command-line programs,
27GUI applications, kernel extensions, and "frameworks" (collections of
28libraries, headers, and other resources which applications can use to
29access functionality provided by the other components.)  Past versions
30of CCL/OpenMCL have used the CHUD framework libraries to control the
31CHUD profiler.  Even though the rest of CHUD is currently 64-bit aware,
32the frameworks are unfortunately still only available as 32-bit libraries,
33so the traditional way of controlling the profiling facility from OpenMCL
34has only worked from DarwinPPC32 versions.
35
36Two of the CHUD component programs are of particular interest:
37
381) The "Shark" application (often installed in
39"/Developer/Applications/Performance Tools/Shark.app"), which provides
40a graphical user interface for exploring and analyzing profiling results
41and provides tools for creating "sampling configurations" (see below),
42among other things.
43
442) the "shark" program ("/usr/bin/shark"), which can be used to control
45the CHUD profiling facility and to collect sampling data, which can then
46be displayed and analyzed in Shark.app.
47
48The fact that these two (substantially different) programs have names that
49differ only in alphabetic case may be confusing.  The discussion below
50tries to consistently distinguish between "the shark program" and "the
51Shark application".
52
53Usage synopsis
54--------------
55
56? (defun fact (n) (if (zerop n) 1 (* n (fact (1- n)))))
57FACT
58? (require "CHUD-METERING")
59"CHUD-METERING"
60("CHUD-METERING")
61? (chud:meter (null (fact 10000)))
62NIL           ; since that large number is not NULL
63
64and, a few seconds after the result is returned, a file whose
65name is of the form "session_nnn.mshark" will open in Shark.app.
66
67The fist time that CHUD:METER is used in a lisp session, it'll do a
68few things to prepare subsequent profiling sessions.  Those things
69include:
70
711) creating a directory to store files that are related to using
72the CHUD tools in this lisp session.  This directory is created in
73the user's home directory and has a name of the form:
74
75profiling-session-<lisp-kernel>-<pid>_<mm>-<dd>-<yyyy>_<h>.<m>.<s>
76
77where <pid> is the lisp's process id, <lisp-kernel> is the name of
78the lisp kernel (of all things ...), and the other values provide
79a timestamp.
80
812) does whatever needs to be done to ensure that currently-defined
82lisp functions don't move around as the result of GC activity, then
83writes a text file describing the names and addresses of those functions
84to the profiling-session directory created above.  (The naming conventions
85for and format of that file are described in
86
87<http://developer.apple.com/documentation/DeveloperTools/Conceptual/SharkUserGuide/MiscellaneousTopics/chapter_951_section_4.html#//apple_ref/doc/uid/TP40005233-CH14-DontLinkElementID_42>
88
893) run the shark program ("/usr/bin/shark") and wait until it's ready to
90receive signals that control its operation.
91
92This startup activity typically takes a few seconds; after it's been
93completed, subsequent use of CHUD:METER doesn't involve that overhead.
94(See the discussion of :RESET below.)
95
96After any startup activity is complete, CHUD:METER arranges to send
97a "start profiling" signal to the running shark program, executes
98the form, sends a "stop profiling" signal to the shark program, and
99reads its diagnostic output, looking for the name of the ".mshark"
100file it produces.  If it's able to find this filename, it arranges
101for "Shark.app" to open it
102
103Profiling "configurations".
104--------------------------
105
106By default, a shark profiling session will:
107a) use "time based" sampling, to periodically interrupt the lisp
108   process and note the value of the program counter and at least
109   a few levels of call history.
110b) do this sampling once every millisecond
111c) run for up to 30 seconds, unless told to stop earlier.
112
113This is known as "the default configuration"; it's possible to use
114items on the "Config" menu in the Shark application to create alternate
115configurations which provide different kinds of profiling parameters
116and to save these configurations in files for subsequent reuse.
117(The set of things that CHUD knows how to monitor is large and interesting.)
118
119You use alternate profiling configurations (created and "exported" via
120Shark.app) with CHUD:METER, but the interface is a little awkward.
121
122Reference
123---------
124
125CHUD:*SHARK-CONFIG-FILE*   [Variable]
126
127When non-null, this should be the pathname of an alternate profiling
128configuration file created by the "Config Editor" in Shark.app.
129
130(CHUD:METER form &key (reset nil) (debug-output nil))  [Macro]
131
132Executes FORM (an arbitrary lisp form) and returns whatever result(s)
133it returns, with CHUD profiling enabled during the form's execution.
134Tries to determine the name of the session file (*.mshark) to which
135the shark program wrote profiling data and opens this file in the
136Shark application.
137
138Arguments:
139
140debug-output   - when non-nil, causes output generated by the shark program to
141                 be echoed to *TERMINAL-IO*.  For debugging.
142reset          - when non-nil, terminates any running instance of the
143                 shark program created by previous invocations of CHUD:METER
144                 in this lisp session, generates a new .spatch file
145                 (describing the names and addresses of lisp functions),
146                 and starts a new instance of the shark program; if
147                 CHUD:*SHARK-CONFIG-FILE* is non-NIL when this new instance
148                 is started, that instance is told to use the specified
149                 config file for profiling (in lieu of the default profiling
150                 configuration.)
151
152Acknowledgments
153---------------
154
155Both Dan Knapp and Hamilton Link have posted similar CHUD interfaces
156to openmcl-devel in the past; Hamilton's also reported bugs in the
157spatch mechanism to CHUD developers (and gotten those bugs fixed.)
Note: See TracBrowser for help on using the repository browser.