You are currently viewing a snapshot of www.mozilla.org taken on April 21, 2008. Most of this content is highly out of date (some pages haven't been updated since the project began in 1998) and exists for historical purposes only. If there are any pages on this archive site that you think should be added back to www.mozilla.org, please file a bug.

Skip to main content

NSPR Reference
Previous     Contents     Next     

Chapter 13   Interval Timing

NSPR defines a platform-dependent type, PRIntervalTime, for timing intervals of fewer than approximately 6 hours. This chapter describes PRIntervalTime and the functions that allow you to use it for timing purposes:

Interval Time Type and Constants
Interval Functions

Interval Time Type and Constants

All timed functions in NSPR require a parameter that depicts the amount of time allowed to elapse before the operation is declared failed. The type of such arguments is PRIntervalTime. Such parameters are common in NSPR functions such as those used for I/O operations and operations on condition variables.

NSPR 2.0 provides interval times that are efficient in terms of performance and storage requirements. Conceptually, they are based on free-running counters that increment at a fixed rate without possibility of outside influence (as might be observed if one was using a time-of-day clock that gets reset due to some administrative action). The counters have no fixed epoch and have a finite period. To make use of these counters, the application must declare a point in time, the epoch, and an amount of time elapsed since that epoch, the interval. In almost all cases the epoch is defined as the value of the interval timer at the time it was sampled.

PRIntervalTime

A platform-dependent type that represents a monotonically increasing integer--the NSPR runtime clock.


Syntax 
#include <prinrval.h>


typedef PRUint32 PRIntervalTime;


#define PR_INTERVAL_MIN 1000UL
#define PR_INTERVAL_MAX 100000UL


#define PR_INTERVAL_NO_WAIT 0UL
#define PR_INTERVAL_NO_TIMEOUT 0xffffffffUL


Description
The units of PRIntervalTime are platform-dependent. They are chosen to be appropriate for the host OS, yet provide sufficient resolution and period to be useful to clients.

The increasing interval value represented by PRIntervalTime wraps. It should therefore never be used for intervals greater than approximately 6 hours. Interval times are accurate regardless of host processing requirements and are very cheap to acquire.

The constants PR_INTERVAL_MIN and PR_INTERVAL_MAX define a range in ticks per second. These constants bound both the period and the resolution of a PRIntervalTime object.

The reserved constants PR_INTERVAL_NO_WAIT and PR_INTERVAL_NO_TIMEOUT have special meaning for NSPR. They indicate that the process should wait no time (return immediately) or wait forever (never time out), respectively.


Important
The counters used for interval times are allowed to overflow. Since the sampling of the counter used to define an arbitrary epoch may have any 32-bit value, some care must be taken in the use of interval times. The proper coding style to test the expiration of an interval is as follows: 

if ((PRIntervalTime)(now - epoch) > interval)
<... interval has expired ...>

As long as the interval and the elapsed time (now - epoch) do not exceed half the namespace allowed by a PRIntervalTime (231-1), the expression shown above provides the expected result even if the signs of now and epoch differ.

The resolution of a PRIntervalTime object is defined by the API. NSPR guarantees that there will be at least 1000 ticks per second and not more than 100000. At the maximum resolution of 10000 ticks per second, each tick represents 1/100000 of a second. At that rate, a 32-bit register will overflow in approximately 28 hours, making the maximum useful interval approximately 6 hours. Waiting on events more than half a day in the future must therefore be based on a calendar time.

Interval Functions

Interval timing functions are divided into three groups:

Getting the Current Interval and Ticks Per Second
Converting Standard Clock Units to Platform-Dependent Intervals
Converting Platform-Dependent Intervals to Standard Clock Units

Getting the Current Interval and Ticks Per Second

PR_IntervalNow

Returns the value of NSPR's free-running interval timer.


Syntax 
#include <prinrval.h>


PRIntervalTime PR_IntervalNow(void);


Returns
A PRIntervalTime object.


Description
You can use the value returned by PR_IntervalNow to establish epochs and to determine intervals (that is, compute the difference between two times). PR_IntervalNow is both very efficient and nonblocking, so it is appropriate to use (for example) while holding a mutex.

The most common use for PR_IntervalNow() is to establish an epoch and test for the expiration of intervals. In this case, you typically call PR_IntervalNow in a sequence that looks like this: 

PRStatus rv;
   PRIntervalTime epoch = PR_IntervalNow();
   PR_Lock(data->mutex);
   if (!EvaluateData(data))
   {
       while (PR_TRUE)
       {
         rv = PR_Wait(data->condition, interval);
         if (PR_FAILURE == rv) break;  /* likely an interrupt */
         if (EvaluateData(data)) break;  /* condition is met */
         if ((PRIntervalTime)(PR_IntervalNow() - epoch) > interval) break;  /* timeout */
       }
   }
   PR_Unlock(data->mutex);


Caution

Note the casting of (PR_InternvalNow() - epoch) back to a PRIntervalTime. In C, the difference between any two fields is signed. The comparison performed by PR_IntervalNow relies on unsigned (modulo 2) arithmetic to function properly.


PR_TicksPerSecond

Returns the number of ticks per second currently used to determine the value of PRIntervalTime.


Syntax 
#include <prinrval.h>


PRUint32 PR_TicksPerSecond(void);


Returns
An integer between 1000 and 100000 indicating the number of ticks per second counted by PRIntervalTime on the current platform. This value is platform dependent and does not change after NSPR is initialized.


Description
The value returned by PR_TicksPerSecond lies between PR_INTERVAL_MIN and PR_INTERVAL_MAX.

The relationship between a PRIntervalTime tick and standard clock units is platform-dependent. PR_TicksPerSecond allows you to discover exactly what that relationship is. Seconds per tick (the inverse of PR_TicksPerSecond) is always between 10 microseconds and 1 millisecond.

Converting Standard Clock Units to Platform-Dependent Intervals

Conversion may cause overflow, which is not reported. For details, see PRIntervalTime.

These functions are not expensive. However, if the value being converted is a constant, it is a good idea to make the conversion once, early, and cache it for later use.

These functions perform mathematical rounding. If that is not a desirable feature, you should provide your own conversions based on PR_TicksPerSecond.

PR_SecondsToInterval

Converts standard clock seconds to platform-dependent intervals.


Syntax 
#include <prinrval.h>


PRIntervalTime PR_SecondsToInterval(PRUint32 seconds);


Returns
Platform-dependent equivalent of the value passed in the seconds parameter.

PR_MillisecondsToInterval

Converts standard clock milliseconds to platform-dependent intervals.


Syntax 
#include <prinrval.h>


PRIntervalTime PR_MillisecondsToInterval(PRUint32 milli);


Returns
Platform-dependent equivalent of the value passed in the milli parameter.

PR_MicrosecondsToInterval

Converts standard clock microseconds to platform-dependent intervals.


Syntax 
#include <prinrval.h>


PRIntervalTime PPR_MicrosecondsToInterval(PRUint32 micro);


Returns
Platform-dependent equivalent of the value passed in the micro parameter.

Converting Platform-Dependent Intervals to Standard Clock Units

Conversion may cause overflow, which is not reported. For details, see PRIntervalTime.

These functions are not expensive. However, if the value being converted is a constant, it is a good idea to make the conversion once, early, and cache it for later use.

These functions perform mathematical rounding. If that is not a desirable feature, you should provide your own conversions based on PR_TicksPerSecond.

PR_IntervalToSeconds

Converts platform-dependent intervals to standard clock seconds.


Syntax 
#include <prinrval.h>


PRUint32 PR_IntervalToSeconds(PRIntervalTime ticks);


Returns
Equivalent in seconds of the value passed in the ticks parameter.


Description
Conversion may cause overflow, which is not reported.

PR_IntervalToMilliseconds

Converts platform-dependent intervals to standard clock milliseconds.


Syntax 
#include <prinrval.h>


PRUint32 PR_IntervalToMilliseconds(PRIntervalTime ticks);


Returns
Equivalent in milliseconds of the value passed in the ticks parameter.


Description
Conversion may cause overflow, which is not reported.

PR_IntervalToMicroseconds

Converts platform-dependent intervals to standard clock microseconds.


Syntax 
#include <prinrval.h>


PRUint32 PR_IntervalToMicroseconds(PRIntervalTime ticks);


Description
Conversion may cause overflow, which is not reported.

Previous     Contents     Next     

Last Updated May 18, 2001