HELP TIME                                         Aaron Sloman, Dec 1982
HELP GCTIME                             Revised: John Williams, Dec 1995

    time command;
    time * number command;

The syntax construct time repeatedly executes the given command and
prints the CPU time and garbage collector time (in seconds) spent in
executing command. It is terminated by interrupting with <CTRL-C>. The
times displayed refer to the amount of time spent within Poplog: they do
not refer to "real" time and are not affected by any other processes
running on your machine.

Before using time, you must first load it with:

    uses time;


-----------------------------------------------------------------------
1  An Example
-----------------------------------------------------------------------

For this example, we define a procedure which makes a list of n
instances of a given item:

    define procedure list_of(item, n);
        lvars item, n;
        [% repeat n times
            item
        endrepeat %]
    enddefine;

Now we check that it works:

    list_of("hello", 4)=>
    ** [hello hello hello hello]

And now we time how long it takes to create lists of length 30000:

    time list_of("hello", 30000) ->;
    CPU TIME: 0.11  GC TIME: 0.0
    CPU TIME: 0.15  GC TIME: 0.0
    CPU TIME: 0.48  GC TIME: 0.31
    CPU TIME: 0.08  GC TIME: 0.0
    CPU TIME: 0.09  GC TIME: 0.0
    CPU TIME: 0.11  GC TIME: 0.0
    CPU TIME: 0.32  GC TIME: 0.21
    CPU TIME: 0.12  GC TIME: 0.0
    <CTRL-C>

Note that time measures times in seconds.


1.1  The * number option
------------------------

If the time taken to execute a particular command is very small, use
the * number option to get more substantial timings. This simply
executes the command number times. For example:

    define third(list);
        lvars list;
        hd(tl(tl(list)))
    enddefine;

    vars list = [1 2 3 4];

    time third(list) ->;
    CPU TIME: 0.0   GC TIME: 0.0
    CPU TIME: 0.0   GC TIME: 0.0
    CPU TIME: 0.0   GC TIME: 0.0
    <CTRL-C>

    time * 50000 third(list) ->;
    CPU TIME: 0.25  GC TIME: 0.0
    CPU TIME: 0.25  GC TIME: 0.0
    CPU TIME: 0.25  GC TIME: 0.0
    <CTRL-C>


-----------------------------------------------------------------------
2  The gctime command
-----------------------------------------------------------------------

gctime is a similar construct, made available by the command:

    uses gctime;

The only difference is that in this case popgctrace is made true while
the command is being obeyed and therefore information about garbage
collections will be printed out as well.


-----------------------------------------------------------------------
3  See Also
-----------------------------------------------------------------------

HELP * SYSTIME    - Returns the CPU time of the current Poplog session.

HELP * TIMEDIFF   - Returns the CPU time since its previous use.

HELP * POPGCTIME  - The CPU time spent in automatic garbage collections.

HELP * POPGCTRACE - Controls the tracing of garbage collections.

HELP * PROFILE    - For finding which procedures take up the most time
                    when running a program.

REF * TIMES       - Details of Pop-11 timing procedures.


--- C.all/help/time
--- Copyright University of Sussex 1995. All rights reserved.