timer.hh File Reference

Timing nested tasks. More...

Include dependency graph for timer.hh:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes

class  ScopedTimer
 Allow the timing of a task within a scope. More...


Detailed Description

Timing nested tasks.

The purpose of the class Timer provided here is to measure the time user-defined tasks use in the execution of a program.

Each task is identified by a unique name (std::string), or alternatively, once task has been declared, by an id number. Special characters in task names must be escaped for the XML export to work properly.

The program source code must be equipped with calls to methods of the Timer instance.

For the timing to be accurate, a task should take 1ms of execution time or more (preferably over 10ms).

Once all the relevant timing data are gathered, the Timer object builds a graph of the results (using the boost graph library), which can be printed to a stream or exported in DOT format. Alternatively, export of the complete results in XML format for further analysis will be made available.

How to use this timer in Vaucauson (taf-kit):

A global timer is declared in taf-kit/src/common.hh. See misc/global_timer.hh for a list of commands on the global timer (using macro definitions).

Refer to the description of the class's methods below.

The global timer is automatically started and stopped in taf-kit/tests/vcsn* programs. Only the source code of automata manipulation algorithm has to be equipped with declaration an execution of tasks (using TIMER_SCOPED(Task) alone or TIMER_PUSH(Task) and TIMER_POP() together).

To obtain a detailed report of the results on std::cerr, use the command-line option --report-time (results are not printed otherwise). This option takes an optional int argument as the verbose degree of the report (from 1 to 3, default 2)

To export the graph of the timing results in DOT format on std::cerr, use the command-line option --export-time-dot. This option takes an optional int argument as the verbose degree of the graph (from 0 to 3, default 2)

To dump the timer in XML format on std::cerr, use the command-line option --export-time-xml.

To benchmark several executions of the same set of tasks, use the command-line option --bench=X where X is the number of iterations. A summary of the results is printed on std::cerr.

How to use this timer outside Vaucanson:

There are two ways to refer to a given task:

There are two ways to time a task:

* Once stopped, standard arithmetic operators (+, +=, /, /=) can be used on timers, e.g. to calculate the mean of several iterations of the same program. The structure of timers added to each other must be strictly identical (same function calls). A Timer.join () method might appear in the future.

* In this report, task names can be truncated to fit the layout. See the description of the report's fields below.

Note on performance:

The data gathering process is generally non-obtrusive (timing one task by its id takes about 1 extra microsecond). However, for a large number of small tasks, using only full name lookup may impact the results.

Documentation for the standard report:

The report obtained using Timer.print () is 80 columns wide. Task names are truncated to fit. Times are reported in the most accurate unit (among hours, minutes, seconds, and milliseconds), except in the task list where the same unit is shared between all tasks' total and self times.

Task list:

Call graph (VERBOSE_NORMAL or higer):

Cycles:

Tasks: This section lists each task, as well as its incoming and outgoing calls. Incoming calls are listed above the task (D: <-), while outgoing calls are listed below (D: ->).

Note: Recursive calls are listed both in incoming and outgoing calls.

Detailed tasks (VERBOSE_MAXIMAL):

Each task is listed here with its gathered data.

Self time refers to the time spent in the task itself. Total time refers to the time spent in the task and its children.

All times are in clock ticks.

User time is the time spent in user code. System time is the time spent in system calls. Cpu time is the total time the cpu spent in the program. It is the value used in the previous parts of the report. Wall time is the real time spent in the task, i.e. the time observed by the user on a wall clock.

Definition in file timer.hh.


Generated on Mon May 4 08:42:28 2009 for Vaucanson by  doxygen 1.5.8