Adding upstream version 124.0.1.upstream/124.0.1

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 72 insertions, 0 deletions

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 <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 :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.