yahns 0.0.1 → 0.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: c03354f508bb8d5ece9deaac06b265c9f97c7254
-  data.tar.gz: e0bcd2f85d316a6ff76b9e7f38b9449f088e59aa
+  metadata.gz: 32f85a4c4ed36a082242c5b58bae7f18528543c1
+  data.tar.gz: e741b37a8b0f62d47d9ea08ce36ab69b31536f15
 SHA512:
-  metadata.gz: d1cf5fae66ee58b4a5435d2d760c6b4283a327e58919c67bcfc7a6ec4805b3a80747e47a9565dab2042bebcfd9ec210ee7f6665397e863ab7cd03cddb9b34493
-  data.tar.gz: 761d334654d9b44ba58f96fbe78d087a8e9c323ce55ef5d1597e6681d5d0076d34f41918858aca66ab3056ce2b52f524d5a2d5ba4f70fc60916f815c1213710b
+  metadata.gz: 8eb0d76f793c6bc787ec789214e05f2f03face6e7772cad38ca7da67986e6a579f9b69c927ed39224b75f72e2dafaa3f886a4dc9c17eea24ccd0d3ae59aaf994
+  data.tar.gz: d9b233d340ef2ca35c5f5c085cac97bb6090d3ba2dbf2c89b57edcc1577d6ea5ef8b67f4821f6cbe04e36938b9d49ebd6d8898838f370baeb89da1845297bbe5

data/.gitignore

@@ -13,3 +13,4 @@
 .manifest
 .gem-manifest
 .tgz-manifest
+/doc

data/Documentation/.gitignore

@@ -0,0 +1,5 @@
+# Copyright (C) 2013, Eric Wong <normalperson@yhbt.net> and all contributors
+# License: GPLv3 or later (https://www.gnu.org/licenses/gpl-3.0.txt)
+*.1
+*.5
+*.7

data/Documentation/GNUmakefile

@@ -0,0 +1,50 @@
+# Copyright (C) 2013, Eric Wong <normalperson@yhbt.net> and all contributors
+# License: GPLv3 or later (https://www.gnu.org/licenses/gpl-3.0.txt)
+all::
+
+INSTALL = install
+PANDOC = pandoc
+PANDOC_OPTS = -f markdown --email-obfuscation=none
+pandoc = $(PANDOC) $(PANDOC_OPTS)
+
+m1 =
+m1 += yahns
+m1 += yahns-rackup
+
+m5 =
+m5 += yahns_config
+
+m7 =
+
+man1 := $(addsuffix .1, $(m1))
+man5 := $(addsuffix .5, $(m5))
+man7 := $(addsuffix .7, $(m7))
+
+all:: man
+
+man: $(man1) $(man5) $(man7)
+
+prefix ?= $(HOME)
+mandir ?= $(prefix)/share/man
+man1dir = $(mandir)/man1
+man5dir = $(mandir)/man5
+man7dir = $(mandir)/man7
+
+gem-man: man
+	$(INSTALL) -d -m 755 ../man
+	$(INSTALL) -m 644 $(man1) ../man
+	$(INSTALL) -m 644 $(man5) ../man
+	test -z "$(man7)" || $(INSTALL) -m 644 $(man7) ../man
+
+install-man: man
+	$(INSTALL) -d -m 755 $(DESTDIR)$(man1dir)
+	$(INSTALL) -d -m 755 $(DESTDIR)$(man5dir)
+	test -z "$(man7)" || $(INSTALL) -d -m 755 $(DESTDIR)$(man7dir)
+	$(INSTALL) -m 644 $(man1) $(DESTDIR)$(man1dir)
+	$(INSTALL) -m 644 $(man5) $(DESTDIR)$(man5dir)
+	test -z "$(man7)" || $(INSTALL) -m 644 $(man7) $(DESTDIR)$(man7dir)
+%.1 %.5 %.7 : %.txt
+	$(pandoc) -s -t man < $< > $@+ && mv $@+ $@
+
+clean::
+	$(RM) $(man1) $(man5) $(man7)

