pr_interrupt.rst (2281B)
1 PR_Interrupt 2 ============ 3 4 Sets the interrupt request for a target thread. 5 6 7 Syntax 8 ------ 9 10 .. code:: 11 12 #include <prthread.h> 13 14 PRStatus PR_Interrupt(PRThread *thread); 15 16 17 Parameter 18 ~~~~~~~~~ 19 20 :ref:`PR_Interrupt` has the following parameter: 21 22 ``thread`` 23 The thread whose interrupt request you want to set. 24 25 26 Returns 27 ~~~~~~~ 28 29 The function returns one of the following values: 30 31 - If the specified thread is currently blocked, ``PR_SUCCESS``. 32 - Otherwise, ``PR_FAILURE``. 33 34 35 Description 36 ----------- 37 38 The purpose of :ref:`PR_Interrupt` is to request that a thread performing 39 some task stop what it is doing and return to some control point. It is 40 assumed that a control point has been mutually arranged between the 41 thread doing the interrupting and the thread being interrupted. When the 42 interrupted thread reaches the prearranged point, it can communicate 43 with its peer to discover the real reason behind the change in plans. 44 45 The interrupt request remains in the thread's state until it is 46 delivered exactly once or explicitly canceled. The interrupted thread 47 returns ``PR_FAILURE`` (-1) with an error code (see :ref:`PR_GetError`) for 48 blocking operations that return a :ref:`PRStatus` (such as I/O operations, 49 monitor waits, or waiting on a condition). To check whether the thread 50 was interrupted, compare the result of :ref:`PR_GetError` with 51 ``PR_PENDING_INTERRUPT_ERROR``. 52 53 :ref:`PR_Interrupt` may itself fail if the target thread is invalid. 54 55 Bugs 56 ---- 57 58 :ref:`PR_Interrupt` has the following limitations and known bugs: 59 60 - There can be a delay for a thread to be interrupted from a blocking 61 I/O function. In all NSPR implementations, the maximum delay is at 62 most five seconds. In the pthreads-based implementation on Unix, the 63 maximum delay is 0.1 seconds. 64 - File I/O is considered instantaneous, so file I/O functions cannot be 65 interrupted. Unfortunately the standard input, output, and error 66 streams are treated as files by NSPR, so a :ref:`PR_Read` call on 67 ``PR_STDIN`` cannot be interrupted even though it may block 68 indefinitely. 69 - In the NT implementation, :ref:`PR_Connect` cannot be interrupted. 70 - In the NT implementation, a file descriptor is not usable and must be 71 closed after an I/O function on the file descriptor is interrupted.