$Revision: 5.0.2.3 $
Package: PROFILER
Arguments: (&key type
start-sampling-p count count-list except-processes
except-stack-groups
interpret-closures verbose)
This function starts the collection of profile data. It creates two new files in a temporary location for saving sample data and initializes the profiler data structures. These files are removed after the profile is analyzed. See profiling.htm under the heading Further points for the location of the temporary directory.
The type keyword argument specifies the type of profile data to be collected. The choices are
Value | Meaning |
:time | collect time profile data (but not space data) |
:space | collect space profile data (but not time data) |
:count-only | collect call-count data but no time or space data |
If the value of type is :time or :space, call-counting data is collected if either count or count-list (or both) is non-nil. The default value of type depends on the values of count and count-list. If either is non-nil, type defaults to :count-only. If both count and count-list are nil (or unspecified, since they default to nil), type defaults to :time.
The count and count-list arguments control whether call-counting information should be collected during the profiler run. Call count information is collected if either argument is non-nil. Both default to nil.
count can be a positive integer or t. If it is a positive integer, a hash table with that many entries is created. If it is t, a hash table of 1000 entries is created. The table is filled with function objects specified by count-list, if any. New function objects (beyond what is specified in count-list) are added to the table as the associated function is called.until the table is filled. No information is collected on function objects called for the first time after the table is filled.
count-list, if specified, should be a list of function objects (not symbols -- thus elements should be #'foo rather than foo). The hash table mentioned in the description of count just above is filled with the elements of count-list, in order, until the hash table is filled or the list is exhausted. Specifying a value for this variable ensures that functions you are interested in are call-counted. Note that if the length of the list is greater than the value of count, only the first count elements are entered in the hash table; the rest are ignored. If count-list has a non-nil value but no value is specified for count, count defaults to 1000 (even is the length of count-list is greater than 1000).
If the start-sampling-p keyword argument is non-nil or is not supplied then sampling is started immediately. If it is specified nil, sampling is not started until start-sampling is called. The functions start-sampling and stop-sampling can be used to control the gathering of samples while the profiler is running. The default value of this argument is t.
On platforms where OS threads are used for multiprocessing (in 5.,0, Windows only), the except-processes keyword argument should be a list of processes. This argument causes the profiler to not record profiling information for the processes listed in this argument. Use of this argument is a good way to narrow down the extent of a profile, if multiprocessing is being used.
On other platforms. except-stack-groups should be used instead. Again, its value should be a list of stack-groups or processes.
except-stack-groups is interpreted on OS threads platforms (Windows only in 5.0) as except-processes but a warning is signaled suggesting use of :except-processes instead. except-processes is not accepted on non-OS-threads platforms. It is always an error to specify values for both arguments.
The interpret-closures argument controls the handling of closures. When interpret-closures is nil
(the default) the closures are not saved and analyzed separately; the behavior is the same
as in earlier releases of Allegro CL on UNIX. When non-nil,
closures are saved and analyzed as separate profile entries, even though they may use the
same template function. A function specialization called prof:closure
has been added. This is valid whenever an analyzed profile exists and identifies the
closures which the profiler has seen. The specialization is (prof:closure
n) where n is a small integer enumerating the closures in the profile. This allows
the user to grab the closure object and to do a prof:disassemble-profile
on it without having to know what symbol holds its fdefinition
(sometimes
this is very hard).
When flat profiles and call-graphs are reported, closures are identified by (prof:closure n), followed by the printed representation of the closure object itself.
Note that if you use the Emacs-Lisp interface or the IDE (on Windows), you are using multiprocessing. The :processes top-level command lists active processes. The Process Browser in Allegro Composer (on UNIX) and the one displayed with View | Processes in the IDE (on Windows) also list processes and provides a graphic interface to include or exclude a process from profiling.
The verbose argument, if non-nil (default is nil), causes messages about what the profiler is doing to be printed to *standard-output* during the profile.
Only one profile can run at a time. Calling this function while a profile is running will signal an error.
See profiling.htm for general information on profiling. Note that the profiler is not available with some Allegro CL products.
The general documentation description is in introduction.htm. The index in index.htm.
Copyright (C) 1998-1999, Franz Inc., Berkeley, CA. All Rights Reserved.