NSPR 2.0: Interval Timing

The Mozilla Organization
	At A Glance
	Feedback
	Get Involved
	Newsgroups
	License Terms
	Newsbot

Developer Docs
	Roadmap
	Projects
	Ports
	Module Owners
	Hacking
	Get the Source
	Build It

Testing
	Download
	Bugzilla
	Bug Writing

Tools
	View Source
	Tree Status
	New Checkins
	Submit A Bug

FAQ
Search

[Contents] [Previous] [Next] [Last]

Chapter 13
Interval Timing

NSPR defines a platform-dependent type, PRIntervalTime, for timing intervals of fewer than 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 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 (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 slightly less than 12 hours, making the maximum useful interval approximately six 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);

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.

[Contents] [Previous] [Next] [Last]

Last Updated: Mon Jul 13 18:22:37 PDT 1998

Chapter 13 Interval Timing

Description

PR_IntervalNow

Returns

Caution

Returns

Returns

Returns

Returns

Returns

Returns

Description

Chapter 13
Interval Timing