comment to explain YAHNS_FD env

Users of other web servers may be surprised there is no recommended
way to have a new instance of yahns inherit from another web server.

1 files changed, 9 insertions, 0 deletions

diff --git a/lib/yahns/server.rb b/lib/yahns/server.rb
index 220381b..92adf52 100644
--- a/lib/yahns/server.rb
+++ b/lib/yahns/server.rb
@@ -300,6 +300,15 @@ class Yahns::Server # :nodoc:
   def inherit_listeners!
     # inherit sockets from parents, they need to be plain Socket objects
     # before they become Yahns::UNIXServer or Yahns::TCPServer
+    #
+    # Note: we intentionally use a yahns-specific environment variable
+    # here because existing servers may use non-blocking listen sockets.
+    # yahns uses _blocking_ listen sockets exclusively.  We cannot
+    # change an existing socket to blocking mode if two servers are
+    # running (one expecting blocking, one expecting non-blocking)
+    # because that can completely break the non-blocking one.
+    # Unfortunately, there is no one-off MSG_DONTWAIT-like flag for
+    # accept4(2).
     inherited = ENV['YAHNS_FD'].to_s.split(/,/).map do |fd|
       io = Socket.for_fd(fd.to_i)
       set_server_sockopt(io, sock_opts(io))