data/Documentation/yahns-rackup.txt

@@ -0,0 +1,152 @@
+% yahns-rackup(1) yahns user manual
+
+# NAME
+
+yahns-rackup - a rackup-like command to launch yahns
+
+# SYNOPSIS
+
+yahns-rackup [-E RACK_ENV] [-O worker_threads=NUM] [RACKUP_FILE]
+
+# DESCRIPTION
+
+A rackup(1)-like command to launch Rack applications using yahns.
+It is expected to start in your application root (APP_ROOT).
+
+# RACKUP FILE
+
+This defaults to \"config.ru\" in APP_ROOT.  It should be the same
+file used by rackup(1) and other Rack launchers, it uses the
+*Rack::Builder* DSL.
+
+# YAHNS OPTIONS
+-O client_timeout=SECONDS
+:   Defines the timeout expiring idle connections.
+
+    Increase this if your application takes longer to run than the
+    default timeout.  Lower this if you run out of FDs.
+
+    Default: 15 (seconds)
+
+-O listen=ADDRESS[,ADDRESS...]
+:   Listens on a given ADDRESS.  ADDRESS may be in the form of
+    HOST:PORT or PATH, HOST:PORT is taken to mean a TCP socket
+    and PATH is meant to be a path to a UNIX domain socket.
+    Defaults to "0.0.0.0:9292" (all addresses on TCP port 9292).
+    Multiple addresses may be separated with commas.
+
+-O stderr_path=PATHNAME
+:   Allow redirecting $stderr to a given path.  Unlike doing this from
+    the shell, this allows the yahns process to know the path its
+    writing to and rotate the file if it is used for logging.  The
+    file will be opened with the O_APPEND flag and writes
+    synchronized to the kernel (but not necessarily to _disk_) so
+    multiple processes can safely append to it.
+
+    If you are daemonizing and using the default logger, it is important
+    to specify this as errors will otherwise be lost to /dev/null.
+    Some applications/libraries may also triggering warnings that go to
+    stderr, and they will end up here.
+
+    Default: /dev/null if daemonized, controlling terminal if not
+
+-O stdout_path=PATH
+:   Same as stderr_path, except for $stdout.  Not many applications
+    write to $stdout, but any that do will have their output written here.
+    It is safe to point this to the same location a stderr_path.
+    Like stderr_path, this defaults to /dev/null when daemonized.
+
+    Default: /dev/null if daemonized, controlling terminal if not
+
+-O worker_threads=INTEGER
+:   This controls the number of threads for application processing.
+    Each queue has its own thread pool.  Increase this number if your
+    applications are able to use more threads effectively or if either
+    (or both) input/output buffering are disabled.  Lower this number if
+    you do not need multi-thread concurrency at all.
+
+    Default: 7
+
+# RACKUP OPTIONS
+-D, \--daemonize
+:   Run daemonized in the background.  The process is detached from
+    the controlling terminal and stdin is redirected to /dev/null.
+    Unless specified via stderr_path and stdout_path, stderr and stdout will
+    also be redirected to "/dev/null".
+
+-E, \--env RACK_ENV
+:   Run under the given RACK_ENV.  See the RACK ENVIRONMENT section
+    for more details.
+
+-o, \--host HOST
+:   Listen on a TCP socket belonging to HOST, default is
+    "0.0.0.0" (all addresses).
+    If specified multiple times on the command-line, only the
+    last-specified value takes effect.
+    This option only exists for compatibility with the rackup(1) command,
+    use of "-l"/"\--listen" switch is recommended instead.
+
+-p, \--port PORT
+:   Listen on the specified TCP PORT, default is 9292.
+    If specified multiple times on the command-line, only the last-specified
+    value takes effect.
+    This option only exists for compatibility with the rackup(1) command,
+    use of "-l"/"\--listen" switch is recommended instead.
+
+# RUBY OPTIONS
+-e, \--eval LINE
+:   Evaluate a LINE of Ruby code.  This evaluation happens
+    immediately as the command-line is being parsed.
+
+-d, \--debug
+:   Turn on debug mode, the $DEBUG variable is set to true.
+
+-w, \--warn
+:   Turn on verbose warnings, the $VERBOSE variable is set to true.
+
+-I, \--include PATH
+:   specify $LOAD_PATH.  PATH will be prepended to $LOAD_PATH.
+    The \':\' character may be used to delimit multiple directories.
+    This directive may be used more than once.  Modifications to
+    $LOAD_PATH take place immediately and in the order they were
+    specified on the command-line.
+
+-r, \--require LIBRARY
+:   require a specified LIBRARY before executing the application.  The
+    \"require\" statement will be executed immediately and in the order
+    they were specified on the command-line.
+
+# SIGNALS
+
+See yahns(1)
+
+# FILES
+
+See Rack documentation for a description of the rackup file format.
+
+# ENVIRONMENT VARIABLES
+
+The RACK_ENV variable is set by the aforementioned \-E switch.
+If RACK_ENV is already set, it will be used unless \-E is used.
+See rackup documentation for more details.
+
+# CONTACT
+
+All feedback welcome via plain-text mail to <yahns-public@rubyforge.org>\
+No subscription is necessary to post to the mailing list.
+
+# COPYRIGHT
+
+Copyright 2013, Eric Wong <normalperson@yhbt.net> and all contributors.\
+License: GPLv3 or later <http://www.gnu.org/licenses/gpl-3.0.txt>
+
+# SEE ALSO
+
+yahns(1), yahns_config(5)
+
+* *Rack::Builder* ri/RDoc
+* [Rack RDoc][1]
+* [Rackup HowTo][2]
+
+[1]: http://rack.rubyforge.org/doc/
+[2]: http://wiki.github.com/rack/rack/tutorial-rackup-howto

