turn on profiling for one function
Major Section:  EVENTS

NOTE: An alternative to this utility, which has a lot less functionality but doesn't depend on the experimental extension of ACL2 mentioned just below, may be found in community book books/misc/profiling.lisp.

This documentation topic relates to an experimental extension of ACL2 under development by Bob Boyer and Warren Hunt. See hons-and-memoization for a general discussion of memoization, on which this profile utility is built, and the related features of hash consing and applicative hash tables.

Profile can be useful in Common Lisp debugging and performance analysis, including examining the behavior of ACL2 functions.

(profile 'fn)       ; keep count of the calls of fn
(profile 'fn        ; as above, with with some memoize options
         :trace t
         :forget t)
(memsum) ; report statistics on calls of memoized functions (e.g., fn)
(clear-memoize-statistics) ; clear memoization (and profiling) statistics

Evaluation of (profile 'fn) redefines fn so that a count will be kept of the calls of FN. The information recorded may be displayed, for example, by invoking (memoize-summary) or (equivalently) (memsum). If you wish to gather fresh statistics for the evaluation of a top-level form, see clear-memoize-statistics.

Profile is just a macro that calls memoize to do its work. Profile gives the two keyword parameters :condition and :recursive of memoize the value nil. Other keyword parameters for memoize, which must not include :condition, :condition-fn, or :recursive, are passed through. To eliminate profiling, use unmemoize; for example, to eliminate profiling for function fn, evaluate (unmemoize 'fn).

You may find raw Lisp functions profile-all and profile-acl2 to be useful. Please contact the ACL2 developers if you want versions of these functions to be executable from inside the ACL2 read-eval-print loop.