Timing A+ Functions


Time  time s, or time(), or time expression, or time{}

   Argument and Result
In the four expressions above, the argument is, respectively, explicitly one or more scalar symbols (not an expression whose value is a scalar symbol or vector of scalar symbols), the Null expressed as a pair of parentheses, some other expression, or absent. The result is a vector that is numeric, symbol, nested, or Null.
   Definition
The effect of time is to set or reset a timer, or to return the results of a timer. All timing information is expressed in milliseconds. In the descriptions that follow, system time refers to the cpu time spent in system calls made by the A+ processor, user time refers to the cpu time spent by the A+ processor directly, and elapsed time is clock time (you will notice it increasing even when you are doing nothing).

When you are timing any code whose execution time is even moderately short, you should use a dyadic do statement to execute the code many times, and take an average. Doing so mitigates any imprecision in the timing and allows for circumstances, like timeslicing, that can vary for the same code.

Timings will generally be different for the same code with different data, being affected by type, size, nesting, and so on. One method of accomplishing something may have a substantial fixed cost but be relatively insensitive to the size of the data, whereas another may have little fixed cost but a strong dependency on size. You should time the various cases that can be expected to arise, so that you can determine which method is best for your expected distribution of cases. It may turn out that you will want to include several methods and choose among them during execution.

time is not a true function, although it has function like attributes. Specifically, if time were a true function then the two expressions time{} and time() could not both be syntactically correct, because the former indicates that time is niladic and the latter monadic. However, both are valid A+ expressions. See the table "Timer Expressions and Their Meanings" for a description of all valid timer expressions. Although its name does not start with an underbar, time is always available, like a system function.

Timer Expressions and Their Meanings
ExpressionEffectResult
time expression Time the indicated A+ expression. 3-element numeric vector of user, system, elapsed time used to evaluate expression.
time s Set the timer for the functions named by the symbols in s. Any external and system functions named in s are ignored. If a function is redefined, the timer switches to the new definition. s, a vector of symbols. Including external or system functions in s may cause a bus error in some releases.
time{}    following    time s Return timer results. 2-element nested vector (s;matrix), explained below.
time{}    otherwise Return timer results. 3-element numeric vector of user, system, elapsed time since the current session began.
time () Reset the timer, i.e., undo the effect of time s. Null.

Result (s; matrix) of time s Explained
ExpressionMeaning
matrix[i+1;0] The number of times the function named in i#s was called.
matrix[i+1;1] Total user time spent in the function named in i#s exclusive of others being timed.
matrix[i+1;2] Total system time spent in the function named in i#s exclusive of others being timed.
matrix[i+1;3] Total elapsed time spent in the function named in i#s exclusive of others being timed.
matrix[0;0] 0 (meaningless - just filler).
matrix[0;1] User time spent outside all functions named in s.
matrix[0;2] System time spent outside all functions named in s.
matrix[0;3] Elapsed time spent outside all functions named in s.
+/matrix[;1] Total user time since time s was executed.
+/matrix[;2] Total system time since time s was executed.
+/matrix[;3] Total elapsed time since time s was executed.

   Examples

    f n:{n do 3;}                  Don't need to see explicit results.
    m g n:{m do f n;}
    time `f `g                     Set timers for f and g
    100 g 10                       Call g and, from g, call f
    1000 g 5                       Call g again.
    10000 do 2+3                   A call outside g
    time{}
<  `f `g
<     0  160    0 7080     160 ms user, 0 system, 7080 elapsed not in f or g
   1100  100  110  230     f: 1100 calls; 100 ms user, 110 system, 230 elapsed.
      2   90  130  250     g: 2 calls; 90 ms user, 130 system, 250 elapsed.

    time ()                        Clear timer.
    time{}
 500 580 20110       500 ms user, 580 system, 20,110 elapsed from the beginning.

    sf(`a`b`c`d`e`f`g`h`i `j `k `l `m `n;
        (1;2;3;4;5;6;7;8;9;10;11;12;13;14))
    s1000(0sf),`o    Includes an invalid index for the slotfiller just defined.

    time (j999) do r 0's[j]sf'
 810 100 920      Times for avoiding index errors by an  Protected Execute.

    time (j999) do r do s[j]sf
 170 70 240       Times for avoiding index errors by a do Protected Execute.

    time (j999) do r {i(0sf)s[j];if (i<#0sf) i1sf}
 300 0 310        Times for avoiding index errors by mimicking symbolic indexing.

doc@aplusdev.org© Copyright 1995–2008 Morgan Stanley Dean Witter & Co. All rights reserved.