data/Documentation/yahns.txt

@@ -0,0 +1,68 @@
+% yahns(1) yahns user manual
+%
+
+# NAME
+
+yahns - multi-threaded, non-blocking application server for Ruby
+
+# SYNOPSYS
+
+yahns -c CONFIG_FILE [-D|--daemonize]
+
+# DESCRIPTION
+
+yahns(1) is the primary interface for launching a yahns application
+server.  The configuration file is documented in yahns_config(5).  yahns
+hosts Rack HTTP applications, but may support others in the future such
+as DRb.
+
+# SIGNALS
+
+The following UNIX signals may be sent to the running yahns process.
+If yahns is configured for worker_processes (optional), signals should
+only be sent to the master process.
+
+* INT/TERM/QUIT - graceful shutdown.  If repeated (any of these signals
+  is sent twice), shutdown occurs immediately.
+* USR1 - reopen all logs owned by the master and all workers.
+  This scans the Ruby ObjectSpace for all open File objects with the O_APPEND
+  file flag and buffering disabled (IO#sync==false)
+* USR2 - reexecute the running binary.  A separate QUIT should be sent to
+* HUP - if worker_processes are not used, this will reexecute the running
+  binary and gracefully exit the running process.  If worker_processes are
+  used, this will reload config file, app, and gracefully restart all workers
+* WINCH - gracefully stops workers but keep the master running.
+  This will only work for daemonized processes and only if the
+  worker_processes configuration directive is used.
+* TTIN - increment the number of worker processes by one
+  (only if the worker_processes directive is used)
+* TTOU - decrement the number of worker processes by one
+  (only if the worker_processes directive is used)
+
+# ENVIRONMENT
+
+yahns(1) itself requires no special environment variables.  However,
+environment variables such as RACK_ENV and RAILS_ENV can affect Rack and
+Rails applications it hosts.  Ruby and C library implementation-specific
+environment variables will also affect it.
+
+yahns will update the PWD (current working directory) env if the
+working_directory directive is set (see yahns_config(5)).
+
+# FILES
+
+See yahns_config(5) for documentation on the configuration file format.
+
+# CONTACT
+
+All feedback welcome via plain-text mail to <yahns-public@rubyforge.org>\
+No subscription is necessary to post to the mailing list.
+
+# COPYRIGHT
+
+Copyright 2013, Eric Wong <normalperson@yhbt.net> and all contributors.\
+License: GPLv3 or later <http://www.gnu.org/licenses/gpl-3.0.txt>
+
+# SEE ALSO
+
+yahns-rackup(1), yahns_config(5)

data/Documentation/yahns_config.txt

@@ -0,0 +1,563 @@
+% yahns_config(5) yahns user manual
+%
+
+# NAME
+
+yahns_config - configuration file description for yahns(1)
+
+# DESCRIPTION
+
+Since yahns is a Ruby application server, its configuration file is
+implemented in Ruby syntax, making it dependent on the version of
+Ruby it is running under.
+
+# TOP-LEVEL DIRECTIVES
+
+* app :TYPE, *APP_ARGUMENTS, &BLOCK
+
+    This defines an application context for yahns to run.  :TYPE defines
+    the type of application it runs.  yahns will eventually support
+    application types other than :rack, but for now, only :rack is
+    supported.
+
+    The &BLOCK given configures the which sockets the app listens on,
+    buffering and logging settings.
+
+    An app with the same :TYPE and APP_ARGUMENTS may be defined multiple
+    times with different &BLOCK contents (with different listeners and
+    buffering settings).
+
+    See the APP-BLOCK DIRECTIVES section for details on what goes into
+    the &BLOCK.
+
+    This directive may be specified multiple times for different or
+    identical applications.
+
+    If the "working_directory" directive is used, all app directives may
+    only be specified after setting "working_directory".
+
+    For Rack HTTP applications, see RACK APP ARGUMENTS for more
+    information.
+
+* before_exec &BLOCK
+
+    This runs &BLOCK before Kernel#exec (execve(2) wrapper).  The command
+    array to be passed to Kernel#exec may be modified within this hook:
+
+        before_exec do |cmd|
+          # you may modify ENV here inside the child process
+          ENV["MALLOC_ARENA_MAX"] = ENV["MALLOC_ARENA_TEST"] = "1"
+
+          # You may change to a different installation of Ruby or yahns
+          # by doing an in-place modification of cmd:
+          cmd.replace(%W(/another/install/of/yahns -c cfg.rb))
+        end
+
+    Default: (none)
+
+* client_expire_threshold {INTEGER|FLOAT}
+
+    yahns will start expiring idle clients when it hits this threshold.
+    If the threshold is a floating point number, it is that fraction of
+    the soft open file limit (RLIMIT_NOFILE ir `ulimit -S -n` in shell).
+    Thus if the soft open file limit is 1024 (a typical value) and the
+    client_expire_threshold is 0.3, yahns will start expiring clients once
+    it hits 307 clients (0.3 * 1024).
+
+    If given a positive integer, yahns will start expiring clients once it
+    its this absolute threshold of connected clients.
+
+    If given a negative integer, yahns will start expiring clients once it
+    reaches N clients away from the the soft file limit.  That is, if
+    client_expire_threshold is -666 and the soft open file limit is 1024,
+    it will start expiring once it hits 358 clients.
+
+    Clients are expired when the configured client_timeout for their
+    app context is hit.
+
+    Default: 0.5
+
+* logger LOGGER
+
+    Sets LOGGER as the default logger of the process.  The new
+    LOGGER must respond to the following methods:
+
+      debug, info, warn, error, fatal
+
+    The default logger will log its output to the path specified
+    by stderr_path.  If you're running yahns daemonized, then
+    you must specify a path to prevent error messages from going
+    to /dev/null
+
+    A per-APP &BLOCK logger may also be configured inside an app &BLOCK.
+
+    Default: Logger.new($stderr)
+
+* pid PATHNAME
+
+    Sets the path of the PID file for use with management/init scripts.
+
+    Default: none
+
+* queue [NAME] &BLOCK
+
+    As a top-level directive, this configures or defines a queue.
+    If no NAME is specified, a default queue (named :default) is
+    assumed.  See the QUEUE-LEVEL DIRECTIVES section for details.
+
+    A &BLOCK must be given if used as a top-level directive.  This
+    behaves slightly differently inside an app &BLOCK.  This may also
+    be given without a block to associate an app block with a named
+    queue.
+
+    Usually, only one queue is necessary.  Each queue corresponds to
+    an epoll descriptor and worker thread pool.
+
+    Default: NAME defaults to :default
+
+* stderr_path PATHNAME
+
+    Allow redirecting $stderr to a given path.  Unlike doing this from
+    the shell, this allows the yahns process to know the path its
+    writing to and rotate the file if it is used for logging.  The
+    file will be opened with the O_APPEND flag and writes
+    synchronized to the kernel (but not necessarily to _disk_) so
+    multiple processes can safely append to it.
+
+    If you are daemonizing and using the default logger, it is important
+    to specify this as errors will otherwise be lost to /dev/null.
+    Some applications/libraries may also triggering warnings that go to
+    stderr, and they will end up here.
+
+    Default: /dev/null if daemonized, controlling terminal if not
+
+* stdout_path PATHNAME
+
+    Same as stderr_path, except for $stdout.  Not many applications
+    write to $stdout, but any that do will have their output written here.
+    It is safe to point this to the same location a stderr_path.
+    Like stderr_path, this defaults to /dev/null when daemonized.
+
+    Default: /dev/null if daemonized, controlling terminal if not
+
+* working_directory PATHNAME
+
+    Sets the working directory for the process.  This ensures SIGUSR2 will
+    start a new instance of yahns in this directory.  This may be
+    a symlink, a common scenario for Capistrano users.  Unlike
+    all other yahns configuration directives, this binds immediately
+    for error checking and cannot be undone by unsetting it in the
+    configuration file and reloading.
+
+    This must be specified before any "app" directives
+
+    Default: / if daemonized, current working directory if not
+
+# QUEUE-LEVEL DIRECTIVES
+
+* max_events INTEGER
+
+    This controls the number of events a worker thread will fetch at
+    once via epoll_wait(2).  There is no good reason to change this
+    unless you use very few (e.g. 1) worker_threads.  Leaving this at
+    1 will give the fairest load balancing behavior with epoll.
+
+    Default: 1
+
+* worker_threads INTEGER
+
+    This controls the number of threads for application processing.
+    Each queue has its own thread pool.  Increase this number if your
+    applications are able to use more threads effectively or if either
+    (or both) input/output buffering are disabled.  Lower this number if
+    you do not need multi-thread concurrency at all.
+
+    Default: 7
+
+## APP-BLOCK DIRECTIVES
+
+* atfork_prepare, atfork_parent, atfork_child
+
+    These are identical to the methods defined in WORKER_PROCESSES-LEVEL
+    DIRECTIVES, however they are available inside the app blocks for
+    convenience in case it is easier to organize per-app hooks.
+
+    Default: (none)
+
+* check_client_connection BOOLEAN
+
+    When enabled, yahns will check the client connection by writing
+    the beginning of the HTTP headers before calling the application.
+
+    This can prevent calling the application for clients who have
+    disconnected while their connection was waiting for a free
+    worker thread.
+
+    This only affects clients connecting over Unix domain sockets and
+    TCP via loopback (127.*.*.*).  It is unlikely to detect disconnects
+    if the client is on a remote host (even on a fast LAN).
+
+    This has no effect for (rare) HTTP/0.9 clients.
+
+    Default: false
+
+* client_body_buffer_size INTEGER
+
+    This controls the maximum size of a request body before it is
+    buffered to the filesystem (instead of memory).  This has no effect
+    if input_buffering is false.  This also governs the size of an
+    individual read(2) system call when reading a request body.
+
+    Default: 8192 bytes (8 kilobytes)
+
+* client_header_buffer_size INTEGER
+
+    This controls the size of a single read(2) syscall for reading
+    client request headers.  Increase this as needed if your application
+    uses large cookies or long URLs.  Lowering this may reduce GC and
+    memory allocator overhead.
+
+    Default 4000 bytes
+
+* client_max_body_size {INTEGER|nil}
+
+    This controls the maximum request body size before a client is
+    rejected with an HTTP 413 error.
+
+    Setting this to nil will allow unlimited-sized inputs.
+
+    Default: 1048576 bytes (one megabyte)
+
+* client_timeout SECONDS
+
+    Defines the timeout expiring idle connections.
+
+    If input_buffering is false or :lazy, this defines the maximum
+    amount of time a worker thread will wait synchronously for a client
+    request body.
+
+    If output_buffering is false, this defines the maximm amount of
+    time a worker thread will wait synchronously for a client socket
+    to become writable.
+
+    It makes sense to lower this to a low value (e.g. 5 seconds) if
+    either output or input buffering are disabled.  The default value
+    of 15 seconds is suitable for configurations with both input and
+    output buffering enabled and assumes all application dispatch
+    finishes in less than 15 seconds.
+
+    Default: 15 (seconds)
+
+* errors {IO|PATHNAME}
+
+    For Rack applications, this controls the env["rack.errors"]
+    destination.  If given a PATHNAME, it will be a writable file
+    opened with O_APPEND without userspace buffering, making it suitable
+    for concurrent appends by multiple processes and threads, as well as
+    making it eligible for reopening via SIGUSR1 after log rotation.
+
+    Default: $stderr
+
+* input_buffering {:lazy|true|false}[, OPTIONS]
+
+    This controls buffering of the HTTP request body.
+
+    + true - fully buffers the request before application dispatch.  This is
+      most suitable for slow and untrusted clients which may trickle
+      the request to the server.
+
+    + :lazy - provides streaming, but rewindable input.  This is suitable
+      for fast, trusted clients and is fully-compatible with Rack 1.x
+      specifications.  :lazy buffering may also be suitable for slow and
+      untrusted clients if you are able and willing to run a queue with
+      many worker threads.
+
+    + false - disable input buffering completely.  This violates the
+      Rack 1.x spec and is only suitable for fast, trusted clients or
+      queues with many worker threads.
+
+    HTTP request headers are always buffered in memory.
+
+    Default: true
+
+    The following OPTIONS may be specified:
+
+      + tmpdir: DIRECTORY
+
+        Specify an alternative temporary directory of input_buffering is
+        :lazy or true.  This can be used in case the normal temporary
+        directory is too small or busy to be used for input buffering.
+
+        Default: Dir.tmpdir (usually from TMPDIR env or /tmp)
+
+* listen ADDRESS [, OPTIONS]
+
+    Adds an ADDRESS to the existing listener set.  May be specified more
+    than once.  ADDRESS may be an Integer port number for a TCP port, an
+    "IP_ADDRESS:PORT" for TCP listeners or a pathname for UNIX domain sockets.
+
+      listen 3000 # listen to port 3000 on all TCP interfaces
+      listen "127.0.0.1:3000"  # listen to port 3000 on the loopback interface
+      listen "/path/to/.unicorn.sock" # listen on the given Unix domain socket
+      listen "[::1]:3000" # listen to port 3000 on the IPv6 loopback interface
+
+    When using Unix domain sockets, be sure:
+    1) the path matches the one used by nginx
+    2) uses the same filesystem namespace as the nginx process
+    For systemd users using PrivateTmp=true (for either nginx or yahns),
+    this means Unix domain sockets must not be placed in /tmp
+
+    The following OPTIONS may be specified (but are generally not needed):
+
+      + backlog: INTEGER
+
+        This is the backlog of the listen(2) syscall.
+
+        Some operating systems allow negative values here to specify the
+        maximum allowable value.  In most cases, this number is only
+        recommendation and there are other OS-specific tunables and
+        variables that can affect this number.  See the listen(2)
+        syscall documentation of your OS for the exact semantics of
+        this.
+
+        If you are running unicorn on multiple machines, lowering this number
+        can help your load balancer detect when a machine is overloaded
+        and give requests to a different machine.
+
+        Default: 1024
+
+      + ipv6only: BOOLEAN
+
+        This option makes IPv6-capable TCP listeners IPv6-only and unable
+        to receive IPv4 queries on dual-stack systems.  A separate IPv4-only
+        listener is required if this is true.
+
+        Enabling this option for the IPv6-only listener and having a
+        separate IPv4 listener is recommended if you wish to support IPv6
+        on the same TCP port.  Otherwise, the value of env["REMOTE_ADDR"]
+        will appear as an ugly IPv4-mapped-IPv6 address for IPv4 clients
+        (e.g ":ffff:10.0.0.1" instead of just "10.0.0.1").
+
+        Default: Operating-system dependent
+
+      + sndbuf / rcvbuf: INTEGER
+
+        Maximum receive and send buffer sizes (in bytes) of sockets.
+
+        These correspond to the SO_RCVBUF and SO_SNDBUF settings which
+        can be set via the setsockopt(2) syscall.  Some kernels
+        (e.g. Linux 2.4+) have intelligent auto-tuning mechanisms and
+        there is no need (and it is sometimes detrimental) to specify them.
+
+        See the socket API documentation of your operating system
+        to determine the exact semantics of these settings and
+        other operating system-specific knobs where they can be
+        specified.
+
+        Defaults: operating system defaults
+
+      + reuseport: BOOLEAN
+
+        This enables multiple, independently-started yahns instances to
+        bind to the same port (as long as all the processes enable this).
+
+        This option must be used when yahns first binds the listen socket.
+        It cannot be enabled when a socket is inherited via SIGUSR2
+        (but it will remain on if inherited), and it cannot be enabled
+        directly via SIGHUP.
+
+        Note: there is a chance of connections being dropped if
+        one of the yahns instances is stopped while using this.
+
+        This is supported on *BSD systems and Linux 3.9 or later.
+
+        ref: https://lwn.net/Articles/542629/
+
+        Default: false (unset)
+
+      + threads: INTEGER
+
+        Used to control the number of threads blocking on the accept(2)
+        or 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
+
+      + umask: MODE
+
+        Sets the file mode creation mask for UNIX sockets.  If specified,
+        this is usually in octal notation.
+
+        Typically UNIX domain sockets are created with more liberal
+        file permissions than the rest of the application.  By default,
+        we create UNIX domain sockets to be readable and writable by
+        all local users to give them the same accessibility as
+        locally-bound TCP listeners.
+
+        This has no effect on TCP listeners.
+
+        Default: 0000 (world-read/writable)
+
+* logger LOGGER
+
+    Configures a logger within the current app &BLOCK.
+    This behaves the same as the logger directive described in
+    TOP-LEVEL DIRECTIVES
+
+    Default: uses the top-level logger
+
+* output_buffering BOOLEAN [, OPTIONS]
+
+    This enables or disables buffering of the HTTP response.  If enabled,
+    buffering is only performed lazily.  In other words, buffering only
+    happens if socket buffers (in the kernel) are filled up.
+
+    Disabling output buffering is only recommended if all clients
+    connecting to this application context are fast, trusted or
+    you are willing and able to run many worker threads.
+
+    If output buffering is disabled, client_timeout controls the maximum
+    amount of time a worker thread will wait synchronously.
+
+    Default: true
+
+    The following OPTIONS may be specified:
+
+      + tmpdir: DIRECTORY
+
+        Specify an alternative temporary directory of output_buffering is
+        enabled.  This can be used in case the normal temporary directory
+        is too small or busy to be used for output buffering.
+
+        Default: Dir.tmpdir (usually from TMPDIR env or /tmp)
+
+* persistent_connections BOOLEAN
+
+    Enable or disables persistent connections and pipelining for HTTP
+    connections.  Persistent connections only expire when the global
+    client_expire_threshold is hit and a client hits its client_timeout.
+
+    Default: true
+
+* user USER [,GROUP]
+
+    Runs application process(es) as the specified USER and GROUP.
+
+    If using worker_processes, this only affects the workers and the
+    master stays running as the user who started it.  This switch will
+    occur before calling the atfork_child hook(s).
+
+    GROUP is optional and will not change if unspecified.
+
+    Default: none (no user switching is done)
+
+* queue [NAME or &BLOCK]
+
+    If given a NAME-only, this will associate this app &BLOCK with an
+    existing queue.
+
+    If given a &BLOCK-only, this will create an anonymous queue for this
+    application context only.  If given a &BLOCK, this takes the same
+    parameters (worker_threads and max_events) as described in
+    QUEUE-LEVEL DIRECTIVES.
+
+    NAME and &BLOCK may not be combined inside an app &BLOCK.
+
+    Default: uses the global, :default queue if none is specified
+
+* shutdown_timeout SECONDS
+
+    This defines the timeout for gracefully exiting the process if there
+    are still connected clients.  This should generally be higher or equal
+    to the app with the highest client_timeout value.
+
+    Increase this if your application has slow endpoints which may take
+    longer than the default timeout.
+
+    Default: max client_timeout value of all apps in the process
+
+* worker_processes INTEGER [&BLOCK]
+
+    This directive allows yahns to use a master/worker configuration to
+    use multiple processes.  Specifying any numeric value (including 1)
+    here means yahns will enable yahns to use a master/worker process
+    model instead of a single process.
+
+    If an optional &BLOCK is given, it may be used to configure
+    pthread_atfork(3)-style hooks.  See WORKER_PROCESSES-LEVEL DIRECTIVES
+    for details.
+
+    Default: nil (single process, no master/worker separation)
+
+## WORKER_PROCESSES-LEVEL DIRECTIVES
+
+Note: all of the atfork_* hooks described here are available inside the
+"app" blocks, too.
+
+* atfork_prepare &BLOCK
+
+    This &BLOCK is executed in the parent before fork(2) operation.
+    This may be useful for app directives which specify "preload: true"
+    to disconnect from databases or otherwise close open file descriptors
+    to prevent them from being shared with the children.
+
+    Default: none
+
+* atfork_parent &BLOCK
+
+    This &BLOCK is executed in the parent after the fork(2) operation.
+    This may not be useful, but exists in case somebody finds a use for it.
+
+    Default: none
+
+* atfork_child &BLOCK
+
+    This &BLOCK is executed in the child after the fork(2) operation.
+
+    This may be useful for app directives which specify "preload: true"
+    to reconnect to databases or reopen closed file descriptors which
+    were closed in the atfork_prepare hook.
+
+    Default: none
+
+# RACK APP ARGUMENTS
+
+Rack applications take a PATHNAME to the rackup(1) config file (e.g.
+"config.ru") as its first argument.
+
+The only supported keyword argument is the preload: BOOLEAN.
+
+preload: only makes sense if worker_processes are configured.
+Preloading an app allows memory to be saved under a copy-on-write GC,
+but will often require atfork_* hooks to be registered when configuring
+worker_processes.  preload: defaults to false for maximum out-of-the-box
+compatibility.
+
+## RACK APP EXAMPLE
+
+    app(:rack, "/path/to/config.ru", preload: false) do
+      # APP-BLOCK DIRECTIVES GO HERE
+    end
+
+# EXAMPLES
+
+See the examples/ directory in the git source tree.
+
+    git clone git://yhbt.net/yahns.git
+
+# COPYRIGHT
+
+Copyright 2013, Eric Wong <normalperson@yhbt.net> and all contributors.\
+License: GPLv3 or later <http://www.gnu.org/licenses/gpl-3.0.txt>
+
+# SEE ALSO
+
+yahns(1)