Adding upstream version 115.8.0esr.upstream/115.8.0esr

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

1 files changed, 71 insertions, 0 deletions

diff --git a/docs/nspr/reference/pr_interrupt.rst b/docs/nspr/reference/pr_interrupt.rst
new file mode 100644
index 0000000000..67bf324e96
--- /dev/null
+++ b/docs/nspr/reference/pr_interrupt.rst
@@ -0,0 +1,71 @@
+PR_Interrupt
+============
+
+Sets the interrupt request for a target thread.
+
+
+Syntax
+------
+
+.. code::
+
+   #include <prthread.h>
+
+   PRStatus PR_Interrupt(PRThread *thread);
+
+
+Parameter
+~~~~~~~~~
+
+:ref:`PR_Interrupt` has the following parameter:
+
+``thread``
+   The thread whose interrupt request you want to set.
+
+
+Returns
+~~~~~~~
+
+The function returns one of the following values:
+
+-  If the specified thread is currently blocked, ``PR_SUCCESS``.
+-  Otherwise, ``PR_FAILURE``.
+
+
+Description
+-----------
+
+The purpose of :ref:`PR_Interrupt` is to request that a thread performing
+some task stop what it is doing and return to some control point. It is
+assumed that a control point has been mutually arranged between the
+thread doing the interrupting and the thread being interrupted. When the
+interrupted thread reaches the prearranged point, it can communicate
+with its peer to discover the real reason behind the change in plans.
+
+The interrupt request remains in the thread's state until it is
+delivered exactly once or explicitly canceled. The interrupted thread
+returns ``PR_FAILURE`` (-1) with an error code (see :ref:`PR_GetError`) for
+blocking operations that return a :ref:`PRStatus` (such as I/O operations,
+monitor waits, or waiting on a condition). To check whether the thread
+was interrupted, compare the result of :ref:`PR_GetError` with
+``PR_PENDING_INTERRUPT_ERROR``.
+
+:ref:`PR_Interrupt` may itself fail if the target thread is invalid.
+
+Bugs
+----
+
+:ref:`PR_Interrupt` has the following limitations and known bugs:
+
+-  There can be a delay for a thread to be interrupted from a blocking
+   I/O function. In all NSPR implementations, the maximum delay is at
+   most five seconds. In the pthreads-based implementation on Unix, the
+   maximum delay is 0.1 seconds.
+-  File I/O is considered instantaneous, so file I/O functions cannot be
+   interrupted. Unfortunately the standard input, output, and error
+   streams are treated as files by NSPR, so a :ref:`PR_Read` call on
+   ``PR_STDIN`` cannot be interrupted even though it may block
+   indefinitely.
+-  In the NT implementation, :ref:`PR_Connect` cannot be interrupted.
+-  In the NT implementation, a file descriptor is not usable and must be
+   closed after an I/O function on the file descriptor is interrupted.