From 539ca9a0efc692edde5448d3e4007d35372e033d Mon Sep 17 00:00:00 2001 From: Eric Wong Date: Fri, 3 Apr 2009 00:09:16 -0700 Subject: Documentation updates Reword and expand a bit --- DESIGN | 24 ++++++++++++++---------- README | 14 +++++++++----- SIGNALS | 15 +++++++++++---- 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 -- cgit v1.2.3-24-ge0c7