Stata 15 help for mf_timer

Title

[M-5] timer() -- Profile code

Syntax

void timer_clear()

void timer_clear(real scalar t)

void timer_on(real scalar t)

void timer_off(real scalar t)

real rowvector timer_value(real scalar t)

void timer()

void timer(real t)

void timer(string scalar txt)

void timer(real t, string scalar txt)

void timer(string scalar txt, real t)

where t is a timer number, 1 through 100.

For timer(), zero, one, or two arguments are allowed, and arguments may be specified in any order. Argument t may be omitted, specified as a scalar, or specified as a vector:

If t is omitted, all timers are reported.

If t is a scalar, the specified timer is reported (timer(.) is the same as omitting t; all timers are reported).

If t is a rowvector, the specified timers are reported.

If t is a colvector, it must be 2 x 1, and the timers in the range are reported.

For timer_clear(), t may be omitted or specified as a scalar:

If t is omitted, all timers are cleared.

If t is a scalar, the specified timer is cleared unless t is specified as missing, in which case the result is the same as if t had been omitted; all timers are cleared.

In the other functions, t is a scalar and may not contain missing values.

Description

Stata provides a set of 100 timers, numbered from 1 to 100, for profiling code; see [P] timer. These functions provide an interface into those timers.

timer_clear() clears (resets to zero) all timers or the specified timer.

timer_on(t) turns on (restarts) timer t.

timer_off(t) turns off (stops) timer t.

timer_value(t) returns a 1 x 2 vector summarizing the contents of timer t. The first element is the cumulative time in seconds that the timer has been on, and the second element is the number of times the timer has been started and stopped.

timer() displays a timer report showing cumulative time, the number of times the timer has been started and stopped, and the average time (first divided by second). timer() allows two optional arguments: txt and t, and they may be specified in either order. txt, if specified, is used to title the report. t, if specified, specifies the timers to be reported. The default is to report all timers that have been turned on and off at least once.

Remarks

To obtain accurate timings, you must run whatever code you wish to profile more than once. In the example below, we run subroutine_to_be_timed() 100,000 times.

timer_clear() for (i=1; i<=100000; i++) { timer_on(1) subroutine_to_be_timed() timer_off(1) } timer()

subroutine_to_be_timed() might use other timers to profile parts of itself:

function subroutine_to_be_timed() { ... for ({txt...}) { ... timer_on(2) ... timer_off(2) }

...

timer_on(3) ... timer_off(3) }

The result of running this experiment, as reported by timer(), might be

---------------------------------------- timer report 1. 511.21 / 100000 = .0051121 2. 5.89 / 100000 = .0000589 3. 505.31 / 100000 = .0050531 ----------------------------------------

Each execution of subroutine_to_be_timed() requires 0.005 seconds, and the bulk of that time is spent in the second part of the code. No matter how inefficient you thought the first part of the code was, improving it will make little difference in the overall execution time.

Conformability

timer_clear(t): t: 1 x 1 (optional) result: void

timer_on(t), timer_off(t): t: 1 x 1 result: void

timer_value(t): t: 1 x 1 result: 1 x 2

timer(t,txt), timer(txt,t): txt: 1 x 1 (optional) t: 1 x 1, 1 x r, 2 x 1 (optional) result: void

Diagnostics

None.

Timer resolution varies across computers but is at least .01 seconds.

Source code

timer.mata; other functions are built in.


© Copyright 1996–2018 StataCorp LLC   |   Terms of use   |   Privacy   |   Contact us   |   What's new   |   Site index