From 5b776637e1facf949c9bc0db665db879c580e2f6 Mon Sep 17 00:00:00 2001 From: Glenn Morris Date: Tue, 20 Nov 2012 00:02:54 -0800 Subject: [PATCH] Make a start on a Profiling section in the lispref * doc/lispref/debugging.texi (Profiling): New section, in progress. * doc/lispref/tips.texi (Compilation Tips): Move profiling to separate section. * doc/lispref/elisp.texi: Add Profiling to detailed menu. --- doc/lispref/ChangeLog | 6 ++++++ doc/lispref/debugging.texi | 40 ++++++++++++++++++++++++++++++++++++++ doc/lispref/elisp.texi | 1 + doc/lispref/tips.texi | 14 ++----------- 4 files changed, 49 insertions(+), 12 deletions(-) diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog index bdf4ef13488..9d71d4b4420 100644 --- a/doc/lispref/ChangeLog +++ b/doc/lispref/ChangeLog @@ -1,3 +1,9 @@ +2012-11-20 Glenn Morris + + * debugging.texi (Profiling): New section, in progress. + * tips.texi (Compilation Tips): Move profiling to separate section. + * elisp.texi: Add Profiling to detailed menu. + 2012-11-18 Martin Rudalics * windows.texi (Display Action Functions): Fix recently added diff --git a/doc/lispref/debugging.texi b/doc/lispref/debugging.texi index 11532b19781..53d739f2295 100644 --- a/doc/lispref/debugging.texi +++ b/doc/lispref/debugging.texi @@ -43,6 +43,7 @@ function (@pxref{Terminal Output}). * Edebug:: A source-level Emacs Lisp debugger. * Syntax Errors:: How to find syntax errors. * Test Coverage:: Ensuring you have tested all branches in your code. +* Profiling:: Measuring the resources that your code uses. @end menu @node Debugger @@ -809,3 +810,42 @@ never return. If it ever does return, you get a run-time error. Edebug also has a coverage testing feature (@pxref{Coverage Testing}). These features partly duplicate each other, and it would be cleaner to combine them. + + +@node Profiling +@section Profiling +@cindex profiling +@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 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 by 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). + +@c FIXME +@c Basic apperance of the report buffer: + +@c The following commands are available in the report buffer: + +@cindex @file{elp.el} +@cindex timing programs +The @file{elp} library offers an alternative approach. See the file +@file{elp.el} for instructions. + +@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}. diff --git a/doc/lispref/elisp.texi b/doc/lispref/elisp.texi index a70558bf09f..cb00b5e9889 100644 --- a/doc/lispref/elisp.texi +++ b/doc/lispref/elisp.texi @@ -617,6 +617,7 @@ Debugging Lisp Programs * Edebug:: A source-level Emacs Lisp debugger. * Syntax Errors:: How to find syntax errors. * Test Coverage:: Ensuring you have tested all branches in your code. +* Profiling:: Measuring the resources that your code uses. The Lisp Debugger diff --git a/doc/lispref/tips.texi b/doc/lispref/tips.texi index 4336baa128f..bba416d5614 100644 --- a/doc/lispref/tips.texi +++ b/doc/lispref/tips.texi @@ -460,18 +460,8 @@ Lisp programs. @itemize @bullet @item -@cindex profiling -@cindex timing programs -@cindex @file{elp.el} -Profile your program with the @file{elp} library. See the file -@file{elp.el} for instructions. - -@item -@cindex @file{benchmark.el} -@cindex benchmarking -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}. +Profile your program, to find out where the time is being spent. +@xref{Profiling}. @item Use iteration rather than recursion whenever possible. -- 2.39.2