[Emacs-diffs] /srv/bzr/emacs/emacs-24 r110920: Make a start on a Profiling section in the lispref

[Glenn Morris]

------------------------------------------------------------
revno: 110920
committer: Glenn Morris <address@hidden>
branch nick: emacs-24
timestamp: Tue 2012-11-20 00:02:54 -0800
message:
  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.
modified:
  doc/lispref/ChangeLog
  doc/lispref/debugging.texi
  doc/lispref/elisp.texi
  doc/lispref/tips.texi

=== modified file 'doc/lispref/ChangeLog'
--- a/doc/lispref/ChangeLog     2012-11-18 11:34:36 +0000
+++ b/doc/lispref/ChangeLog     2012-11-20 08:02:54 +0000
@@ -1,3 +1,9 @@
+2012-11-20  Glenn Morris  <address@hidden>
+
+       * 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  <address@hidden>
 
        * windows.texi (Display Action Functions): Fix recently added

=== modified file 'doc/lispref/debugging.texi'
--- a/doc/lispref/debugging.texi        2012-11-11 01:16:25 +0000
+++ b/doc/lispref/debugging.texi        2012-11-20 08:02:54 +0000
@@ -43,6 +43,7 @@
 * 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 @@
   Edebug also has a coverage testing feature (@pxref{Coverage
 Testing}).  These features partly duplicate each other, and it would
 be cleaner to combine them.
+
+
address@hidden Profiling
address@hidden Profiling
address@hidden profiling
address@hidden measuring resource usage
address@hidden 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
address@hidden profiler-start}.  You can choose to profile by processor
+usage, memory usage, or both.  After doing some work, type
address@hidden 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).
+
address@hidden FIXME
address@hidden Basic apperance of the report buffer:
+
address@hidden The following commands are available in the report buffer:
+
address@hidden @file{elp.el}
address@hidden timing programs
+The @file{elp} library offers an alternative approach.  See the file
address@hidden for instructions.
+
address@hidden @file{benchmark.el}
address@hidden benchmarking
+You can check the speed of individual Emacs Lisp forms using the
address@hidden library.  See the functions @code{benchmark-run} and
address@hidden in @file{benchmark.el}.

=== modified file 'doc/lispref/elisp.texi'
--- a/doc/lispref/elisp.texi    2012-11-07 09:41:52 +0000
+++ b/doc/lispref/elisp.texi    2012-11-20 08:02:54 +0000
@@ -617,6 +617,7 @@
 * 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
 

=== modified file 'doc/lispref/tips.texi'
--- a/doc/lispref/tips.texi     2012-10-22 02:18:58 +0000
+++ b/doc/lispref/tips.texi     2012-11-20 08:02:54 +0000
@@ -460,18 +460,8 @@
 
 @itemize @bullet
 @item
address@hidden profiling
address@hidden timing programs
address@hidden @file{elp.el}
-Profile your program with the @file{elp} library.  See the file
address@hidden for instructions.
-
address@hidden
address@hidden @file{benchmark.el}
address@hidden benchmarking
-Check the speed of individual Emacs Lisp forms using the
address@hidden library.  See the functions @code{benchmark-run} and
address@hidden in @file{benchmark.el}.
+Profile your program, to find out where the time is being spent.
address@hidden
 
 @item
 Use iteration rather than recursion whenever possible.