about summary refs log tree commit homepage
path: root/README
diff options
context:
space:
mode:
authorEric Wong <normalperson@yhbt.net>2013-10-18 10:28:18 +0000
committerEric Wong <normalperson@yhbt.net>2013-10-18 10:28:18 +0000
commitab067831e707b191d6dfdcd01de1f1d85fc90d05 (patch)
treeb02861eb1521fb325ee4e1d91e1a194ca73e7a9e /README
downloadyahns-ab067831e707b191d6dfdcd01de1f1d85fc90d05.tar.gz
Diffstat (limited to 'README')
-rw-r--r--README127
1 files changed, 127 insertions, 0 deletions
diff --git a/README b/README
new file mode 100644
index 0000000..82fad54
--- /dev/null
+++ b/README
@@ -0,0 +1,127 @@
+yahns - sleepy, multi-threaded, non-blocking application server for Ruby
+------------------------------------------------------------------------
+
+A Free Software, multi-threaded, non-blocking network application server
+designed for low _idle_ power consumption.  It is primarily optimized
+for applications with occasional users which see little or no traffic.
+yahns currently hosts Rack/HTTP applications, but may eventually support
+other application types.  Unlike some existing servers, yahns is
+extremely sensitive to fatal bugs in the applications it hosts.
+
+Features
+--------
+
+* _zero_ wakeups when all clients are idle
+* idle client connections may live forever if there is no FD pressure
+* suitable for slow clients, fast clients, or a mixture of both
+* HTTP/0.9 support
+* HTTP/1.1 persistent connections and pipelining
+* decodes HTTP chunked encoding for requests
+* parses HTTP/1.1 trailers in requests
+* supports streaming responses with lazy buffering for slow clients
+* optional streaming input for fast clients
+* able to host multiple applications with different settings
+* uses epoll to scale to many idle connections
+* abuses epoll as a load balancer between threads inside a process
+* optional multi-process support (in addition to threads)
+* fairly balances new clients between multiple processes (on Linux)
+
+Supported Platforms
+-------------------
+
+yahns is developed primarily for modern GNU/Linux systems.
+
+We may support kqueue for FreeBSD/OpenBSD/NetBSD if there is significant
+interest.  Non-Free systems/dependencies will never be supported
+
+Supported Ruby implementations:
+* (Matz) Ruby 2.0 or later
+* Rubinius 2.0 or later (planned)
+
+Contact
+-------
+
+We are happy to see feedback of all types via plain-text email.
+Please send comments, user/dev discussion, patches, bug reports,
+and pull requests to Eric Wong at: normalperson@yhbt.net
+
+Public mailing list coming soon.
+
+This README is our homepage, we would rather be working on HTTP servers
+all day than worrying about the next browser vulnerability because
+HTML/CSS/JS is too complicated for us.
+
+* http://yahns.yhbt.net/README
+
+Hacking
+-------
+
+We use git and follow the same development model as git itself
+(mailing list-oriented, benevolent dictator).
+
+  git clone git://yahns.yhbt.net/yahns
+
+Please use git-format-patch(1) and git-send-email(1) distributed with
+the git(7) suite for generating and sending patches.  Please format
+pull requests with the git-request-pull(1) script (also distributed
+with git(7)) and send them via email.
+
+See http://www.git-scm.com/ for more information on git.
+
+Design
+------
+
+yahns is designed to optimimally use multiple threads with non-blocking I/O.
+The event loop is not a traditional single-threaded design with a mutex
+slapped on as an afterthought, but designed from the beginning to utilize
+multiple threads.
+
+* two classes of long-lived, persistent threads
+  1. blocking acceptors
+  2. non-blocking event loop workers
+* epoll acts as a queue (by using one-shot notifications)
+* acceptors accept new clients and put them in the epoll "queue"
+* workers pull clients off the queue, rearming them to epoll on EAGAIN
+
+The end result is clients transition freely and fairly between threads
+and will always be able to find the next idle thread to run on.
+
+This design works with kqueue, too, and we will support kqueue if there
+is interest.  In fact, got our design inspiration from the name "kqueue"
+when working on another project.  We may also support libkqueue:
+
+    http://sourceforge.net/projects/libkqueue/
+
+In addition to multiple threads, yahns optionally supports multiple
+processes to work around low FD limits as well as contention in the:
+
+* kernel (socket (de)allocation from accept/close)
+* standard C library (malloc/free)
+* Ruby VM (GVL, GC)
+* application it hosts
+
+Copyright
+---------
+
+Copyright 2013, Eric Wong <normalperson@yhbt.net> and all contributors.
+License: GPLv3 or later <https://www.gnu.org/licenses/gpl-3.0.txt>
+
+yahns is copyrighted Free Software by all contributors, see logs in
+revision control for names and email addresses of all of them.  yahns
+contains code from Mongrel, unicorn, and Rainbows! which may also be
+licensed under the GPLv2 or later.
+
+yahns is free software; you can redistribute it and/or modify it
+under the terms of the GNU General Public License as published by the
+Free Software Foundation; either version 3 of the License, or (at your
+option) any later version.
+
+yahns is distributed in the hope that it will be useful, but WITHOUT ANY
+WARRANTY; without even the implied warranty of MERCHANTABILITY or
+FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+for more details.
+
+You should have received a copy of the GNU General Public License along
+with this program; if not, see https://www.gnu.org/licenses/gpl-3.0.txt
+
+lrg nabgure ubeevoyl-anzrq freire :>