fdmap: document + fix for level-trigger

Our QueueQuitter may race with epoll_wait and GC, potentially
triggering memory corruption if a level-trigger object was
placed into the ready list and no longer referenced.

We'll work around this problem by making the QueueQuitter object
a thread-local (on thread failure) to prevent concurency issues
where the epoll pointer no longer points to a Ruby object.

1 files changed, 5 insertions, 0 deletions

diff --git a/lib/yahns/fdmap.rb b/lib/yahns/fdmap.rb
index a9125e7..5ba4399 100644
--- a/lib/yahns/fdmap.rb
+++ b/lib/yahns/fdmap.rb
@@ -36,6 +36,11 @@ class Yahns::Fdmap # :nodoc:
   # as one which got accept-ed (a brand new IO object) so we must prevent
   # IO#close in worker threads from racing with any threads which may run
   # __expire
+  #
+  # We must never, ever call this while it is capable of being on the
+  # epoll ready list and returnable by epoll_wait.  So we can only call
+  # this on objects which were epoll_ctl-ed with EPOLLONESHOT (and now
+  # retrieved).
   def sync_close(io)
     @fdmap_mtx.synchronize do
       @count -= 1