doc/timevar.texi

   1 @node Profiling of program phases
   2 @section Profiling of program phases
   3
   4 @mindex timevar
   5 The module @samp{timevar} provides a simple self-profiling facility,
   6 based on timers.
   7
   8 @smallexample
   9 Execution times (seconds)
  10 read                  :   0.09 (19%) usr   0.08 (80%) sys   0.09 (18%) wall
  11 read: scan            :   0.04 ( 9%) usr   0.08 (80%) sys   0.12 (26%) wall
  12 read: parse           :   0.05 (10%) usr   0.00 ( 0%) sys   0.05 (10%) wall
  13 work                  :   0.33 (70%) usr   0.00 ( 0%) sys   0.35 (71%) wall
  14 work: phase 1         :   0.30 (64%) usr   0.00 ( 0%) sys   0.30 (64%) wall
  15 work: phase 2         :   0.13 (28%) usr   0.00 ( 0%) sys   0.14 (29%) wall
  16 output                :   0.04 ( 9%) usr   0.02 (20%) sys   0.04 ( 8%) wall
  17 total time            :   0.47             0.10             0.49
  18 @end smallexample
  19
  20 To set up @code{timevar}, copy the stub file
  21 @file{gnulib/lib/timevar.def} next to where @file{timevar.h} and
  22 @file{timevar.c} were imported in your project, and define your timers
  23 there.  For instance:
  24
  25 @smallexample
  26 /* The total execution time.  Mandatory.  */
  27 DEFTIMEVAR (tv_total,      "total time")
  28
  29 /* Examples.  */
  30 DEFTIMEVAR (tv_read,       "read")
  31 DEFTIMEVAR (tv_work,       "work")
  32 DEFTIMEVAR (tv_work_1,     "work: phase 1")
  33 DEFTIMEVAR (tv_work_2,     "work: phase 2")
  34 DEFTIMEVAR (tv_output,     "output")
  35 @end smallexample
  36
  37 Do not remove @code{tv_total}, it is mandatory.  You may change its
  38 associated string.
  39
  40 @sp 1
  41
  42 Use @code{timevar_push}/@code{timevar_pop} to start/stop timers, as in
  43 the following example.
  44
  45 @smallexample
  46 #include <config.h>
  47 #include "timevar.h"
  48
  49 #include <stdio.h>
  50 #include "read.h"
  51 #include "work.h"
  52 #include "output.h"
  53
  54 int
  55 main (void)
  56 @{
  57   timevar_enabled = true;
  58   timevar_init ();
  59   timevar_start (tv_total);
  60
  61   timevar_push (tv_read);
  62   reader ();
  63   timevar_pop (tv_read);
  64
  65   timevar_push (tv_work);
  66   work ();
  67   timevar_pop (tv_work);
  68
  69   timevar_push (tv_output);
  70   output ();
  71   timevar_pop (tv_output);
  72
  73   timevar_stop (tv_total);
  74   timevar_print (stderr);
  75 @}
  76 @end smallexample
  77
  78 @noindent
  79 with, for instance, in @file{work.c}
  80
  81 @smallexample
  82 #include <config.h>
  83 #include "work.h"
  84
  85 void
  86 work (void)
  87 @{
  88   timevar_push (tv_work_phase1);
  89   work1 ();
  90   timevar_pop (tv_work_phase1);
  91
  92   timevar_push (tv_work_phase2);
  93   work2 ();
  94   timevar_pop (tv_work_phase2);
  95 @}
  96 @end smallexample