Documentation for: timeblk.r

Usage document for %timeblk.r

1. Introduction to %timeblk.r

This script is a handy tool that times REBOL code.

This usage document also highlights other timing related scripts, and some of this information is shared among the documentation.

2. timeblk At a Glance

 Script: "Time a Block" (28-Oct-1998)
 == [
     fib: func [x] [
         if (x < 2) [return x]
         return (fib x - 2) + (fib x - 1)
     ]
     time-block [fib 20]
   ...
 >> do http://www.rebol.org/cgi-bin/cgiwrap/rebol/download-a-script.r?script-name=timeblk.r
 connecting to: www.rebol.org
 >> do example
 0:00:01
 0:00:01
 

3. Timing related scripts

4. Another excellent timing script, not in the library,

5. Using %timeblk.r

There are a few change that can be made to this script. The script in the repository, is a sample. You need to call time-block with your own block of code.

5.1. Running %timeblk.r

This utility is simple to use. Just DO it.

 >> do %timeblk.r
 

This defines the time-block function, and defines an example. To be more useful, the example should be commented out to remove example from the global namespace.

The time-block function executes a DO on the code in the passed in block!, and displays the elapsed time.

5.1.1. Refinements

time-block also accepts a /reps refinement that takes an integer! argument, for the number of repetitions. This allows for more accurate timings in some circumstances, be careful with side-effects in the block of code you are timing.

5.1.2. Another timing toolkit

For comprehensive named events with cumulative times, take a look at
%profile-timer.r 

5.2. Direct execution from the library

This script can be executed directly from the library

 >> do http://www.rebol.org/cgi-bin/cgiwrap/rebol/download-a-script.r?script-name=timeblk.r
 

6. What you can learn

The example block defines a nice little Fibonacci Sequence recursive function. REBOL does many things, and recursion is one of them.

6.1. Hidden gems everywhere

This also highlights one of the aspect of the scripts in the repository. Many of the samples include gems of code snippets worthy of exploration, perhaps unrelated to the script's main purpose.

The example block defines a fib function, and calls the main time-block function from within inside this block. There are quite a few ways of encapsulating code and data with REBOL. As you learn more, and write programs that are destined for sharing, these encapsulation techniques become more important. Shared code should add a minimum of words to the global namespace. This type of programming may become more prevalent in REBOL as we aim for more shareable scripts.

The time refinement of the now native function, now/time has a resolution of 1 second. Most new machines can cut through a lot of REBOL code in 1 second. More comprehensive timing utilities will use now/time/precise, for much finer grained timings.

7. What can break

Don't try and execute the sample fib function with large values. By nature, recursion can spin a stack frame out of control quite quickly.

A midnight rollover will give wonky results.

With a fast processor, you may get a lot of 0:00 second results.

8. Credits

• The rebol.org Library Team
• Usage document by Brian Tiffin, Library Team Apprentice, Last updated: 9-May-2007