[PATCH 1/2] doc: trim down documentation slightly

[Eric Wong <normalperson@yhbt.net>]

The "threads:" option for the "listen" directive is worthless.
Having a dedicated thread per-process is already more than enough
(and ideal) for a multi-process setup.  Multiple acceptor threads
is still wrong for a single-process setup (even if we did not
have a GVL) as it still incurs contention with the worker
pool within the kernel.

So remove the documentation regarding "listen ... threads: ",
for now; at least until somebody can prove it's useful and not
taking up space.

Additionally, "atfork_parent" may be useful for restarting
background threads/connections if somebody wants to run
background jobs in the master process, so stop saying
it's completely useless.
---
 Documentation/yahns_config.pod    | 17 -----------------
 examples/yahns_rack_basic.conf.rb |  2 +-
 test/test_server.rb               |  8 ++++----
 3 files changed, 5 insertions(+), 22 deletions(-)

diff --git a/Documentation/yahns_config.pod b/Documentation/yahns_config.pod
index ff04cb3..12ec75e 100644
--- a/Documentation/yahns_config.pod
+++ b/Documentation/yahns_config.pod
@@ -422,22 +422,6 @@ ref: https://lwn.net/Articles/542629/
 
 Default: false (unset)
 
-=item threads: INTEGER
-
-Used to control the number of threads blocking on the L<accept(2)>
-or L<accept4(2)> system call (per listen socket).
-
-Usually, only one thread here is necessary, especially when
-multiple worker_processes are configured (as there'll be one
-thread per-process).  Having extra threads may increase
-contention with epoll and FD allocation within one process.
-
-Note: do not confuse this option with worker_threads for queues,
-each queue has their own thread pool and it makes sense to
-have multiple threads there.
-
-Default: 1
-
 =item umask: MODE
 
 Sets the file mode creation mask for UNIX sockets.  If specified,
@@ -584,7 +568,6 @@ Default: none
 =item atfork_parent &BLOCK
 
 This &BLOCK is executed in the parent after the L<fork(2)> operation.
-This may not be useful, but exists in case somebody finds a use for it.
 
 Default: none
 
diff --git a/examples/yahns_rack_basic.conf.rb b/examples/yahns_rack_basic.conf.rb
index 12bbc99..33ba619 100644
--- a/examples/yahns_rack_basic.conf.rb
+++ b/examples/yahns_rack_basic.conf.rb
@@ -16,7 +16,7 @@
     puts "#$$ yahns parent about to spawn"
   end
   atfork_parent do
-    puts "#$$ this is probably not useful"
+    puts "#$$ yahns parent done spawning"
   end
 end
 
diff --git a/test/test_server.rb b/test/test_server.rb
index 65a6ea1..87193e3 100644
--- a/test/test_server.rb
+++ b/test/test_server.rb
@@ -428,7 +428,7 @@ def test_mp_hooks
         worker_processes(1) do
           atfork_child { puts "af #$$ worker is running" }
           atfork_prepare { puts "af #$$ parent about to spawn" }
-          atfork_parent { puts "af #$$ this is probably not useful" }
+          atfork_parent { puts "af #$$ parent done spawning" }
         end
       }
       stderr_path err.path
@@ -457,7 +457,7 @@ def test_mp_hooks
     assert_equal("af #{pid} parent about to spawn", lines.shift)
 
     # child/parent ordering is not guaranteed
-    assert_equal 1, lines.grep(/\Aaf #{pid} this is probably not useful\z/).size
+    assert_equal 1, lines.grep(/\Aaf #{pid} parent done spawning\z/).size
     assert_equal 1, lines.grep(/\Aaf #{worker_pid} worker is running\z/).size
   ensure
     quit_wait(master_pid)
@@ -479,7 +479,7 @@ def test_mp_hooks_worker_nr
         worker_processes(1) do
           atfork_child { |nr| puts "af.#{nr} #$$ worker is running" }
           atfork_prepare { |nr| puts "af.#{nr} #$$ parent about to spawn" }
-          atfork_parent { |nr| puts "af.#{nr} #$$ this is probably not useful" }
+          atfork_parent { |nr| puts "af.#{nr} #$$ parent done spawning" }
         end
       }
       stderr_path err.path
@@ -503,7 +503,7 @@ def test_mp_hooks_worker_nr
 
     # child/parent ordering is not guaranteed
     assert_equal 1,
-        lines.grep(/\Aaf\.0 #{pid} this is probably not useful\z/).size
+        lines.grep(/\Aaf\.0 #{pid} parent done spawning\z/).size
     assert_equal 1,
         lines.grep(/\Aaf\.0 #{worker_pid} worker is running\z/).size
   ensure
-- 
EW