Documentation for: profile-timer.r

  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:

• profiler.r 
• timeit.r 

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

4.2. Show timer

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

• event-id -- the name you gave the event
• total-completed events -- number of times it has been stopped
• total-time -- total elapse time that it was running
• current-event:
  • none -- the timer is stopped
  • block with start time -- the timer is running

5. Limitations

May not give accurate results if used across midnight.