From 36d22d82aa202bb199967e9512281e9a53db42c9 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Sun, 7 Apr 2024 21:33:14 +0200 Subject: Adding upstream version 115.7.0esr. Signed-off-by: Daniel Baumann --- docs/nspr/reference/printervaltime.rst | 72 ++++++++++++++++++++++++++++++++++ 1 file changed, 72 insertions(+) create mode 100644 docs/nspr/reference/printervaltime.rst (limited to 'docs/nspr/reference/printervaltime.rst') diff --git a/docs/nspr/reference/printervaltime.rst b/docs/nspr/reference/printervaltime.rst new file mode 100644 index 0000000000..9367d6ad7f --- /dev/null +++ b/docs/nspr/reference/printervaltime.rst @@ -0,0 +1,72 @@ +PRIntervalTime +============== + +A platform-dependent type that represents a monotonically increasing +integer--the NSPR runtime clock. + + +Syntax +------ + +.. code:: + + #include + + 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 :ref:`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 :ref:`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 :ref:`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: + +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: + +.. code:: + + 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 :ref:`PRIntervalTime` (2\ :sup:`31`-1), the +expression shown above provides the expected result even if the signs of +now and epoch differ. + +The resolution of a :ref:`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. -- cgit v1.2.3