gnulib: lib/timevar.h annotate

annotate lib/timevar.h @ 39871:08db1aa192ec

timevar: Small tweaks. * lib/timevar.h: Fix comments. Add parameter names to function declarations. * lib/timevar.c: Include timevar.h immediately after config.h. * lib/timevar.def: Fix comments. * modules/timevar (Maintainer): List Akim Demaille.

author	Bruno Haible <bruno@clisp.org>
date	Sun, 30 Sep 2018 19:36:29 +0200
parents	f315e5e30ddd
children	13eae48fd484

rev	line source
39871 08db1aa192ec timevar: Small tweaks. Bruno Haible <bruno@clisp.org> parents: 39869 diff changeset	1 /* Timing variables for measuring application performance.
39869 f315e5e30ddd timevar: import from Bison. Akim Demaille <akim.demaille@gmail.com> parents: diff changeset	2
f315e5e30ddd timevar: import from Bison. Akim Demaille <akim.demaille@gmail.com> parents: diff changeset	3 Copyright (C) 2000, 2002, 2004, 2009-2015, 2018 Free Software
f315e5e30ddd timevar: import from Bison. Akim Demaille <akim.demaille@gmail.com> parents: diff changeset	4 Foundation, Inc.
f315e5e30ddd timevar: import from Bison. Akim Demaille <akim.demaille@gmail.com> parents: diff changeset	5
f315e5e30ddd timevar: import from Bison. Akim Demaille <akim.demaille@gmail.com> parents: diff changeset	6 Contributed by Alex Samuel <samuel@codesourcery.com>
f315e5e30ddd timevar: import from Bison. Akim Demaille <akim.demaille@gmail.com> parents: diff changeset	7
f315e5e30ddd timevar: import from Bison. Akim Demaille <akim.demaille@gmail.com> parents: diff changeset	8 This program is free software: you can redistribute it and/or modify
f315e5e30ddd timevar: import from Bison. Akim Demaille <akim.demaille@gmail.com> parents: diff changeset	9 it under the terms of the GNU General Public License as published by
f315e5e30ddd timevar: import from Bison. Akim Demaille <akim.demaille@gmail.com> parents: diff changeset	10 the Free Software Foundation, either version 3 of the License, or
f315e5e30ddd timevar: import from Bison. Akim Demaille <akim.demaille@gmail.com> parents: diff changeset	11 (at your option) any later version.
f315e5e30ddd timevar: import from Bison. Akim Demaille <akim.demaille@gmail.com> parents: diff changeset	12
f315e5e30ddd timevar: import from Bison. Akim Demaille <akim.demaille@gmail.com> parents: diff changeset	13 This program is distributed in the hope that it will be useful,
f315e5e30ddd timevar: import from Bison. Akim Demaille <akim.demaille@gmail.com> parents: diff changeset	14 but WITHOUT ANY WARRANTY; without even the implied warranty of
f315e5e30ddd timevar: import from Bison. Akim Demaille <akim.demaille@gmail.com> parents: diff changeset	15 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
f315e5e30ddd timevar: import from Bison. Akim Demaille <akim.demaille@gmail.com> parents: diff changeset	16 GNU General Public License for more details.
f315e5e30ddd timevar: import from Bison. Akim Demaille <akim.demaille@gmail.com> parents: diff changeset	17
f315e5e30ddd timevar: import from Bison. Akim Demaille <akim.demaille@gmail.com> parents: diff changeset	18 You should have received a copy of the GNU General Public License
f315e5e30ddd timevar: import from Bison. Akim Demaille <akim.demaille@gmail.com> parents: diff changeset	19 along with this program. If not, see <http://www.gnu.org/licenses/>. */
f315e5e30ddd timevar: import from Bison. Akim Demaille <akim.demaille@gmail.com> parents: diff changeset	20
f315e5e30ddd timevar: import from Bison. Akim Demaille <akim.demaille@gmail.com> parents: diff changeset	21 #ifndef _TIMEVAR_H
f315e5e30ddd timevar: import from Bison. Akim Demaille <akim.demaille@gmail.com> parents: diff changeset	22 #define _TIMEVAR_H
f315e5e30ddd timevar: import from Bison. Akim Demaille <akim.demaille@gmail.com> parents: diff changeset	23
f315e5e30ddd timevar: import from Bison. Akim Demaille <akim.demaille@gmail.com> parents: diff changeset	24 /* Timing variables are used to measure elapsed time in various
39871 08db1aa192ec timevar: Small tweaks. Bruno Haible <bruno@clisp.org> parents: 39869 diff changeset	25 portions of the application. Each measures elapsed user, system, and
39869 f315e5e30ddd timevar: import from Bison. Akim Demaille <akim.demaille@gmail.com> parents: diff changeset	26 wall-clock time, as appropriate to and supported by the host
f315e5e30ddd timevar: import from Bison. Akim Demaille <akim.demaille@gmail.com> parents: diff changeset	27 system.
f315e5e30ddd timevar: import from Bison. Akim Demaille <akim.demaille@gmail.com> parents: diff changeset	28
f315e5e30ddd timevar: import from Bison. Akim Demaille <akim.demaille@gmail.com> parents: diff changeset	29 Timing variables are defined using the DEFTIMEVAR macro in
f315e5e30ddd timevar: import from Bison. Akim Demaille <akim.demaille@gmail.com> parents: diff changeset	30 timevar.def. Each has an enumeral identifier, used when referring
f315e5e30ddd timevar: import from Bison. Akim Demaille <akim.demaille@gmail.com> parents: diff changeset	31 to the timing variable in code, and a character string name.
f315e5e30ddd timevar: import from Bison. Akim Demaille <akim.demaille@gmail.com> parents: diff changeset	32
f315e5e30ddd timevar: import from Bison. Akim Demaille <akim.demaille@gmail.com> parents: diff changeset	33 Timing variables can be used in two ways:
f315e5e30ddd timevar: import from Bison. Akim Demaille <akim.demaille@gmail.com> parents: diff changeset	34
f315e5e30ddd timevar: import from Bison. Akim Demaille <akim.demaille@gmail.com> parents: diff changeset	35 - On the timing stack, using timevar_push and timevar_pop.
f315e5e30ddd timevar: import from Bison. Akim Demaille <akim.demaille@gmail.com> parents: diff changeset	36 Timing variables may be pushed onto the stack; elapsed time is
f315e5e30ddd timevar: import from Bison. Akim Demaille <akim.demaille@gmail.com> parents: diff changeset	37 attributed to the topmost timing variable on the stack. When
f315e5e30ddd timevar: import from Bison. Akim Demaille <akim.demaille@gmail.com> parents: diff changeset	38 another variable is pushed on, the previous topmost variable is
f315e5e30ddd timevar: import from Bison. Akim Demaille <akim.demaille@gmail.com> parents: diff changeset	39 'paused' until the pushed variable is popped back off.
f315e5e30ddd timevar: import from Bison. Akim Demaille <akim.demaille@gmail.com> parents: diff changeset	40
f315e5e30ddd timevar: import from Bison. Akim Demaille <akim.demaille@gmail.com> parents: diff changeset	41 - As a standalone timer, using timevar_start and timevar_stop.
f315e5e30ddd timevar: import from Bison. Akim Demaille <akim.demaille@gmail.com> parents: diff changeset	42 All time elapsed between the two calls is attributed to the
f315e5e30ddd timevar: import from Bison. Akim Demaille <akim.demaille@gmail.com> parents: diff changeset	43 variable.
f315e5e30ddd timevar: import from Bison. Akim Demaille <akim.demaille@gmail.com> parents: diff changeset	44 */
f315e5e30ddd timevar: import from Bison. Akim Demaille <akim.demaille@gmail.com> parents: diff changeset	45
f315e5e30ddd timevar: import from Bison. Akim Demaille <akim.demaille@gmail.com> parents: diff changeset	46 /* This structure stores the various varieties of time that can be
f315e5e30ddd timevar: import from Bison. Akim Demaille <akim.demaille@gmail.com> parents: diff changeset	47 measured. Times are stored in seconds. The time may be an
f315e5e30ddd timevar: import from Bison. Akim Demaille <akim.demaille@gmail.com> parents: diff changeset	48 absolute time or a time difference; in the former case, the time
f315e5e30ddd timevar: import from Bison. Akim Demaille <akim.demaille@gmail.com> parents: diff changeset	49 base is undefined, except that the difference between two times
f315e5e30ddd timevar: import from Bison. Akim Demaille <akim.demaille@gmail.com> parents: diff changeset	50 produces a valid time difference. */
f315e5e30ddd timevar: import from Bison. Akim Demaille <akim.demaille@gmail.com> parents: diff changeset	51
f315e5e30ddd timevar: import from Bison. Akim Demaille <akim.demaille@gmail.com> parents: diff changeset	52 struct timevar_time_def
f315e5e30ddd timevar: import from Bison. Akim Demaille <akim.demaille@gmail.com> parents: diff changeset	53 {
f315e5e30ddd timevar: import from Bison. Akim Demaille <akim.demaille@gmail.com> parents: diff changeset	54 /* User time in this process. */
f315e5e30ddd timevar: import from Bison. Akim Demaille <akim.demaille@gmail.com> parents: diff changeset	55 float user;
f315e5e30ddd timevar: import from Bison. Akim Demaille <akim.demaille@gmail.com> parents: diff changeset	56
f315e5e30ddd timevar: import from Bison. Akim Demaille <akim.demaille@gmail.com> parents: diff changeset	57 /* System time (if applicable for this host platform) in this
f315e5e30ddd timevar: import from Bison. Akim Demaille <akim.demaille@gmail.com> parents: diff changeset	58 process. */
f315e5e30ddd timevar: import from Bison. Akim Demaille <akim.demaille@gmail.com> parents: diff changeset	59 float sys;
f315e5e30ddd timevar: import from Bison. Akim Demaille <akim.demaille@gmail.com> parents: diff changeset	60
f315e5e30ddd timevar: import from Bison. Akim Demaille <akim.demaille@gmail.com> parents: diff changeset	61 /* Wall clock time. */
f315e5e30ddd timevar: import from Bison. Akim Demaille <akim.demaille@gmail.com> parents: diff changeset	62 float wall;
f315e5e30ddd timevar: import from Bison. Akim Demaille <akim.demaille@gmail.com> parents: diff changeset	63 };
f315e5e30ddd timevar: import from Bison. Akim Demaille <akim.demaille@gmail.com> parents: diff changeset	64
f315e5e30ddd timevar: import from Bison. Akim Demaille <akim.demaille@gmail.com> parents: diff changeset	65 /* An enumeration of timing variable identifiers. Constructed from
f315e5e30ddd timevar: import from Bison. Akim Demaille <akim.demaille@gmail.com> parents: diff changeset	66 the contents of timevar.def. */
f315e5e30ddd timevar: import from Bison. Akim Demaille <akim.demaille@gmail.com> parents: diff changeset	67
f315e5e30ddd timevar: import from Bison. Akim Demaille <akim.demaille@gmail.com> parents: diff changeset	68 #define DEFTIMEVAR(identifier__, name__) \
f315e5e30ddd timevar: import from Bison. Akim Demaille <akim.demaille@gmail.com> parents: diff changeset	69 identifier__,
f315e5e30ddd timevar: import from Bison. Akim Demaille <akim.demaille@gmail.com> parents: diff changeset	70 typedef enum
f315e5e30ddd timevar: import from Bison. Akim Demaille <akim.demaille@gmail.com> parents: diff changeset	71 {
f315e5e30ddd timevar: import from Bison. Akim Demaille <akim.demaille@gmail.com> parents: diff changeset	72 #include "timevar.def"
f315e5e30ddd timevar: import from Bison. Akim Demaille <akim.demaille@gmail.com> parents: diff changeset	73 TIMEVAR_LAST
f315e5e30ddd timevar: import from Bison. Akim Demaille <akim.demaille@gmail.com> parents: diff changeset	74 }
f315e5e30ddd timevar: import from Bison. Akim Demaille <akim.demaille@gmail.com> parents: diff changeset	75 timevar_id_t;
f315e5e30ddd timevar: import from Bison. Akim Demaille <akim.demaille@gmail.com> parents: diff changeset	76 #undef DEFTIMEVAR
f315e5e30ddd timevar: import from Bison. Akim Demaille <akim.demaille@gmail.com> parents: diff changeset	77
f315e5e30ddd timevar: import from Bison. Akim Demaille <akim.demaille@gmail.com> parents: diff changeset	78 /* Initialize timing variables. */
f315e5e30ddd timevar: import from Bison. Akim Demaille <akim.demaille@gmail.com> parents: diff changeset	79
f315e5e30ddd timevar: import from Bison. Akim Demaille <akim.demaille@gmail.com> parents: diff changeset	80 void timevar_init (void);
f315e5e30ddd timevar: import from Bison. Akim Demaille <akim.demaille@gmail.com> parents: diff changeset	81
f315e5e30ddd timevar: import from Bison. Akim Demaille <akim.demaille@gmail.com> parents: diff changeset	82 /* Push TIMEVAR onto the timing stack. No further elapsed time is
f315e5e30ddd timevar: import from Bison. Akim Demaille <akim.demaille@gmail.com> parents: diff changeset	83 attributed to the previous topmost timing variable on the stack;
f315e5e30ddd timevar: import from Bison. Akim Demaille <akim.demaille@gmail.com> parents: diff changeset	84 subsequent elapsed time is attributed to TIMEVAR, until it is
f315e5e30ddd timevar: import from Bison. Akim Demaille <akim.demaille@gmail.com> parents: diff changeset	85 popped or another element is pushed on top.
f315e5e30ddd timevar: import from Bison. Akim Demaille <akim.demaille@gmail.com> parents: diff changeset	86
f315e5e30ddd timevar: import from Bison. Akim Demaille <akim.demaille@gmail.com> parents: diff changeset	87 TIMEVAR cannot be running as a standalone timer. */
f315e5e30ddd timevar: import from Bison. Akim Demaille <akim.demaille@gmail.com> parents: diff changeset	88
39871 08db1aa192ec timevar: Small tweaks. Bruno Haible <bruno@clisp.org> parents: 39869 diff changeset	89 void timevar_push (timevar_id_t timevar);
39869 f315e5e30ddd timevar: import from Bison. Akim Demaille <akim.demaille@gmail.com> parents: diff changeset	90
f315e5e30ddd timevar: import from Bison. Akim Demaille <akim.demaille@gmail.com> parents: diff changeset	91 /* Pop the topmost timing variable element off the timing stack. The
f315e5e30ddd timevar: import from Bison. Akim Demaille <akim.demaille@gmail.com> parents: diff changeset	92 popped variable must be TIMEVAR. Elapsed time since the that
f315e5e30ddd timevar: import from Bison. Akim Demaille <akim.demaille@gmail.com> parents: diff changeset	93 element was pushed on, or since it was last exposed on top of the
f315e5e30ddd timevar: import from Bison. Akim Demaille <akim.demaille@gmail.com> parents: diff changeset	94 stack when the element above it was popped off, is credited to that
f315e5e30ddd timevar: import from Bison. Akim Demaille <akim.demaille@gmail.com> parents: diff changeset	95 timing variable. */
f315e5e30ddd timevar: import from Bison. Akim Demaille <akim.demaille@gmail.com> parents: diff changeset	96
39871 08db1aa192ec timevar: Small tweaks. Bruno Haible <bruno@clisp.org> parents: 39869 diff changeset	97 void timevar_pop (timevar_id_t timevar);
39869 f315e5e30ddd timevar: import from Bison. Akim Demaille <akim.demaille@gmail.com> parents: diff changeset	98
f315e5e30ddd timevar: import from Bison. Akim Demaille <akim.demaille@gmail.com> parents: diff changeset	99 /* Start timing TIMEVAR independently of the timing stack. Elapsed
f315e5e30ddd timevar: import from Bison. Akim Demaille <akim.demaille@gmail.com> parents: diff changeset	100 time until timevar_stop is called for the same timing variable is
f315e5e30ddd timevar: import from Bison. Akim Demaille <akim.demaille@gmail.com> parents: diff changeset	101 attributed to TIMEVAR. */
f315e5e30ddd timevar: import from Bison. Akim Demaille <akim.demaille@gmail.com> parents: diff changeset	102
39871 08db1aa192ec timevar: Small tweaks. Bruno Haible <bruno@clisp.org> parents: 39869 diff changeset	103 void timevar_start (timevar_id_t timevar);
39869 f315e5e30ddd timevar: import from Bison. Akim Demaille <akim.demaille@gmail.com> parents: diff changeset	104
f315e5e30ddd timevar: import from Bison. Akim Demaille <akim.demaille@gmail.com> parents: diff changeset	105 /* Stop timing TIMEVAR. Time elapsed since timevar_start was called
f315e5e30ddd timevar: import from Bison. Akim Demaille <akim.demaille@gmail.com> parents: diff changeset	106 is attributed to it. */
f315e5e30ddd timevar: import from Bison. Akim Demaille <akim.demaille@gmail.com> parents: diff changeset	107
39871 08db1aa192ec timevar: Small tweaks. Bruno Haible <bruno@clisp.org> parents: 39869 diff changeset	108 void timevar_stop (timevar_id_t timevar);
08db1aa192ec timevar: Small tweaks. Bruno Haible <bruno@clisp.org> parents: 39869 diff changeset	109
39869 f315e5e30ddd timevar: import from Bison. Akim Demaille <akim.demaille@gmail.com> parents: diff changeset	110 /* Fill the elapsed time for TIMEVAR into ELAPSED. Returns
f315e5e30ddd timevar: import from Bison. Akim Demaille <akim.demaille@gmail.com> parents: diff changeset	111 update-to-date information even if TIMEVAR is currently running. */
f315e5e30ddd timevar: import from Bison. Akim Demaille <akim.demaille@gmail.com> parents: diff changeset	112
39871 08db1aa192ec timevar: Small tweaks. Bruno Haible <bruno@clisp.org> parents: 39869 diff changeset	113 void timevar_get (timevar_id_t timevar, struct timevar_time_def *elapsed);
39869 f315e5e30ddd timevar: import from Bison. Akim Demaille <akim.demaille@gmail.com> parents: diff changeset	114
f315e5e30ddd timevar: import from Bison. Akim Demaille <akim.demaille@gmail.com> parents: diff changeset	115 /* Summarize timing variables to FP. The timing variable TV_TOTAL has
f315e5e30ddd timevar: import from Bison. Akim Demaille <akim.demaille@gmail.com> parents: diff changeset	116 a special meaning -- it's considered to be the total elapsed time,
f315e5e30ddd timevar: import from Bison. Akim Demaille <akim.demaille@gmail.com> parents: diff changeset	117 for normalizing the others, and is displayed last. */
f315e5e30ddd timevar: import from Bison. Akim Demaille <akim.demaille@gmail.com> parents: diff changeset	118
39871 08db1aa192ec timevar: Small tweaks. Bruno Haible <bruno@clisp.org> parents: 39869 diff changeset	119 void timevar_print (FILE *fp);
39869 f315e5e30ddd timevar: import from Bison. Akim Demaille <akim.demaille@gmail.com> parents: diff changeset	120
f315e5e30ddd timevar: import from Bison. Akim Demaille <akim.demaille@gmail.com> parents: diff changeset	121 /* Set to to nonzero to enable timing variables. */
f315e5e30ddd timevar: import from Bison. Akim Demaille <akim.demaille@gmail.com> parents: diff changeset	122 extern int timevar_enabled;
f315e5e30ddd timevar: import from Bison. Akim Demaille <akim.demaille@gmail.com> parents: diff changeset	123
f315e5e30ddd timevar: import from Bison. Akim Demaille <akim.demaille@gmail.com> parents: diff changeset	124 #endif /* ! _TIMEVAR_H */

Mercurial > gnulib

annotate lib/timevar.h @ 39871:08db1aa192ec