From 8913f6174cd312e911ce839f5b74671ed98a34d5 Mon Sep 17 00:00:00 2001 From: leitner Date: Sat, 1 Oct 2016 20:10:38 +0000 Subject: [PATCH] document race condition caused by queueing of multiple events --- io/io_wait.3 | 12 ++++++++++++ io/io_waituntil.3 | 12 ++++++++++++ 2 files changed, 24 insertions(+) diff --git a/io/io_wait.3 b/io/io_wait.3 index 615fa17..cf93150 100644 --- a/io/io_wait.3 +++ b/io/io_wait.3 @@ -23,5 +23,17 @@ io_wait is not interrupted by the delivery of a signal. Programs that expect interruption are unreliable: they will block if the same signal is delivered a moment before io_wait. The correct way to handle signals is with the self-pipe trick. + +.SH NOTE +Depending on the underlying operating system primitive, there is a +potential race condition to be aware of. Some event notification +mechanisms (for example, kqueue on BSD and epoll on Linux) will return +multiple events. If your application operates on pairs of file +descriptors (a proxy server maybe), and an error on one descriptor +can lead to closing the other descriptor, then an outstanding event on +the other descriptor can still be queued for delivery to you. Be +prepared to receive events for a descriptor that has already been +closed. + .SH "SEE ALSO" io_waituntil(3), io_check(3), io_wantread(3), io_wantwrite(3), io_fd(3) diff --git a/io/io_waituntil.3 b/io/io_waituntil.3 index 062da40..c102bfa 100644 --- a/io/io_waituntil.3 +++ b/io/io_waituntil.3 @@ -7,5 +7,17 @@ io_waituntil \- wait for events void \fBio_waituntil\fP(tai6464 t); .SH DESCRIPTION io_waituntil(t) is like io_wait() but does not wait (noticeably) past time \fIt\fR. + +.SH NOTE +Depending on the underlying operating system primitive, there is a +potential race condition to be aware of. Some event notification +mechanisms (for example, kqueue on BSD and epoll on Linux) will return +multiple events. If your application operates on pairs of file +descriptors (a proxy server maybe), and an error on one descriptor +can lead to closing the other descriptor, then an outstanding event on +the other descriptor can still be queued for delivery to you. Be +prepared to receive events for a descriptor that has already been +closed. + .SH "SEE ALSO" io_wait(3), io_check(3), io_wantread(3), io_wantwrite(3), io_fd(3)