63 lines
2.2 KiB
Markdown
63 lines
2.2 KiB
Markdown
# 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.
|