about summary refs log tree commit homepage
diff options
context:
space:
mode:
authorEric Wong <normalperson@yhbt.net>2009-04-03 00:09:16 -0700
committerEric Wong <normalperson@yhbt.net>2009-04-03 02:16:51 -0700
commit539ca9a0efc692edde5448d3e4007d35372e033d (patch)
tree426e62a71fa3f54c7e9e3700b554804a92e438ec
parentff59e34b6957bc6da2ac3e6c1453adcac9f591b4 (diff)
downloadunicorn-539ca9a0efc692edde5448d3e4007d35372e033d.tar.gz
Reword and expand a bit
-rw-r--r--DESIGN24
-rw-r--r--README14
-rw-r--r--SIGNALS15
3 files changed, 34 insertions, 19 deletions
diff --git a/DESIGN b/DESIGN
index 8f8c63d..3543d9e 100644
--- a/DESIGN
+++ b/DESIGN
@@ -37,10 +37,11 @@
 
 * The number of worker processes should be scaled to the number of
   CPUs, memory or even spindles you have.  If you have an existing
-  Mongrel cluster, using the same amount of processes should work.
-  Let a full-HTTP-request-buffering reverse proxy like nginx manage
-  concurrency to thousands of slow clients for you.  Unicorn scaling
-  should only be concerned about limits of your backend system(s).
+  Mongrel cluster on a single-threaded app, using the same amount of
+  processes should work.  Let a full-HTTP-request-buffering reverse
+  proxy like nginx manage concurrency to thousands of slow clients for
+  you.  Unicorn scaling should only be concerned about limits of your
+  backend system(s).
 
 * Load balancing between worker processes is done by the OS kernel.
   All workers share a common set of listener sockets and does
@@ -56,8 +57,8 @@
 
 * Blocking I/O is used for clients.  This allows a simpler code path
   to be followed within the Ruby interpreter and fewer syscalls.
-  Applications that use threads should continue to work if Unicorn
-  is serving LAN or localhost clients.
+  Applications that use threads continue to work if Unicorn
+  is only serving LAN or localhost clients.
 
 * Timeout implementation is done via fchmod(2) in each worker
   on a shared file descriptor to update st_ctime on the inode.
@@ -67,8 +68,9 @@
   pwrite(2)/pread(2) are supported by base MRI, nor are they as
   portable on UNIX systems as fchmod(2).
 
-* SIGKILL is used to terminate the timed-out workers as reliably
-  as possible on a UNIX system.
+* SIGKILL is used to terminate the timed-out workers from misbehaving apps
+  as reliably as possible on a UNIX system.  The default timeout is a
+  generous 60 seconds (same default as in Mongrel).
 
 * The poor performance of select() on large FD sets is avoided
   as few file descriptors are used in each worker.
@@ -81,5 +83,7 @@
   the master to its death.
 
 * There is never any explicit real-time dependency or communication
-  between the worker processes themselves nor to the master process.
-  Synchronization is handled entirely by the OS kernel.
+  between the worker processes nor to the master process.
+  Synchronization is handled entirely by the OS kernel and shared
+  resources are never accessed by the worker when it is servicing
+  a client.
diff --git a/README b/README
index 4c7d1ab..d620b7d 100644
--- a/README
+++ b/README
@@ -21,13 +21,15 @@ and DESIGN documents for more details regarding this.
 
 * Does not care if your application is thread-safe or not, workers
   all run within their own isolated address space and only serve one
-  client at a time...
+  client at a time.
 
 * Supports all Rack applications, along with pre-Rack versions of
   Ruby on Rails via a Rack wrapper.
 
-* Builtin log rotation of all log files in your application via USR1
-  signal.
+* Builtin reopening of all log files in your application via
+  USR1 signal.  This allows logrotate to rotate files atomically
+  and quickly via rename instead of the racy and slow
+  copytruncate method.
 
 * nginx-style binary re-execution without losing connections.
   You can upgrade Unicorn, your entire application, libraries
@@ -35,10 +37,12 @@ and DESIGN documents for more details regarding this.
   installed in the same path.
 
 * before_fork and after_fork hooks in case your application
-  has special needs when dealing with forked processes.
+  has special needs when dealing with forked processes.  These
+  should not be needed when the "preload_app" directive is
+  false (the default).
 
 * Can be used with copy-on-write-friendly memory management
-  to save memory.
+  to save memory (by setting "preload_app" to true).
 
 * Able to listen on multiple interfaces including UNIX sockets,
   each worker process can also bind to a private port via the
diff --git a/SIGNALS b/SIGNALS
index 671e8a5..fc0fa31 100644
--- a/SIGNALS
+++ b/SIGNALS
@@ -7,7 +7,7 @@ processes are documented here as well.
 === Master Process
 
  * HUP - reload config file and gracefully restart all workers
-   If preload_app is false (the default), the application code
+   If "preload_app" is false (the default), the application code
    will be reloaded when workers are restarted as well.
 
  * INT/TERM - quick shutdown, kills all workers immediately
@@ -31,12 +31,19 @@ Sending signals directly to the worker processes should not normally be
 needed.  If the master process is running, any exited worker will be
 automatically respawned.
 
- * INT/TERM - quick shutdown, immediately exit
+ * INT/TERM - Quick shutdown, immediately exit.
+   Unless WINCH has been sent to the master (or the master is killed),
+   the master process will respawn a worker to replace this one.
 
- * QUIT - gracefully exit after finishing the current request
+ * QUIT - Gracefully exit after finishing the current request.
+   Unless WINCH has been sent to the master (or the master is killed),
+   the master process will respawn a worker to replace this one.
 
- * USR1 - reopen all logs owned by the worker process
+ * USR1 - Reopen all logs owned by the worker process.
    See Unicorn::Util.reopen_logs for what is considered a log.
+   Log files are not reopened until it is done processing
+   the current request, so multiple log lines for one request
+   (as done by Rails) will not be split across multiple logs.
 
 === Procedure to replace a running unicorn executable