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 Note

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 (2³¹-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.