passenger 2.0.3 → 2.0.4

data/Rakefile

@@ -24,10 +24,12 @@ require 'rake/extensions'
 require 'rake/cplusplus'
 require 'passenger/platform_info'
 
+verbose true
+
 ##### Configuration
 
 # Don't forget to edit Configuration.h too
-PACKAGE_VERSION = "2.0.3"
+PACKAGE_VERSION = "2.0.4"
 OPTIMIZE = ["yes", "on", "true"].include?(ENV['OPTIMIZE'])
 
 include PlatformInfo
@@ -35,6 +37,7 @@ APXS2.nil? and raise "Could not find 'apxs' or 'apxs2'."
 APACHE2CTL.nil? and raise "Could not find 'apachectl' or 'apache2ctl'."
 HTTPD.nil? and raise "Could not find the Apache web server binary."
 APR_FLAGS.nil? and raise "Could not find Apache Portable Runtime (APR)."
+APU_FLAGS.nil? and raise "Could not find Apache Portable Runtime Utility (APU)."
 
 CXX = "g++"
 THREADING_FLAGS = "-D_REENTRANT"
@@ -107,7 +110,7 @@ end
 ##### Apache module
 
 class APACHE2
-	CXXFLAGS = "-I.. -fPIC #{OPTIMIZATION_FLAGS} #{APR_FLAGS} #{APXS2_FLAGS} #{CXXFLAGS}"
+	CXXFLAGS = "-I.. -fPIC #{OPTIMIZATION_FLAGS} #{APR_FLAGS} #{APU_FLAGS} #{APXS2_FLAGS} #{::CXXFLAGS}"
 	OBJECTS = {
 		'Configuration.o' => %w(Configuration.cpp Configuration.h),
 		'Bucket.o' => %w(Bucket.cpp Bucket.h),
@@ -184,8 +187,8 @@ end
 ##### Unit tests
 
 class TEST
-	CXXFLAGS = ::CXXFLAGS + " -Isupport -DTESTING_SPAWN_MANAGER -DTESTING_APPLICATION_POOL "
-	AP2_FLAGS = "-I../ext/apache2 -I../ext #{APR_FLAGS}"
+	CXXFLAGS = "#{::CXXFLAGS} -Isupport -DTESTING_SPAWN_MANAGER -DTESTING_APPLICATION_POOL "
+	AP2_FLAGS = "-I../ext/apache2 -I../ext #{APR_FLAGS} #{APU_FLAGS}"
 	
 	AP2_OBJECTS = {
 		'CxxTestMain.o' => %w(CxxTestMain.cpp),
@@ -368,7 +371,7 @@ subdir 'doc' do
 	end
 end
 
-Rake::RDocTask.new do |rd|
+Rake::RDocTask.new(:clobber_rdoc => "rdoc:clobber", :rerdoc => "rdoc:force") do |rd|
 	rd.main = "README"
 	rd.rdoc_dir = "doc/rdoc"
 	rd.rdoc_files.include("README", "DEVELOPERS.TXT",

data/bin/passenger-install-apache2-module

@@ -47,6 +47,7 @@ class Installer
 		Dependencies::Apache2,
 		Dependencies::Apache2_DevHeaders,
 		Dependencies::APR_DevHeaders,
+		Dependencies::APU_DevHeaders,
 		Dependencies::FastThread,
 		Dependencies::Rack
 	]
@@ -187,7 +188,11 @@ private
 		color_puts '<banner>Compiling and installing Apache 2 module...</banner>'
 		puts "cd #{PASSENGER_ROOT}"
 		puts "rake clean apache2"
-		return system("rake", "clean", "apache2")
+		if ENV['TRACE']
+			return system("rake", "--trace", "clean", "apache2")
+		else
+			return system("rake", "clean", "apache2")
+		end
 	end
 	
 	def show_apache2_config_snippets

data/doc/ApplicationPool algorithm.txt

@@ -119,6 +119,11 @@ information:
      for all keys app_root in restart_times:
         apps.has_key(app_root)
 
+- waiting_on_global_queue: integer
+  If global queuing mode is enabled, then when get() is waiting for a backend
+  process to become idle, this variable will be incremented. When get() is done
+  waiting, this variable will be decremented.
+
 - app_instance_count: map[string => unsigned int]
   Maps an application root to the number of spawned applications.
 
@@ -197,13 +202,22 @@ function spawn_or_use_existing(app_root):
 			# All apps are active, and the pool is full. 
 			#  -OR-
 			# All apps are active and the number of max instances
-			# spawned for this application has been reached.
+			# spawned for this application domain has been reached.
 			#
 			# We're not allowed to spawn a new application instance.
-			# So we connect to an already active application. This connection
-			# will be put into that application's queue.
-			container = a container in _list_ with the smallest _session_ value
-			list.move_to_back(container.iterator)
+			if use_global_queue:
+				# So we wait until _active_ has changed, then
+				# we restart this function and try again.
+				waiting_on_global_queue++
+				wait until _active_ has changed
+				waiting_on_global_queue--
+				goto beginning of function
+			else:
+				# So we connect to an already active application.
+				# This connection will be put into that
+				# application's private queue.
+				container = a container in _list_ with the smallest _session_ value
+				list.move_to_back(container.iterator)
 		else:
 			# All apps are active, but the pool hasn't reached its
 			# maximum yet. So we spawn a new app.
@@ -221,6 +235,10 @@ function spawn_or_use_existing(app_root):
 		wait until
 		  (active < max) and
 		  (max_per_app == 0 or app_instance_count[app_root] < max_per_app)
+		# FIXME: there's a possible concurrency issue here. After
+		# waiting and having reacquired the lock, the state might have
+		# been completely changed, and there may now exist an instance
+		# of this application domain.
 		if count == max:
 			# Here we are in a though situation. There are several
 			# apps which are inactive, and none of them have

data/doc/Architectural overview.html

@@ -0,0 +1,778 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
+    "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
+<meta name="generator" content="AsciiDoc 8.2.7" />
+<style type="text/css">
+/* Debug borders */
+p, li, dt, dd, div, pre, h1, h2, h3, h4, h5, h6 {
+/*
+  border: 1px solid red;
+*/
+}
+
+body {
+  margin: 1em 5% 1em 5%;
+}
+
+a {
+  color: blue;
+  text-decoration: underline;
+}
+a:visited {
+  color: fuchsia;
+}
+
+em {
+  font-style: italic;
+  color: navy;
+}
+
+strong {
+  font-weight: bold;
+  color: #083194;
+}
+
+tt {
+  color: navy;
+}
+
+h1, h2, h3, h4, h5, h6 {
+  color: #527bbd;
+  font-family: sans-serif;
+  margin-top: 1.2em;
+  margin-bottom: 0.5em;
+  line-height: 1.3;
+}
+
+h1, h2, h3 {
+  border-bottom: 2px solid silver;
+}
+h2 {
+  padding-top: 0.5em;
+}
+h3 {
+  float: left;
+}
+h3 + * {
+  clear: left;
+}
+
+div.sectionbody {
+  font-family: serif;
+  margin-left: 0;
+}
+
+hr {
+  border: 1px solid silver;
+}
+
+p {
+  margin-top: 0.5em;
+  margin-bottom: 0.5em;
+}
+
+ul, ol, li > p {
+  margin-top: 0;
+}
+
+pre {
+  padding: 0;
+  margin: 0;
+}
+
+span#author {
+  color: #527bbd;
+  font-family: sans-serif;
+  font-weight: bold;
+  font-size: 1.1em;
+}
+span#email {
+}
+span#revision {
+  font-family: sans-serif;
+}
+
+div#footer {
+  font-family: sans-serif;
+  font-size: small;
+  border-top: 2px solid silver;
+  padding-top: 0.5em;
+  margin-top: 4.0em;
+}
+div#footer-text {
+  float: left;
+  padding-bottom: 0.5em;
+}
+div#footer-badges {
+  float: right;
+  padding-bottom: 0.5em;
+}
+
+div#preamble,
+div.tableblock, div.imageblock, div.exampleblock, div.verseblock,
+div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock,
+div.admonitionblock {
+  margin-right: 10%;
+  margin-top: 1.5em;
+  margin-bottom: 1.5em;
+}
+div.admonitionblock {
+  margin-top: 2.5em;
+  margin-bottom: 2.5em;
+}
+
+div.content { /* Block element content. */
+  padding: 0;
+}
+
+/* Block element titles. */
+div.title, caption.title {
+  color: #527bbd;
+  font-family: sans-serif;
+  font-weight: bold;
+  text-align: left;
+  margin-top: 1.0em;
+  margin-bottom: 0.5em;
+}
+div.title + * {
+  margin-top: 0;
+}
+
+td div.title:first-child {
+  margin-top: 0.0em;
+}
+div.content div.title:first-child {
+  margin-top: 0.0em;
+}
+div.content + div.title {
+  margin-top: 0.0em;
+}
+
+div.sidebarblock > div.content {
+  background: #ffffee;
+  border: 1px solid silver;
+  padding: 0.5em;
+}
+
+div.listingblock {
+  margin-right: 0%;
+}
+div.listingblock > div.content {
+  border: 1px solid silver;
+  background: #f4f4f4;
+  padding: 0.5em;
+}
+
+div.quoteblock {
+  padding-left: 2.0em;
+}
+div.quoteblock > div.attribution {
+  padding-top: 0.5em;
+  text-align: right;
+}
+
+div.verseblock {
+  padding-left: 2.0em;
+}
+div.verseblock > div.content {
+  white-space: pre;
+}
+div.verseblock > div.attribution {
+  padding-top: 0.75em;
+  text-align: left;
+}
+/* DEPRECATED: Pre version 8.2.7 verse style literal block. */
+div.verseblock + div.attribution {
+  text-align: left;
+}
+
+div.admonitionblock .icon {
+  vertical-align: top;
+  font-size: 1.1em;
+  font-weight: bold;
+  text-decoration: underline;
+  color: #527bbd;
+  padding-right: 0.5em;
+}
+div.admonitionblock td.content {
+  padding-left: 0.5em;
+  border-left: 2px solid silver;
+}
+
+div.exampleblock > div.content {
+  border-left: 2px solid silver;
+  padding: 0.5em;
+}
+
+div.imageblock div.content { padding-left: 0; }
+div.imageblock img { border: 1px solid silver; }
+span.image img { border-style: none; }
+
+dl {
+  margin-top: 0.8em;
+  margin-bottom: 0.8em;
+}
+dt {
+  margin-top: 0.5em;
+  margin-bottom: 0;
+  font-style: normal;
+}
+dd > *:first-child {
+  margin-top: 0.1em;
+}
+
+ul, ol {
+    list-style-position: outside;
+}
+div.olist > ol {
+  list-style-type: decimal;
+}
+div.olist2 > ol {
+  list-style-type: lower-alpha;
+}
+
+div.tableblock > table {
+  border: 3px solid #527bbd;
+}
+thead {
+  font-family: sans-serif;
+  font-weight: bold;
+}
+tfoot {
+  font-weight: bold;
+}
+
+div.hlist {
+  margin-top: 0.8em;
+  margin-bottom: 0.8em;
+}
+div.hlist td {
+  padding-bottom: 15px;
+}
+td.hlist1 {
+  vertical-align: top;
+  font-style: normal;
+  padding-right: 0.8em;
+}
+td.hlist2 {
+  vertical-align: top;
+}
+
+@media print {
+  div#footer-badges { display: none; }
+}
+
+div#toctitle {
+  color: #527bbd;
+  font-family: sans-serif;
+  font-size: 1.1em;
+  font-weight: bold;
+  margin-top: 1.0em;
+  margin-bottom: 0.1em;
+}
+
+div.toclevel1, div.toclevel2, div.toclevel3, div.toclevel4 {
+  margin-top: 0;
+  margin-bottom: 0;
+}
+div.toclevel2 {
+  margin-left: 2em;
+  font-size: 0.9em;
+}
+div.toclevel3 {
+  margin-left: 4em;
+  font-size: 0.9em;
+}
+div.toclevel4 {
+  margin-left: 6em;
+  font-size: 0.9em;
+}
+/* Workarounds for IE6's broken and incomplete CSS2. */
+
+div.sidebar-content {
+  background: #ffffee;
+  border: 1px solid silver;
+  padding: 0.5em;
+}
+div.sidebar-title, div.image-title {
+  color: #527bbd;
+  font-family: sans-serif;
+  font-weight: bold;
+  margin-top: 0.0em;
+  margin-bottom: 0.5em;
+}
+
+div.listingblock div.content {
+  border: 1px solid silver;
+  background: #f4f4f4;
+  padding: 0.5em;
+}
+
+div.quoteblock-attribution {
+  padding-top: 0.5em;
+  text-align: right;
+}
+
+div.verseblock-content {
+  white-space: pre;
+}
+div.verseblock-attribution {
+  padding-top: 0.75em;
+  text-align: left;
+}
+
+div.exampleblock-content {
+  border-left: 2px solid silver;
+  padding-left: 0.5em;
+}
+
+/* IE6 sets dynamically generated links as visited. */
+div#toc a:visited { color: blue; }
+
+/* Because IE6 child selector is broken. */
+div.olist2 ol {
+  list-style-type: lower-alpha;
+}
+div.olist2 div.olist ol {
+  list-style-type: decimal;
+}
+</style>
+<script type="text/javascript">
+/*<![CDATA[*/
+window.onload = function(){generateToc(3)}
+/* Author: Mihai Bazon, September 2002
+ * http://students.infoiasi.ro/~mishoo
+ *
+ * Table Of Content generator
+ * Version: 0.4
+ *
+ * Feel free to use this script under the terms of the GNU General Public
+ * License, as long as you do not remove or alter this notice.
+ */
+
+ /* modified by Troy D. Hanson, September 2006. License: GPL */
+ /* modified by Stuart Rackham, October 2006. License: GPL */
+
+function getText(el) {
+  var text = "";
+  for (var i = el.firstChild; i != null; i = i.nextSibling) {
+    if (i.nodeType == 3 /* Node.TEXT_NODE */) // IE doesn't speak constants.
+      text += i.data;
+    else if (i.firstChild != null)
+      text += getText(i);
+  }
+  return text;
+}
+
+function TocEntry(el, text, toclevel) {
+  this.element = el;
+  this.text = text;
+  this.toclevel = toclevel;
+}
+
+function tocEntries(el, toclevels) {
+  var result = new Array;
+  var re = new RegExp('[hH]([2-'+(toclevels+1)+'])');
+  // Function that scans the DOM tree for header elements (the DOM2
+  // nodeIterator API would be a better technique but not supported by all
+  // browsers).
+  var iterate = function (el) {
+    for (var i = el.firstChild; i != null; i = i.nextSibling) {
+      if (i.nodeType == 1 /* Node.ELEMENT_NODE */) {
+        var mo = re.exec(i.tagName)
+        if (mo)
+          result[result.length] = new TocEntry(i, getText(i), mo[1]-1);
+        iterate(i);
+      }
+    }
+  }
+  iterate(el);
+  return result;
+}
+
+// This function does the work. toclevels = 1..4.
+function generateToc(toclevels) {
+  var toc = document.getElementById("toc");
+  var entries = tocEntries(document.getElementsByTagName("body")[0], toclevels);
+  for (var i = 0; i < entries.length; ++i) {
+    var entry = entries[i];
+    if (entry.element.id == "")
+      entry.element.id = "toc" + i;
+    var a = document.createElement("a");
+    a.href = "#" + entry.element.id;
+    a.appendChild(document.createTextNode(entry.text));
+    var div = document.createElement("div");
+    div.appendChild(a);
+    div.className = "toclevel" + entry.toclevel;
+    toc.appendChild(div);
+  }
+  if (entries.length == 0)
+    document.getElementById("header").removeChild(toc);
+}
+/*]]>*/
+</script>
+<title>Passenger architectural overview</title>
+</head>
+<body>
+<div id="header">
+<h1>Passenger architectural overview</h1>
+<div id="toc">
+  <div id="toctitle">Table of Contents</div>
+  <noscript><p><b>JavaScript must be enabled in your browser to display the table of contents.</b></p></noscript>
+</div>
+</div>
+<div id="preamble">
+<div class="sectionbody">
+<div class="para"><p>This document describes Passenger's architure in a global way. The purpose of
+this document is to lower the barrier to entry for new contributors, as well
+as to explain (some of the) design choices that we have made.</p></div>
+<div class="para"><p>Or it can be a fun read for people who just want to know how Passenger works.</p></div>
+</div>
+</div>
+<h2 id="_about_the_involved_technologies">1. About the involved technologies</h2>
+<div class="sectionbody">
+<h3 id="typical_web_applications">1.1. Typical web applications</h3><div style="clear:left"></div>
+<div class="para"><p>Before we describe Passenger, it is important to understand how typical web
+applications work, from the point of view of someone who wants to connect the
+application to a web server.</p></div>
+<div class="para"><p>A typical, isolated, web application accepts an HTTP request from some I/O
+channel, processes it internally, and outputs an HTTP response, which is sent
+back to the client. This is done in a loop, until the application is commanded
+to exit. This does not necessarily mean that the web application speaks HTTP
+directly: it just means that the web application accepts some kind of
+representation of an HTTP request.</p></div>
+<div class="para"><p><span class="image">
+<img src="images/typical_isolated_web_application.png" alt="Architecture of a typical web application in isolation" title="Architecture of a typical web application in isolation" />
+</span></p></div>
+<div class="para"><p>Few web applications are accessible directly by HTTP clients. Common setups
+are:</p></div>
+<div class="olist"><ol>
+<li>
+<p>
+The web application is contained in an application server. This application
+server may or may not be able to contain multiple web applications. The
+application server is then connected to the web server. The web server
+dispatches requests to the application server, which in turn dispatches
+requests to the correct web application, in a format that the web application
+understands. Conversely, HTTP responses outputted by the web application are
+sent to the application server, which in turn sends them to the web server,
+and eventually to the HTTP client.
+</p>
+<div class="para"><p>A typical example of such a setup is a J2EE application, contained in the
+Tomcat web server, behind the Apache web server.</p></div>
+</li>
+<li>
+<p>
+The web application is contained in a web server. In this case, the web
+server acts like an application server. This is the case for PHP applications,
+on Apache servers with <em>mod_php</em>. Note that this does not necessarily mean
+that the web application is run inside the same process as the web server:
+it just means that the web server manages applications.
+</p>
+</li>
+<li>
+<p>
+The web application <strong>is</strong> a web server, and can accept HTTP requests
+directly. This is the case for the Trac bug tracking system, running in its
+standalone server. In many setups, such web applications sit behind a different
+web server, instead of accepting HTTP requests directly. The frontend web
+server acts like a reverse HTTP proxy.
+</p>
+</li>
+<li>
+<p>
+The web application does not speak HTTP directly, but is connected directly
+to the web server through some communication adapter. CGI, FastCGI and SCGI
+are good examples of this.
+</p>
+</li>
+</ol></div>
+<div class="para"><p>These descriptions are true for virtually all web applications, whether they're
+based on PHP, Django, J2EE, ASP.NET, Ruby on Rails, or whatever. Note that all
+of these setups provide the same functionality, i.e. no setup can do something
+that a different setup can't. The critical reader will notice that all of these
+setups are identical to the one described in the first diagram, if the
+combination of web servers, application servers, web applications etc. are
+considered to be a single entity; a black box if you will.</p></div>
+<div class="para"><p>It should also be noted that these setups do not enforce any particular
+I/O processing implementation. The web servers, application servers, web
+applications, etc. could process I/O serially (i.e. one request at a time),
+could multiplex I/O with a single thread (e.g. by using <tt>select(2)</tt> or
+<tt>poll(2)</tt>) or it could process I/O with multiple threads and/or multiple
+processes.</p></div>
+<div class="para"><p>Of course, there are many variations possible. For example, load balancers
+could be used. But that is outside the scope of this document.</p></div>
+<h3 id="_ruby_on_rails">1.2. Ruby on Rails</h3><div style="clear:left"></div>
+<div class="para"><p>Every Ruby on Rails application has a <em>dispatcher</em>. This dispatcher is
+responsible for processing HTTP requests. It does not speak HTTP directly.
+Instead, it accepts data structures that contain the information of an
+HTTP request. Thus, the dispatcher is particularly interesting to
+developers who wish to develop software which connects Ruby on Rails to an
+HTTP processing layer (e.g. a web server).</p></div>
+<div class="para"><p>The Ruby on Rails dispatcher can only process requests serially, i.e. one
+at a time. It is not possible to process two requests at the same time
+with threads, because parts of Ruby on Rails are not thread-safe. (In
+practice, this isn't as big of a problem as some people imagine. This will
+be elaborated further in <a href="#concurrent_requests">Handling of concurrent requests</a>.)</p></div>
+<div class="para"><p>A particularly interesting thing to note, is that a lot of the memory
+occupied by Ruby on Rails applications is spent on storing the program code
+(i.e. the <a href="http://en.wikipedia.org/wiki/Abstract_syntax_tree">abstract
+syntax tree (AST)</a>) in memory. This is observed through the use of the
+memory statistics function in <a href="http://www.rubyenterpriseedition.com/">Ruby
+Enterprise Edition</a>. Also, a lot of the startup time of a Ruby on Rails
+application is spent on bootstrapping the Rails framework.</p></div>
+<h3 id="_apache">1.3. Apache</h3><div style="clear:left"></div>
+<div class="para"><p>The Apache web server has a pluggable I/O multiprocessing (the ability to
+handle more than 1 concurrent HTTP client at the same time) architecture. An
+Apache module which implements a particular multiprocessing strategy, is called
+a Multi-Processing Module (MPM). The
+<a href="http://httpd.apache.org/docs/2.0/mod/prefork.html">prefork MPM</a> &#8212; which
+also happens to be the default &#8212; appears to be the most popular one. This MPM
+spawns multiple worker child processes. HTTP requests are first accepted by a
+so-called control process, and then forwarded to one of the worker processes.
+The next section contains a diagram which shows the prefork MPM's architecture.</p></div>
+</div>
+<h2 id="_passenger_architecture">2. Passenger architecture</h2>
+<div class="sectionbody">
+<h3 id="_overview">2.1. Overview</h3><div style="clear:left"></div>
+<div class="para"><p>Passenger's architecture is a lot like setup #2 described in
+<a href="#typical_web_applications">Typical web applications</a>. In other words,
+Passenger extends Apache and allows it to act like an application server.
+Passenger's architecture &#8212; assuming Apache 2 with the prefork MPM is used &#8212;
+is shown in the following diagram:</p></div>
+<div class="para"><p><span class="image">
+<img src="images/passenger_architecture.png" alt="Passenger's architecture" title="Passenger's architecture" />
+</span></p></div>
+<div class="para"><p>Passenger consists of an Apache module, <em>mod_passenger</em>. This is written in
+C++, and can be found in the directory <em>ext/apache2</em>. The module is active in
+the Apache control process and in all the Apache worker processes. When an
+HTTP request comes in, <em>mod_passenger</em> will check whether the request should
+be handled by a Ruby on Rails application. If so, then <em>mod_passenger</em> will
+spawn the corresponding Rails application (if necessary) and forward the
+request to that application.</p></div>
+<div class="para"><p>It should be noted that the Ruby on Rails application does <strong>not</strong> run in the
+same address space as Apache. This differentiates Passenger from other
+application-server-inside-web-server software such as mod_php, mod_perl and
+mod_ruby. If the Rails application crashes or leak memory, it will have no
+effect on Apache. In fact, stability is one of our highest goals. Passenger
+is carefully designed and implemented so that Apache shouldn't crash because
+of Passenger.</p></div>
+<h3 id="_spawning_and_caching_of_code_and_applications">2.2. Spawning and caching of code and applications</h3><div style="clear:left"></div>
+<div class="para"><p>A very naive implementation of Passenger would spawn a Ruby on Rails
+application every time an HTTP request is received, just like CGI would.
+However, spawning Ruby on Rails applications is expensive. It can take 1 or 2
+seconds on a modern PC, and possibly much longer on a heavily loaded server.
+This overhead is particularily unacceptable on shared hosts. A less naive
+implementation would keep spawned Ruby on Rails application instances alive,
+similar to how Lighttpd's FastCGI implementation works.
+However, this still has several problems:</p></div>
+<div class="olist"><ol>
+<li>
+<p>
+The first request to a Rails website will be slow, and subsequent requests
+   will be fast. But the first request to a different Rails website - on the
+   same web server - will still be slow.
+</p>
+</li>
+<li>
+<p>
+As we've explained earlier in this article, a lot of memory in a Rails
+   application is spent on storing the AST of the Ruby on Rails framework and
+   the application. Especially on shared hosts and on memory-constrained
+   Virtual Private Servers (VPS), this can be a problem.
+</p>
+</li>
+</ol></div>
+<div class="para"><p>Both of these problems are very much solvable, and we've chosen to do just
+that.</p></div>
+<div class="para"><p>The first problem can be solved by preloading Rails applications, i.e. by
+running the Rails application before a request is ever made to that website.
+This is the approach taken by most Rails hosts, for example in the form of a
+Mongrel cluster which is running all the time. However, this is unacceptable
+for a shared host: such an application would just sit there and waste memory
+even if it's not doing anything. Instead, we've chosen to take a different
+approach, which solves both of the aforementioned problems.</p></div>
+<div class="para"><p>We spawn Rails applications via a <em>spawn server</em>. The spawn server caches Ruby
+on Rails framework code and application code in memory. Spawning a Rails
+application for the first time will still be slow, but subsequent spawn
+attempts will be very fast. Furthermore, because the framework code is cached
+independently from the application code, spawning a different Rails application
+will also be very fast, as long as that application is using a Rails framework
+version that has already been cached.</p></div>
+<div class="para"><p>Another implication of the spawn server is that different Ruby on Rails will
+share memory with each other, thus solving problem #2. This is described in
+detail in <a href="#spawn_server">the next section</a>.</p></div>
+<div class="para"><p>But despite the caching of framework code and application code, spawning is
+still expensive compared to an HTTP request. We want to avoid spawning whenever
+possible. This is why we've introduced the <strong>application pool</strong>. Spawned
+application instances are kept alive, and their handles are stored into this
+pool, allowing each application instance to be reused later. Thus, Passenger
+has very good average case performance.</p></div>
+<div class="para"><p>The application pool is shared between different worker processes. Because the
+worker processes cannot share memory with each other, either shared memory must
+be used to implement the application pool, or a client/server architecture must
+be implemented. We've chosen the latter because it is easier
+to implement. The Apache control process acts like a server for the application
+pool. However, this does not mean that all HTTP request/response data go
+through the control process. A worker process queries the pool for a connection
+session with a Rails application. Once this session has been obtained, the
+worker process will communicate directly with the Rails application.</p></div>
+<div class="para"><p>The application pool is implemented inside <em>mod_passenger</em>. One can find
+detailed documentation about it in
+<a href="cxxapi/index.html">the C++ API documentation</a>,
+in particular the documentation about the <tt>ApplicationPool</tt>,
+<tt>StandardApplicationPool</tt> and <tt>ApplicationPoolServer</tt> classes.</p></div>
+<div class="admonitionblock">
+<table><tr>
+<td class="icon">
+<img src="./images/icons/note.png" alt="Note" />
+</td>
+<td class="content">At the moment, Passenger does not support Apache with the worker MPM
+(which uses threads instead of processes). But because the application pool is
+implemented in a modular way, supporting the worker MPM shouldn't take more
+than 10 lines of code.</td>
+</tr></table>
+</div>
+<div class="para"><p>The application pool is responsible for spawning applications, caching
+spawned applications' handles, and cleaning up applications which have been
+idle for an extended period of time.</p></div>
+<h3 id="spawn_server">2.3. The spawn server</h3><div style="clear:left"></div>
+<div class="para"><p>The spawn server is written in Ruby, and its code can be found in the directory
+<em>lib/passenger</em>. Its main executable is <em>bin/passenger-spawn-server</em>.
+<a href="rdoc/index.html">The spawn server's RDoc documentation</a> documents the
+implementation in detail.</p></div>
+<div class="para"><p>The spawn server consists of 3 logical layers:</p></div>
+<div class="olist"><ol>
+<li>
+<p>
+<strong>The spawn manager.</strong> This is the topmost layer, and acts like a fascade for
+   all the underlying layers. Clients who use the spawn server only communicate
+   with this layer.
+</p>
+</li>
+<li>
+<p>
+<strong>The framework spawner server.</strong> The spawn manager spawns a framework spawner
+   server for each unique Ruby on Rails framework version. Each framework
+   spawner server caches the code for exactly one Ruby on Rails framework
+   version. A spawn request for an application is forwarded to the framework
+   spawner server that contains the correct Ruby on Rails version for the
+   application.
+</p>
+</li>
+<li>
+<p>
+<strong>The application spawner server.</strong> This is to the framework spawner server
+   what the framework spawner server is to the spawn manager. The framework
+   spawner server spawns an application spawner server for each unique Ruby on
+   Rails application (here &#8220;application&#8221; does not mean a running process, but
+   a set of (source code) files). An application spawner server caches the
+   code for exactly one application.
+</p>
+</li>
+</ol></div>
+<div class="para"><p><span class="image">
+<img src="images/spawn_server_architecture.png" alt="The spawn server's architecture" title="The spawn server's architecture" />
+</span></p></div>
+<div class="para"><p>As you can see, we have two layers of code caching: when the spawn server
+receives a request to spawn a new application instance, it will forward the
+request to the correct framework spawner server (and will spawn that framework
+spawner server if it doesn't already exist), which &#8212; in turn &#8212; will forward
+it to the correct application spawner server (which will, again, be created if
+it doesn't already exist).</p></div>
+<div class="para"><p>Each layer is only responsible for the layer directly below. The spawn manager
+only knows about framework spawner servers, and a framework spawner server only
+knows about its application spawner servers. The application spawner server is,
+however, not responsible for managing spawned application instances. If an
+application instance is spawned by mod_passenger, its information will be sent
+back to mod_passenger, which will be fully responsible for managing the
+application instance's life time (through the application pool).</p></div>
+<div class="para"><p>Also note that each layer is a seperate process. This is required because a
+single Ruby process can only load a single Ruby on Rails framework and a
+single application.</p></div>
+<h4 id="_memory_sharing">2.3.1. Memory sharing</h4>
+<div class="para"><p>On most modern Unix operating systems, when a child process is created, it will
+share most of its memory with the parent process. Processes are not supposed to
+be able to access each others' memory, so the operating system makes a copy of
+a piece of memory when it is written to by the parent process or the child
+process. This is called copy-on-write (COW). Detailed background information
+can be found on <a href="http://www.rubyenterpriseedition.com/">Ruby Enterprise
+Edition's website</a>.</p></div>
+<div class="para"><p>The spawn server makes use of this useful fact. Each layer shares its Ruby AST
+memory with all of its lower layers, as long as the AST nodes in question
+haven't been written to. This means that all spawned Rails applications will
+&#8212; if possible &#8212; share the Ruby on Rails framework's code, as well as its own
+application code, with each other. This results in a dramatic reduction in
+memory usage.</p></div>
+<div class="admonitionblock">
+<table><tr>
+<td class="icon">
+<img src="./images/icons/note.png" alt="Note" />
+</td>
+<td class="content">
+<div class="para"><p>Sharing memory only works if <a href="http://www.rubyenterpriseedition.com/">Ruby
+Enterprise Edition</a> is used. This is because the standard Ruby interpreter's
+garbage collector isn't copy-on-write friendly. Please visit the Ruby
+Enterprise Edition website for technical details.</p></div>
+<div class="para"><p>Passenger works fine with standard Ruby. You still get to enjoy reduced Rails
+startup times. You just won't be able to benefit from memory sharing.</p></div>
+</td>
+</tr></table>
+</div>
+<div class="para"><p>Note that <a href="http://rubini.us/">Rubinius</a>'s garbage collector is already
+copy-on-write friendly.</p></div>
+<h3 id="concurrent_requests">2.4. Handling of concurrent requests</h3><div style="clear:left"></div>
+<div class="para"><p>As explained earlier, a single Rails application instance can only handle a
+single request at the same time. This is obviously undesirable. But before we
+dive into the solution, let us take a look how the &#8220;competition&#8221; solves this
+problem. PHP has similar problems: a single PHP script can also process only
+one HTTP request at a time.</p></div>
+<div class="ilist"><ul>
+<li>
+<p>
+mod_php &#8220;solves&#8221; this problem by using Apache's MPM. In other words,
+  mod_php doesn't do anything by itself at all. A single Apache worker
+  process/thread can only handle 1 PHP request at a time, but Apache spawns
+  multiple worker processes/threads.
+</p>
+</li>
+<li>
+<p>
+PHP-FastCGI solves the problem by spawning multiple persistent PHP servers.
+  The number of PHP servers is independent from the number of Apache worker
+  processes/threads. This approach is a lot like existing Rails setups, in
+  which a frontend web server proxies requests to a persistent Mongrel cluster.
+</p>
+</li>
+</ul></div>
+<div class="para"><p>Passenger cannot use the mod_php way because it would force us to spawn a new
+Rails application for each request, which is &#8212; as explained earlier &#8212;
+unacceptably slow. Instead, Passenger uses the PHP-FastCGI approach. We
+maintain a pool of application instances, and whenever a request is received,
+we forward the request to one of the application instances in the pool. The
+size of the pool is configurable, which is useful for administrators of servers
+that are either heavily loaded or have little memory.</p></div>
+<div class="para"><p>The reader might also be interested in studying the application pool's
+algorithm, which is non-trivial. The algorithm is documented in detail in
+<a href="ApplicationPool%20algorithm.txt">ApplicationPool algorithm.txt</a>.</p></div>
+</div>
+<h2 id="_appendix_a_about_this_document">3. Appendix A: About this document</h2>
+<div class="sectionbody">
+<div class="para"><p>The text of this document is licensed under the
+<a href="http://creativecommons.org/licenses/by-sa/3.0/">Creative Commons
+Attribution-Share Alike 3.0 Unported License</a>.</p></div>
+<div class="para"><p><span class="image">
+<a class="image" href="link:http://creativecommons.org/licenses/by-sa/3.0/">
+<img src="images/by_sa.png" alt="images/by_sa.png" />
+</a>
+</span></p></div>
+</div>
+<div id="footer">
+<div id="footer-text">
+Last updated 2008-12-01 14:21:21 CEST
+</div>
+</div>
+</body>
+</html>