Documention for: profile-timer.r
Created by: sunanda
on: 13-Oct-2004
Last updated by: sunanda on: 13-Jul-2005
Format: html
Downloaded on: 31-Mar-2020

1. Purpose
2. Similar scripts
3. Quick examples
3.1. Time a single event
3.2. Time Nested events
4. Usage
4.1. Refinements
4.2. Show timer
5. Limitations
  Version: 0.0.1 (corrects typos)
  10-Oct-2004
  Sunanda
 

1. Purpose

To help you find the elapse time for executing arbitrary stretches of code. Could help to track down slow parts that need tuning.

2. Similar scripts

The Library also contains:

A difference is that profile-timer.r lets you create multiple, named, timers.

3. Quick examples

3.1. Time a single event

   do %profile-timer.r                  ;; load the script
   profile-timer/start "an-event"       ;; start timing
   loop 10000 [99 * 99]                 ;; the code being timed
   profile-timer/stop "an-event"        ;; stop the timer

   probe profile-timer/show "an-event"  ;; display the timer

     make object! [
        event-id: "an-event"
        total-completed-events: 1
        total-time: 0:00:00.06
        current-event: none
    ]
 

As you can see, the loop took .06 seconds

3.2. Time Nested events

Each event you time has a unique name (supplied by you) so they can be started and stopped independently:

   profile-timer/start "whole program"
   loop 25 [
     profile-timer/start "loop"
     loop 10000 [99 * 99]
     profile-timer/stop "loop"
     ]
   profile-timer/stop "whole program"

   probe profile-timer/show "loop"
      make object! [
          event-id: "loop"
          total-completed-events: 25
          total-time: 0:00:00.22
          current-event: none
      ]

   probe profile-timer/show "whole program"
      make object! [
          event-id: "whole program"
          total-completed-events: 1
          total-time: 0:00:00.27
          current-event: none
 

Again, as you can see from the probes, event loop executed 25 times for a total execution time of 0.22 seconds. Event whole program executed just once for a total time of 0.27 seconds. That, of course, includes the time for the loop events.

4. Usage

   do %profile-timer.r       ;; to load the script

   profile-timer/xxxx   "event name"  ;; to time or display an event
 

4.1. Refinements

Refinement Meaning Example Notes
Start Start timing an event profile-timer/start "my timer" After you stop a timer, you can use start to start it again
Stop Stop timing a started event profile-timer/stop "my timer" A stopped timer can be started again
Show See the value of a timer profile-timer/show "my timer" See below for details of the timer object
Show-all See the value of all timers profile-timer/show-all "dummy string" See below for details of the timer object
Reset Zeroizes all timers profile-timer/reset "dummy string" Same as reDOing %profile-timer.r

4.2. Show timer

A timer object looks like this:
      make object! [
          event-id: "my timer"
          total-completed-events: 4
          total-time: 0:00:01.23
          current-event: none
      ]
  

5. Limitations

May not give accurate results if used across midnight.