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