From 36d22d82aa202bb199967e9512281e9a53db42c9 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Sun, 7 Apr 2024 21:33:14 +0200 Subject: Adding upstream version 115.7.0esr. Signed-off-by: Daniel Baumann --- .../using_io_timeouts_and_interrupts_on_nt.rst | 131 +++++++++++++++++++++ 1 file changed, 131 insertions(+) create mode 100644 docs/nspr/using_io_timeouts_and_interrupts_on_nt.rst (limited to 'docs/nspr/using_io_timeouts_and_interrupts_on_nt.rst') diff --git a/docs/nspr/using_io_timeouts_and_interrupts_on_nt.rst b/docs/nspr/using_io_timeouts_and_interrupts_on_nt.rst new file mode 100644 index 0000000000..9aaca06a1b --- /dev/null +++ b/docs/nspr/using_io_timeouts_and_interrupts_on_nt.rst @@ -0,0 +1,131 @@ +This technical memo is a cautionary note on using NetScape Portable +Runtime's (NSPR) IO timeout and interrupt on Windows NT 3.51 and 4.0. +Due to a limitation of the present implementation of NSPR IO on NT, +programs must follow the following guideline: + +If a thread calls an NSPR IO function on a file descriptor and the IO +function fails with PR_IO_TIMEOUT_ERROR or +PR_PENDING_INTERRUPT_ERROR, the file descriptor must be closed +before the thread exits. + +In this memo we explain the problem this guideline is trying to work +around and discuss its limitations. + +.. _NSPR_IO_on_NT: + +NSPR IO on NT +------------- + +The IO model of NSPR 2.0 is synchronous and blocking. A thread calling +an IO function is blocked until the IO operation finishes, either due to +a successful IO completion or an error. If the IO operation cannot +complete before the specified timeout, the IO function returns with +PR_IO_TIMEOUT_ERROR. If the thread gets interrupted by another +thread's PR_Interrupt() call, the IO function returns with +PR_PENDING_INTERRUPT_ERROR. + +On Windows NT, NSPR IO is implemented using NT's *overlapped* (also +called *asynchronous*) *IO*. When a thread calls an IO function, the +thread issues an overlapped IO request using the overlapped buffer in +its PRThread structure. Then the thread is put to sleep. In the +meantime, there are dedicated internal threads (called the *idle +threads*) monitoring the IO completion port for completed IO requests. +If a completed IO request appears at the IO completion port, an idle +thread fetches it and wakes up the thread that issued the IO request +earlier. This is the normal way the thread is awakened. + +.. _IO_Timeout_and_Interrupt: + +IO Timeout and Interrupt +------------------------ + +However, NSPR may wake up the thread in two other situations: + +- if the overlapped IO request is not completed before the specified + timeout. (Note that we can't specify timeout on overlapped IO + requests, so the timeouts are all handled at the NSPR level.) In this + case, the error is PR_IO_TIMEOUT_ERROR. +- if the thread gets interrupted by another thread's + PR_Interrupt() call. In this case, the error is + PR_PENDING_INTERRUPT_ERROR. + +These two errors are generated by the NSPR layer, so the OS is oblivious +of what is going on and the overlapped IO request is still in progress. +The OS still has a pointer to the overlapped buffer in the thread's +PRThread structure. If the thread subsequently exists and its +PRThread structure gets deleted, the pointer to the overlapped +buffer will be pointing to freed memory. This is problematic. + +.. _Canceling_Overlapped_IO_by_Closing_the_File_Descriptor: + +Canceling Overlapped IO by Closing the File Descriptor +------------------------------------------------------ + +Therefore, we need to cancel the outstanding overlapped IO request +before the thread exits. NT's CancelIo() function would be +ideal for this purpose. Unfortunately, CancelIo() is not +available on NT 3.51. So we can't go this route as long as we are +supporting NT 3.51. The only reliable way to cancel outstanding +overlapped IO request that works on both NT 3.51 and 4.0 is to close the +file descriptor, hence the rule of thumb stated at the beginning of this +memo. + +.. _Limitations: + +Limitations +----------- + +This seemingly harsh way to force the completion of outstanding +overlapped IO request has the following limitations: + +- It is difficult for threads to shared a file descriptor. For example, + suppose thread A and thread B call PR_Accept() on the same + socket, and they time out at the same time. Following the rule of + thumb, both threads would close the socket. The first + PR_Close() would succeed, but the second PR_Close() + would be freeing freed memory. A solution that may work is to use a + lock to ensure only one thread can be using that socket at all times. +- Once there is a timeout or interrupt error, the file descriptor is no + longer usable. Suppose the file descriptor is intended to be used for + the life time of the process, for example, the logging file, this is + really not acceptable. A possible solution is to add a + PR_DisableInterrupt() function to turn off interrupts when + accessing such file descriptors. + +.. + + *A related known bug is that timeout and interrupt don't work for + PR_Connect() on NT. This bug is due to a different + limitation in our NT implementation.* + +.. _Conclusions: + +Conclusions +----------- + +As long as we need to support NT 3.51, we need to program under the +guideline that after an IO timeout or interrupt error, the thread must +make sure the file descriptor is closed before it exits. Programs should +also take care in sharing file descriptors and using IO timeout or +interrupt on files that need to stay open throughout the process. + +When we stop supporting NT 3.51, we can look into using NT 4's +CancelIo() function to cancel outstanding overlapped IO +requests when we get IO timeout or interrupt errors. If +CancelIo() really works as advertised, that should +fundamentally solve this problem. + +If these limitations with IO timeout and interrupt are not acceptable to +the needs of your programs, you can consider using the Win95 version of +NSPR. The Win95 version runs without trouble on NT, but you would lose +the better performance provided by NT fibers and asynchronous IO. + +| + +.. _Original_Document_Information: + +Original Document Information +----------------------------- + +- Author: larryh@netscape.com +- Last Updated Date: December 1, 2004 -- cgit v1.2.3