printervaltime.rst (2440B)
1 PRIntervalTime 2 ============== 3 4 A platform-dependent type that represents a monotonically increasing 5 integer--the NSPR runtime clock. 6 7 8 Syntax 9 ------ 10 11 .. code:: 12 13 #include <prinrval.h> 14 15 typedef PRUint32 PRIntervalTime; 16 17 #define PR_INTERVAL_MIN 1000UL 18 #define PR_INTERVAL_MAX 100000UL 19 20 #define PR_INTERVAL_NO_WAIT 0UL 21 #define PR_INTERVAL_NO_TIMEOUT 0xffffffffUL 22 23 24 Description 25 ----------- 26 27 The units of :ref:`PRIntervalTime` are platform-dependent. They are chosen 28 to be appropriate for the host OS, yet provide sufficient resolution and 29 period to be useful to clients. 30 31 The increasing interval value represented by :ref:`PRIntervalTime` wraps. 32 It should therefore never be used for intervals greater than 33 approximately 6 hours. Interval times are accurate regardless of host 34 processing requirements and are very cheap to acquire. 35 36 The constants ``PR_INTERVAL_MIN`` and ``PR_INTERVAL_MAX`` define a range 37 in ticks per second. These constants bound both the period and the 38 resolution of a :ref:`PRIntervalTime` object. 39 40 The reserved constants ``PR_INTERVAL_NO_WAIT`` and 41 ``PR_INTERVAL_NO_TIMEOUT`` have special meaning for NSPR. They indicate 42 that the process should wait no time (return immediately) or wait 43 forever (never time out), respectively. 44 45 .. _Important_Note: 46 47 Important Note 48 ~~~~~~~~~~~~~~ 49 50 The counters used for interval times are allowed to overflow. Since the 51 sampling of the counter used to define an arbitrary epoch may have any 52 32-bit value, some care must be taken in the use of interval times. The 53 proper coding style to test the expiration of an interval is as follows: 54 55 .. code:: 56 57 if ((PRIntervalTime)(now - epoch) > interval) 58 <... interval has expired ...> 59 60 As long as the interval and the elapsed time (now - epoch) do not exceed 61 half the namespace allowed by a :ref:`PRIntervalTime` (2\ :sup:`31`-1), the 62 expression shown above provides the expected result even if the signs of 63 now and epoch differ. 64 65 The resolution of a :ref:`PRIntervalTime` object is defined by the API. 66 NSPR guarantees that there will be at least 1000 ticks per second and 67 not more than 100000. At the maximum resolution of 10000 ticks per 68 second, each tick represents 1/100000 of a second. At that rate, a 69 32-bit register will overflow in approximately 28 hours, making the 70 maximum useful interval approximately 6 hours. Waiting on events more 71 than half a day in the future must therefore be based on a calendar 72 time.