forked from mirrors/gecko-dev
14e205a735
Depends on D137612 Differential Revision: https://phabricator.services.mozilla.com/D137650
71 lines
2.2 KiB
ReStructuredText
71 lines
2.2 KiB
ReStructuredText
PR_Interrupt
|
|
============
|
|
|
|
Sets the interrupt request for a target thread.
|
|
|
|
|
|
Syntax
|
|
------
|
|
|
|
.. code:: eval
|
|
|
|
#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.
|