passenger 1.0.1

data/benchmark/unix_sockets_vs_pipes.rb

@@ -0,0 +1,83 @@
+#!/usr/bin/env ruby
+# Benchmarks raw Unix socket I/O performance versus pipe I/O performance.
+require 'benchmark'
+
+ITERATIONS = 150000
+
+def start
+	if ARGV.empty?
+		benchmark(:unix_sockets)
+		benchmark(:pipes)
+	elsif ARGV.size == 1 && ARGV[0] == 'unix_sockets'
+		benchmark(:unix_sockets)
+	elsif ARGV.size == 1 && ARGV[0] == 'pipes'
+		benchmark(:pipes)
+	else
+		puts "Benchmarks raw Unix socket I/O performance versus pipe I/O performance."
+		puts "Usage: unix_sockets_vs_pipes.rb <unix_sockets|pipes>"
+		exit(1)
+	end
+end
+
+def benchmark(type)
+	if type == :unix_sockets
+		puts "Benchmarking Unix sockets..."
+		pid, reader, writer = setup_unix_sockets
+	else
+		puts "Benchmarking pipes..."
+		pid, reader, writer = setup_pipes
+	end
+	result = Benchmark.measure do
+		ITERATIONS.times do |i|
+			writer.write("hello world\n")
+			reader.readline
+		end
+		reader.close
+		if reader != writer
+			writer.close
+		end
+		Process.waitpid(pid)
+	end
+	puts "User/system/real time: #{result}"
+	printf "%.2f lines per second\n", ITERATIONS / result.real
+end
+
+def setup_unix_sockets
+	require 'socket'
+	a, b = UNIXSocket.pair
+	pid = fork do
+		a.close
+		child_main_loop(b, b)
+	end
+	b.close
+	return [pid, a, a]
+end
+
+def setup_pipes
+	a, b = IO.pipe
+	c, d = IO.pipe
+	pid = fork do
+		b.close
+		c.close
+		reader = a
+		writer = d
+		child_main_loop(reader, writer)
+	end
+	a.close
+	d.close
+	reader = c
+	writer = b
+	return [pid, reader, writer]
+end
+
+def child_main_loop(reader, writer)
+	begin
+		while true
+			x = reader.readline
+			writer.write(x)
+		end
+	rescue EOFError
+	end
+end
+
+start

data/bin/passenger-install-apache2-module

