Illustrate concurrency with timebars

John Peck
Published , updated

I needed to document some concurrent processes, so I put together a script that generates figures like these:

mario example

Download single-file executables here.

Creating the input file

The input file is simply Tcl, and is sourced by the main program. Starting the program with no inputs will create an example.tbi file in an input directory. This is just some basic organization -- the program doesn't care about the input file location or its extension.

The seconds_per_inch variable controls how large timeslices will be relative to their labels. If your timeslice labels don't fit, try reducing this number.

Creating timeslices

The timeslice::timeslice function creates a timeslice. For example:

set mario_airborne [timeslice::timeslice 100e-3 red "Mario has jumped"]

...creates a 100ms-long red timeslice with a label. Recognized colors are black, blue, green, cyan, red, magenta, yellow, and white.

Creating reference lines (timestamps)

The timeslice::reference function creates a reference line. For example:

set mario_lands [timeslice::reference "Mario lands on goomba"]

...creates a reference line with a label. The program will assign a timestamp to the reference line depending on where it lands in its timeline.

Creating timelines

The timeline::timeline function assembles lists of timeslices into a timeline. For example:

set mario_list [list $mario_airborne $mario_lands $mario_recovers]
set mario_timeline [timeline::timeline "Mario" $mario_list]

...creates the mario_timeline timeline. Notice that the mario_lands reference line is in the list of timeslices along with regular timeslices.

Processing the input file

I have a history of creating Tcl software used by manufacturing technicians. These people usually use Windows machines, and they like being able to choose which version they can run. My executables thus have their version numbers in their filenames. Use the -h option to see the usage:

~/projects/eventual/timebars/starpacks $ ./timebars-1.0.2-win32-ix86.exe -h
timebars usage: timebars [options] filename
 -d value             Minimum depth <50>
 -o value             Output file name <timebars.fig>
 --                   Forcibly stop option processing
 -help                Print this message
 -?                   Print this message

If you don't specify an input file (call the script with no arguemnts), the script will generate an input directory and an example file in that directory.

The "minimum depth" parameter is for Xfig. If you already have graphics drawn in Xfig and you want to add this figure, you'll need to make sure the depths cooperate to make overlapping elements visible.