Documention for: profile-timer.r
Created by: sunanda
 on: 13-Oct-2004
Last updated by: sunanda on: 13-Jul-2005
Format: text/editable
Downloaded on: 16-Apr-2024

[numbering-on
[contents
 
[asis
 Version: 0.0.1 (corrects typos)
 10-Oct-2004 
 Sunanda 
asis] 

[h2 Purpose

[p/class/ca+notice To help you find the elapse time for executing arbitrary stretches of code. Could help to track down slow parts that need tuning.

[h2 Similar scripts

[p The Library also contains:

[li [link/class/fsl http://www.rebol.org/cgi-bin/cgiwrap/rebol/view-script.r?script=profiler.r&color=yes "profiler.r" 
[li [link/class/fsl http://www.rebol.org/cgi-bin/cgiwrap/rebol/view-script.r?script=timeit.r&color=yes "timeit.r"
list]

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

[h2 Quick examples

[h3 Time a single event

[asis
  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
   ]
asis]

[p As you can see, the loop took .06 seconds


[h3 Time Nested events

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

[asis
  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
asis]

[p 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.


[h2 Usage

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

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

[h3 Refinements

[table
[row
[cell/class/lsh
Refinement
[cell/class/*
Meaning
[cell/class/*
Example
[cell/class/*
Notes

[row
[cell/class/lskey1
Start
[cell/class/lsdata1 Start timing an event
[cell/class/* profile-timer/start "my timer"
[cell/class/* After you stop a timer, you can use start to start it again

[row
[cell/class/lskey2
Stop
[cell/class/lsdata2 Stop timing a started event
[cell/class/* profile-timer/stop "my timer"
[cell/class/* A stopped timer can be started again

[row
[cell/class/*-3
Show
[cell/class/*-3 See the value of a timer
[cell/class/*-3 profile-timer/show "my timer"
[cell/class/*-3 See below for details of the timer object


[row
[cell/class/*-3
Show-all
[cell/class/*-3 See the value of **all** timers
[cell/class/*-3 profile-timer/show-all "dummy string"
[cell/class/*-3 See below for details of the timer object


[row
[cell/class/*-3
Reset
[cell/class/*-3 Zeroizes **all** timers
[cell/class/*-3 profile-timer/reset "dummy string"
[cell/class/*-3 Same as reDOing %profile-timer.r

table]

[h3 Show timer

A timer object looks like this:

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

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



[h2 Limitations
[p May not give accurate results if used across midnight.