@@ -0,0 +1,274 @@
+#!/usr/bin/env ruby
+#  Phusion Passenger - http://www.modrails.com/
+#  Copyright (C) 2008  Phusion
+#
+#  This program 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; version 2 of the License.
+#
+#  This program 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, write to the Free Software Foundation, Inc.,
+#  51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+
+PASSENGER_ROOT = File.expand_path(File.dirname(__FILE__) << "/..")
+$LOAD_PATH.unshift("#{PASSENGER_ROOT}/lib")
+
+# The Apache executable may be located in an 'sbin' folder. We add
+# the 'sbin' folders to $PATH just in case. On some systems
+# 'sbin' isn't in $PATH unless the user is logged in as root from
+# the start (i.e. not via 'su' or 'sudo').
+ENV["PATH"] += ":/usr/sbin:/sbin:/usr/local/sbin"
+
+require 'passenger/platform_info'
+require 'passenger/dependencies'
+require 'passenger/console_text_template'
+include Passenger
+include PlatformInfo
+
+class Installer
+	PASSENGER_WEBSITE = "http://www.modrails.com/"
+	PHUSION_WEBSITE = "www.phusion.nl"
+	USERS_GUIDE = "#{PASSENGER_ROOT}/doc/Users guide.html"
+	
+	REQUIRED_DEPENDENCIES = [
+		Dependencies::GCC,
+		Dependencies::Ruby_DevHeaders,
+		Dependencies::Ruby_OpenSSL,
+		Dependencies::RubyGems,
+		Dependencies::Rake,
+		Dependencies::Apache2,
+		Dependencies::Apache2_DevHeaders,
+		Dependencies::APR_DevHeaders,
+		Dependencies::FastThread
+	]
+	
+	def start
+		Dir.chdir(PASSENGER_ROOT)
+		show_welcome_screen
+		check_dependencies || exit(1)
+		warn_about_broken_apache_on_osx
+		check_whether_apache_uses_prefork_mpm
+		check_write_permission_to_passenger_root || exit(1)
+		check_write_permission_to_apache_modules_dir || exit(1)
+		if install_apache2_module
+			show_apache2_config_snippets
+			show_deployment_example
+		else
+			show_possible_solutions_for_compilation_and_installation_problems
+			exit(1)
+		end
+	ensure
+		reset_terminal_colors
+	end
+
+private
+	def init_terminal_colors
+		STDOUT.write("\e[0m\e[37m\e[40m")
+		STDOUT.flush
+	end
+	
+	def reset_terminal_colors
+		STDOUT.write("\e[0m")
+		STDOUT.flush
+	end
+	
+	def show_welcome_screen
+		render_template 'welcome'
+		wait
+	end
+
+	def check_dependencies
+		missing_dependencies = []
+		color_puts "<banner>Checking for required software...</banner>"
+		puts
+		REQUIRED_DEPENDENCIES.each do |dep|
+			color_print " * #{dep.name}... "
+			result = dep.check
+			if result.found?
+				if result.found_at
+					color_puts "<green>found at #{result.found_at}</green>"
+				else
+					color_puts "<green>found</green>"
+				end
+			else
+				color_puts "<red>not found</red>"
+				missing_dependencies << dep
+			end
+		end
+		
+		if missing_dependencies.empty?
+			return true
+		else
+			puts
+			color_puts "<red>Some required software is not installed.</red>"
+			color_puts "But don't worry, this installer will tell you how to install them.\n"
+			color_puts "<b>Press Enter to continue, or Ctrl-C to abort.</b>"
+			wait
+			
+			line
+			color_puts "<banner>Installation instructions for required software</banner>"
+			puts
+			missing_dependencies.each do |dep|
+				print_dependency_installation_instructions(dep)
+				puts
+			end
+			return false
+		end
+	end
+	
+	def warn_about_broken_apache_on_osx
+		return unless RUBY_PLATFORM =~ /darwin/ && APXS2 == "/usr/sbin/apxs"
+		line
+		render_template 'osx_broken_apache_warning'
+		wait
+	end
+	
+	def check_whether_apache_uses_prefork_mpm
+		line
+		# 'httpd -V' output is in the form of:
+		#
+		# Server MPM:      Prefork     # <--- this line is not always available!
+		# ...
+		# Server compiled with....
+		#  -D APACHE_MPM_DIR="server/mpm/prefork"
+		output = `#{HTTPD} -V`
+		output =~ /^Server MPM: +(.*)$/
+		if $1
+			mpm = $1.downcase
+		else
+			output =~ /APACHE_MPM_DIR="server\/mpm\/(.*)"/
+			if $1
+				mpm = $1.downcase
+			else
+				mpm = nil
+			end
+		end
+		if mpm != "prefork"
+			render_template 'apache_must_be_compiled_with_prefork_mpm',
+				:current_mpm => mpm
+			wait
+		end
+	end
+	
+	def check_write_permission_to_passenger_root
+		File.new("__test__.txt", "w").close
+		return true
+	rescue
+		puts
+		line
+		if Process.uid == 0
+			render_template 'no_write_permission_to_passenger_root'
+		else
+			render_template 'run_installer_as_root'
+		end
+		return false
+	ensure
+		File.unlink("__test__.txt") rescue nil
+	end
+	
+	def check_write_permission_to_apache_modules_dir
+		install_dir = `#{APXS2} -q LIBEXECDIR`.strip
+		begin
+			File.new("#{install_dir}/__test__.txt", "w").close
+			return true
+		rescue
+			puts
+			line
+			if Process.uid == 0
+				render_template 'no_write_permission_to_passenger_root',
+					:path => install_dir
+			else
+				render_template 'run_installer_as_root',
+					:path => install_dir
+			end
+			return false
+		ensure
+			File.unlink("#{install_dir}/__test__.txt") rescue nil
+		end
+	end
+	
+	def install_apache2_module
+		puts
+		line
+		color_puts '<banner>Compiling and installing Apache 2 module...</banner>'
+		puts "cd #{PASSENGER_ROOT}"
+		puts "rake clean apache2"
+		return system("rake", "clean", "apache2")
+	end
+	
+	def show_apache2_config_snippets
+		puts
+		line
+		render_template 'apache2_config_snippets',
+			:module_location => "#{PASSENGER_ROOT}/ext/apache2/mod_passenger.so",
+			:spawn_server_location => "#{PASSENGER_ROOT}/bin/passenger-spawn-server",
+			:ruby => RUBY
+		wait
+	end
+	
+	def show_deployment_example
+		puts
+		line
+		render_template 'deployment_example',
+			:users_guide => USERS_GUIDE,
+			:phusion_website => PHUSION_WEBSITE,
+			:passenger_website => PASSENGER_WEBSITE
+	end
+	
+	def show_possible_solutions_for_compilation_and_installation_problems
+		puts
+		line
+		render_template 'possible_solutions_for_compilation_and_installation_problems',
+			:users_guide => USERS_GUIDE,
+			:passenger_website => PASSENGER_WEBSITE
+	end
+
+private
+	def color_print(text)
+		STDOUT.write(ConsoleTextTemplate.new(:text => text).result)
+		STDOUT.flush
+	end
+	
+	def color_puts(text)
+		color_print("#{text}\n")
+	end
+	
+	def render_template(name, options = {})
+		puts ConsoleTextTemplate.new({ :file => name }, options).result
+	end
+	
+	def line
+		puts "--------------------------------------------"
+	end
+	
+	def wait
+		begin
+			STDIN.readline
+		rescue Interrupt
+			exit 2
+		end
+	end
+	
+	def print_dependency_installation_instructions(dep)
+		color_puts " * To install <yellow>#{dep.name}</yellow>:"
+		if !dep.install_command.nil?
+			color_puts "   Please run <b>#{dep.install_command}</b> as root."
+		elsif !dep.install_instructions.nil?
+			color_puts "   " << dep.install_instructions
+		elsif !dep.website.nil?
+			color_puts "   Please download it from <b>#{dep.website}</b>"
+			if !dep.website_comments.nil?
+				color_puts "   (#{dep.website_comments})"
+			end
+		else
+			color_puts "   Search Google."
+		end
+	end
+end
+
+Installer.new.start

