From d8917eba1c683d7e4fdbfc38ab52c7bc0025bdc6 Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Sat, 17 Feb 2018 11:59:36 +0200 Subject: [PATCH] Improve documentation of Profiling features * doc/lispref/debugging.texi (Profiling): Improve the description of elp.el. Improve wording of the rest of the section. (Bug#30491) * lisp/emacs-lisp/elp.el (elp-instrument-list): Make the interactive invocation work. Doc fix. --- doc/lispref/debugging.texi | 59 ++++++++++++++++++++++-------------- lisp/emacs-lisp/benchmark.el | 3 +- lisp/emacs-lisp/elp.el | 5 +-- 3 files changed, 41 insertions(+), 26 deletions(-) diff --git a/doc/lispref/debugging.texi b/doc/lispref/debugging.texi index bb022e4516a..c08a382ef12 100644 --- a/doc/lispref/debugging.texi +++ b/doc/lispref/debugging.texi @@ -922,48 +922,61 @@ be cleaner to combine them. @cindex measuring resource usage @cindex memory usage -If your program is working correctly, but you want to make it run more -quickly or efficiently, the first thing to do is @dfn{profile} your -code so that you know how it is using resources. If you find that one -particular function is responsible for a significant portion of the -runtime, you can start looking for ways to optimize that piece. +If your program is working correctly, but not fast enough, and you +want to make it run more quickly or efficiently, the first thing to do +is @dfn{profile} your code so that you know where it spends most of +the execution time. If you find that one particular function is +responsible for a significant portion of the execution time, you can +start looking for ways to optimize that piece. Emacs has built-in support for this. To begin profiling, type @kbd{M-x profiler-start}. You can choose to profile by processor -usage, memory usage, or both. After doing some work, type -@kbd{M-x profiler-report} to display a summary buffer for each -resource that you chose to profile. The names of the report buffers -include the times at which the reports were generated, so you can -generate another report later on without erasing previous results. -When you have finished profiling, type @kbd{M-x profiler-stop} (there -is a small overhead associated with profiling). +usage, memory usage, or both. Then run the code you'd like to speed +up. After that, type @kbd{M-x profiler-report} to display a summary +buffer for each resource (cpu and memory) that you chose to profile. +The names of the report buffers include the times at which the reports +were generated, so you can generate another report later on without +erasing previous results. When you have finished profiling, type +@kbd{M-x profiler-stop} (there is a small overhead associated with +profiling, so we don't recommend leaving it active except when you are +actually running the code you want to examine). The profiler report buffer shows, on each line, a function that was -called, followed by how much resource (processor or memory) it used in -absolute and percentage times since profiling started. If a given +called, followed by how much resources (cpu or memory) it used in +absolute and percentage terms since profiling started. If a given line has a @samp{+} symbol at the left-hand side, you can expand that line by typing @kbd{@key{RET}}, in order to see the function(s) called by the higher-level function. Use a prefix argument (@kbd{C-u @key{RET}}) to see the whole call tree below a function. Pressing @kbd{@key{RET}} again will collapse back to the original state. -Press @kbd{j} or @kbd{mouse-2} to jump to the definition of a function. -Press @kbd{d} to view a function's documentation. -You can save a profile to a file using @kbd{C-x C-w}. -You can compare two profiles using @kbd{=}. +Press @kbd{j} or @kbd{mouse-2} to jump to the definition of a function +at point. Press @kbd{d} to view a function's documentation. You can +save a profile to a file using @kbd{C-x C-w}. You can compare two +profiles using @kbd{=}. @c FIXME reversed calltree? @cindex @file{elp.el} @cindex timing programs -The @file{elp} library offers an alternative approach. See the file -@file{elp.el} for instructions. +The @file{elp} library offers an alternative approach, which is useful +when you know in advance which Lisp function(s) you want to profile. +Using that library, you begin by setting @code{elp-function-list} to +the list of function symbols---those are the functions you want to +profile. Then type @w{@kbd{M-x elp-instrument-list @key{RET} nil +@key{RET}}} to arrange for profiling those functions. After running +the code you want to profile, invoke @w{@kbd{M-x elp-results}} to +display the current results. See the file @file{elp.el} for more +detailed instructions. This approach is limited to profiling +functions written in Lisp, it cannot profile Emacs primitives. @cindex @file{benchmark.el} @cindex benchmarking -You can check the speed of individual Emacs Lisp forms using the -@file{benchmark} library. See the functions @code{benchmark-run} and -@code{benchmark-run-compiled} in @file{benchmark.el}. +You can measure the time it takes to evaluate individual Emacs Lisp +forms using the @file{benchmark} library. See the macros +@code{benchmark-run} and @code{benchmark-run-compiled} in +@file{benchmark.el}. You can also use the @code{benchmark} command +for timing forms interactively. @c Not worth putting in the printed manual. @ifnottex diff --git a/lisp/emacs-lisp/benchmark.el b/lisp/emacs-lisp/benchmark.el index 589e76eaec0..d74446c7479 100644 --- a/lisp/emacs-lisp/benchmark.el +++ b/lisp/emacs-lisp/benchmark.el @@ -98,7 +98,8 @@ result. The overhead of the `lambda's is accounted for." ;;;###autoload (defun benchmark (repetitions form) "Print the time taken for REPETITIONS executions of FORM. -Interactively, REPETITIONS is taken from the prefix arg. +Interactively, REPETITIONS is taken from the prefix arg, and +the command prompts for the form to benchmark. For non-interactive use see also `benchmark-run' and `benchmark-run-compiled'." (interactive "p\nxForm: ") diff --git a/lisp/emacs-lisp/elp.el b/lisp/emacs-lisp/elp.el index dab17fd75b6..954e7aa73ae 100644 --- a/lisp/emacs-lisp/elp.el +++ b/lisp/emacs-lisp/elp.el @@ -278,8 +278,9 @@ Argument FUNSYM is the symbol of a defined function." (defun elp-instrument-list (&optional list) "Instrument, for profiling, all functions in `elp-function-list'. Use optional LIST if provided instead. -If called interactively, read LIST using the minibuffer." - (interactive "PList of functions to instrument: ") ;FIXME: Doesn't work?! +If called interactively, prompt for LIST in the minibuffer; +type \"nil\" to use `elp-function-list'." + (interactive "xList of functions to instrument: ") (unless (listp list) (signal 'wrong-type-argument (list 'listp list))) (mapcar #'elp-instrument-function (or list elp-function-list))) -- 2.39.2