NSPR Reference: Chapter 13 Interval Timing
Description: The Sun-Netscape Alliance, a strategic alliance formed by America Online and Sun Microsystems, Inc., is delivering iPlanet e-commerce software and enterprise solutions that enable companies to compete successfully in the Net Economy
Keywords: electronic commerce, ecommerce, ebusiness, e-business, e-commerce, enterprise software, net economy, Netscape, Sun Microsystems, Sun-Netscape Alliance, iPlanet, internet software

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