docs/nspr/reference/printervaltime.rst

   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.