data/bin/passenger-spawn-server

@@ -0,0 +1,38 @@
+#!/usr/bin/env ruby
+#  Phusion Passenger - http://www.modrails.com/
+#  Copyright (C) 2008  Phusion
+#
+#  This program 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; version 2 of the License.
+#
+#  This program 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, write to the Free Software Foundation, Inc.,
+#  51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+
+require 'pathname'
+$LOAD_PATH.unshift(File.expand_path("#{File.dirname(__FILE__)}/../lib"))
+require 'passenger/spawn_manager'
+require 'passenger/utils'
+
+begin
+	STDOUT.sync = true
+	STDERR.sync = true
+	$0 = "Passenger spawn server"
+	if GC.respond_to?(:copy_on_write_friendly=)
+		GC.copy_on_write_friendly = true
+	end
+	spawn_manager = Passenger::SpawnManager.new
+	input = IO.new(Passenger::SpawnManager::DEFAULT_INPUT_FD)
+	spawn_manager.start_synchronously(input)
+	spawn_manager.cleanup
+rescue => e
+	include Passenger::Utils
+	print_exception("spawn manager", e)
+	exit 10
+end

data/doc/ApplicationPool algorithm.txt

@@ -0,0 +1,290 @@
+= ApplicationPool algorithm
+
+
+== Introduction
+
+For efficiency reasons, Passenger keeps a pool spawned Rails applications.
+Please read the C++ API documentation for the ApplicationPool class for a full
+introduction. This document describes an algorithm for managing the pool.
+
+The algorithm should strive to keep spawning to a minimum.
+
+TODO: check whether the algorithm has thrashing behavior.
+
+
+== Definitions
+
+=== Types
+
+Most of the types that we use in this document are pretty standard. But we
+explicitly define some special types:
+
+- list<SomeType>
+  A doubly linked list which contains elements of type SomeType. It supports
+  all the usual list operations that one can expect from a linked list, like
+  add_to_back(), etc.
+  
+  The following operations deserve special mention:
+  * remove(iterator)
+    Removes the specified element from the list. _iterator_ is a linked list
+    iterator: it probably contains the links and a reference to the actual
+    list element, depending on the list implementation. This operation can be
+    done in O(1) time.
+  
+  * move_to_front(iterator)
+    Moves the specified element to the front of the list. _iterator_ is an
+    iterator, as described earlier.
+  
+- AppContainer
+  A compound type which contains an application instance, as well as iterators
+  for various linked lists. These iterators make it possible to perform actions
+  on the linked list in O(1) time.
+  
+  An AppContainer has the following members:
+  * app - An Application object, representing an application instance.
+  * last_used (time) - The last time a session for this application instance
+    was opened or closed.
+  * sessions (integer) - The number of open sessions for this application
+    instance.
+    Invariant:
+       (sessions == 0) == (This AppContainer is in inactive_apps.)
+  * iterator - The iterator for this AppContainer in the linked list
+    apps[app.app_root]
+  * ia_iterator - The iterator for this AppContainer in the linked list
+    inactive_apps. This iterator is only valid if this AppContainer really is
+    in that list.
+
+=== Special functions
+
+- spawn(app_root)
+  Spawns a new instance of the application at the given application root.
+  Throws an exception if something went wrong. This function is thread-safe.
+  Note that application initialization can take an arbitrary amount of time.
+
+=== Instance variables
+
+The algorithm requires the following instance variables for storing state
+information:
+
+- lock: mutex
+  This lock is used for implementing thread-safetiness. We assume that it
+  is non-recursive, i.e. if a thread locks a mutex that it has already locked,
+  then it will result in a deadlock.
+
+- apps: map[string => list<AppContainer>]
+  Maps an application root to a list of AppContainers. Thus, this map contains
+  all application instances that are in the pool.
+  
+  Invariant:
+     for all values v in app:
+        v is nonempty.
+        for all 0 <= i < v.size() - 1:
+           if v[i].app is active:
+              v[i + 1].app is active
+  
+  An active application is one that has more than 0 active sessions.
+
+- max: integer
+  The maximum number of AppContainer objects that may exist in 'apps'.
+
+- count: integer
+  The current number of AppContainer objects in 'apps'.
+  Since 'max' can be set dynamically during the life time of an application
+  pool, 'count > max' is possible.
+
+- active: integer
+  The number of application instances in 'apps' that are active.
+  Invariant:
+     active <= count
+
+- inactive_apps: list<AppContainer>
+  A linked list of AppContainer objects. All application instances in this list
+  are inactive.
+  
+  Invariant:
+     inactive_apps.size() == count - active
+     for all c in inactive_apps:
+        c is in apps.
+        c.sessions == 0
+
+- restart_file_times: map[string => time]
+  Maps an application root to the last known modification time of
+  'restart.txt'.
+  
+  Invariant:
+     for all keys app_root in restart_times:
+        apps.has_key(app_root)
+
+
+== Algorithm in pseudo code
+
+# Thread-safetiness notes:
+# - All wait commands are to unlock the lock during waiting.
+
+function get(app_root):
+	MAX_ATTEMPTS = 5
+	attempt = 0
+	while (true):
+		attempt++
+		lock.synchronize:
+			container, list = spawn_or_use_existing(app_root)
+			container.last_used = current_time()
+			container.sessions++
+			try:
+				return container.app.connect()
+			on exception:
+				container.sessions--
+				if (attempt == MAX_ATTEMPTS):
+					propagate exception
+				else:
+					# The app instance seems to have crashed. So we remove this
+					# instance from our data structures.
+					list.remove(container.iterator)
+					if list.empty():
+						apps.remove(app_root)
+					count--
+					active--
+
+
+# Returns a pair of [AppContainer, list<AppContainer>] that matches the
+# given application root. If no such AppContainer exists, then it is created
+# and a new application instance is spawned. All exceptions that occur are
+# propagated.
+function spawn_or_use_existing(app_root):
+	list = apps[app_root]
+	
+	if (list != nil) and (needs_restart(app_root)):
+		for all container in list:
+				if container.sessions == 0:
+					inactive_apps.remove(container.ia_iterator)
+				else:
+					active--
+				list.remove(container.iterator)
+				count--
+			apps.remove(app_root)
+			list = nil
+			Tell spawn server to reload code for app_root.
+	
+	if list != nil:
+		# There are apps for this app root.
+		if (list.front.sessions == 0) or (count >= max):
+			# There is an inactive app, so we use it.
+			#  -OR-
+			# All apps are active, and the pool is full. We're not
+			# allowed to spawn a new app, so we try to connect to
+			# an existing one. Our connection request will be put
+			# into that app's connection queue.
+			container = list.front
+			list.move_to_back(container.iterator)
+			if container.sessions == 0:
+				inactive_apps.remove(container.ia_iterator)
+			active++
+		else:
+			# All apps are active, but the pool hasn't reached its
+			# maximum yet. So we spawn a new app.
+			container = new AppContainer
+			# TODO: we should unlock the mutex during spawning,
+			# and add some kind of timeout check.
+			container.app = spawn(app_root)
+			container.sessions = 0;
+			iterator = list.add_to_back(container)
+			container.iterator = iterator
+			count++
+			active++
+	else:
+		# There are no apps for this app root.
+		wait until active < max
+		if count == max:
+			# Here we are in a though situation. There are several
+			# apps which are inactive, and none of them have
+			# application root _app_root_, so we must kill one of
+			# them in order to free a spot in the pool. But which
+			# one do we kill? We want to minimize spawning.
+			#
+			# It's probably a good idea to keep some kind of
+			# statistics in order to decide this. We want the
+			# application root that gets the least traffic to be
+			# killed. But for now, we kill a random application
+			# instance.
+			container = inactive_apps.pop_front
+			list = apps[container.app.app_root]
+			list.remove(container.iterator)
+			if list.empty():
+				apps.remove(container.app.app_root)
+				restart_file_times.remove(container.app.app_root)
+			count--
+		container = new AppContainer
+		# TODO: we should unlock the mutex during spawning,
+		# and add some kind of timeout check.
+		container.app = spawn(app_root)
+		container.sessions = 0;
+		list = apps[app_root]
+		if list == nil:
+			list = new list
+			apps[app_root] = list
+		iterator = list.add_to_back(container)
+		container.iterator = iterator
+		count++
+		active++
+	return [container, list]
+
+
+# The following function is to be called when a session has been closed.
+# _container_ is the AppContainer that contains the application for which a
+# session has been closed.
+function session_has_been_closed(container):
+	lock.synchronize:
+		list = apps[container.app.app_root]
+		if list != nil:
+			container.last_used = current_time()
+			container.sessions--
+			if container.sessions == 0:
+				list.move_to_front(container.iterator)
+				container.ia_iterator = inactive_apps.add_to_back(container.app)
+			active--
+
+
+function needs_restart(app_root):
+	restart_file = "$app_root/tmp/restart.txt"
+	s = stat(restart_file)
+	if s != null:
+		delete_file(restart_file)
+		if (deletion was successful) or (file was already deleted):
+			restart_file_times.remove(app_root)
+			result = true
+		else:
+			last_restart_file_time = restart_file_times[app_root]
+			if last_restart_time == null:
+				result = true
+			else:
+				result = s.mtime != last_restart_file_time
+			restart_file_times[app_root] = s.mtime
+	else:
+		restart_file_times.remove(app_root)
+		result = false
+	return result
+
+
+# The following thread will be responsible for cleaning up idle application
+# instances, i.e. instances that haven't been used for a while.
+thread cleaner:
+	lock.synchronize:
+		done = false
+		while !done:
+			Wait until CLEAN_INTERVAL seconds have expired, or until the thread has been signalled to quit.
+			if thread has been signalled to quit:
+				done = true
+				break
+		
+			now = current_time()
+			for all container in inactive_apps:
+				app = container.app
+				app_list = apps[app.app_root]
+				if now - container.last_used > MAX_IDLE_TIME:
+					app_list.remove(container.iterator)
+					inactive_apps.remove(iterator for container)
+					count--
+				if app_list.empty():
+					apps.remove(app.app_root)
+					restart_file_times.remove(app.app_root)
+