doc/timevar.texi

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