CIBC:Documentation:SCIRun:DevManual:Utilities

SCIRun Utilities

This chapter describes some simple utilities available in SCIRun.

Introduction

The Core/Util directory is a miscellaneous collection of code. The code can be classified into 3 groups: debugging tools, timing routines, and SCIRun internal code.

The debugging tools and timing routines are generally useful. The SCIRun internal code is not.

The SCIRun internal code consists of routines for accessing shared libraries and work arounds of bugs on Linux platforms.

Programming with SCIRun Utilities

Use the the debugging and timing tools when developing any kind of code.

Use the debugging tools to specify data invariants, catch programming errors, and log messages during program execution.

The timer tools can be used to analyze code bottlenecks and perform other timing tasks.

Assertion

Assertions have 2 (related) uses. They are used to catch programming errors and they may used to make promises between a routine and its caller, i.e. "If you the caller send me data that does not violate my assertion(s) then I, the routine, promise to do the right thing by you."

Assertions express a set of valid states a data object (or objects) may possess at some point in the code. If a piece of data is not in a valid state, i.e. it violates the assertion, then the assertion will catch this violation, report the violation, and perhaps terminate the program.

SCIRun supports a number of assertion styles which can be found in Assert.h and FancyAssert.h. Here are a few examples:

Ensure that the variable 'n' is greater than 0:

ASSERT(n < 0);
   

Ensure that 'a' is equal to 999:

ASSERTEQ(a, 999);

Other examples:

ASSERTNE(a, 0);
ASSERTRANGE(a, 0.0, 1.0);
  

Timer

A Timer keeps track of time. Class Timer is an abstract base class - you can't create a Timer object. But you can create objects of the derived types CPUTimer, WallClockTimer, and TimeThrottle. These all provide the functions start(), stop(), clear(), time(), and add(). A TimeThrottle also provides the function wait_for_time(). Functions common to all timers are:

start() starts or resumes a timer.

stop() stops a timer. It does not clear accumulated time. The timer may be resumed with start().

clear() sets the timer's accumulated time to 0. clear() may be executed while a timer is running (although a warning will be written to std error).

time() returns the timer's accumulated time. It may be executed while the timer is running or stopped.

add(double t) adds t seconds to the current elapsed time.

Individual timer types are discussed next.

CPUTimer

CPUTimer records the elasped CPU time (seconds) used by the calling process (including system CPU time used on behalf of the calling process).

Example use of a CPUTimer:

CPUTimer cpuTimer;
cpuTimer.start();
for (i =0; i<3; ++i) {
   .
   .
   .
}
cpuTimer.stop();
std::cout << "Loop used " << cpuTimer.time()
          << " seconds of cpu" << endl;
   

WallClockTimer

WallClockTimer records elasped real time (seconds).

Example use of a WallClockTimer:

WallClockTimer wcTimer;
wcTimer.start();
for (i =0; i<3; ++i) {
   .
   .
   .
}
wcTimer.stop();
std::cout << "Loop used " << wcTimer.time()
          << " seconds of real time" << endl;
   

TimeThrottle

TimeThrottle is a WallClockTimer with the added function wait_for_time().

wait_for_time(double endtime) will suspend the calling thread until the given endtime (seconds) has elapsed. This function is only implemented on SGI systems.

Example use of a TimeThrottle:

TimeThrottle timeThrottle;
timeThrottle.start();
double startTime = timeThrottle.time();
// Start doing stuff.
 .
 .
 .
// Make sure that not less than 1 second has elapsed since we started
// doing stuff.
timeThrottle.wait_for_time(startTime + 1);
   

---

Go back to Documentation:SCIRun:DevManual