Passenger::SpawnManager Class Reference
[Apache-independent support classes and function]

#include <SpawnManager.h>

List of all members.

Detailed Description

Spawning of Ruby on Rails/Rack application instances.

This class is responsible for spawning new instances of Ruby on Rails or Rack applications. Use the spawn() method to do so.

This class is fully thread-safe.

Implementation details

Internally, this class makes use of a spawn server, which is written in Ruby. This server is automatically started when a SpawnManager instance is created, and automatically shutdown when that instance is destroyed. The existance of the spawn server is almost totally transparent to users of this class. Spawn requests are sent to the server, and details about the spawned process is returned.

If the spawn server dies during the middle of an operation, it will be restarted. See spawn() for full details.

The communication channel with the server is anonymous, i.e. no other processes can access the communication channel, so communication is guaranteed to be safe (unless, of course, if the spawn server itself is a trojan).

The server will try to keep the spawning time as small as possible, by keeping corresponding Ruby on Rails frameworks and application code in memory. So the second time an instance of the same application is spawned, the spawn time is significantly lower than the first time. Nevertheless, spawning is a relatively expensive operation (compared to the processing of a typical HTTP request/response), and so should be avoided whenever possible.

See the documentation of the spawn server for full implementation details.

Public Member Functions

 SpawnManager (const string &spawnServerCommand, const string &logFile="", const string &rubyCommand="ruby", const string &user="")
 Construct a new SpawnManager.
ApplicationPtr spawn (const string &appRoot, bool lowerPrivilege=true, const string &lowestUser="nobody", const string &environment="production", const string &spawnMethod="smart", const string &appType="rails")
 Spawn a new instance of a Ruby on Rails or Rack application.
void reload (const string &appRoot)
 Remove the cached application instances at the given application root.
pid_t getServerPid () const
 Get the Process ID of the spawn server.

Constructor & Destructor Documentation

Passenger::SpawnManager::SpawnManager ( const string &  spawnServerCommand,
const string &  logFile = "",
const string &  rubyCommand = "ruby",
const string &  user = "" 
) [inline]

Construct a new SpawnManager.

spawnServerCommand The filename of the spawn server to use.
logFile Specify a log file that the spawn server should use. Messages on its standard output and standard error channels will be written to this log file. If an empty string is specified, no log file will be used, and the spawn server will use the same standard output/error channels as the current process.
rubyCommand The Ruby interpreter's command.
user The user that the spawn manager should run as. This parameter only has effect if the current process is running as root. If the empty string is given, or if the user is not a valid username, then the spawn manager will be run as the current user.
SystemException An error occured while trying to setup the spawn server.
IOException The specified log file could not be opened.

Member Function Documentation

ApplicationPtr Passenger::SpawnManager::spawn ( const string &  appRoot,
bool  lowerPrivilege = true,
const string &  lowestUser = "nobody",
const string &  environment = "production",
const string &  spawnMethod = "smart",
const string &  appType = "rails" 
) [inline]

Spawn a new instance of a Ruby on Rails or Rack application.

If the spawn server died during the spawning process, then the server will be automatically restarted, and another spawn attempt will be made. If restarting the server fails, or if the second spawn attempt fails, then an exception will be thrown.

If lowerPrivilege is true, then it will be attempt to switch the spawned application instance to the user who owns the application's config/environment.rb, and to the default group of that user.

If that user doesn't exist on the system, or if that user is root, then it will be attempted to switch to the username given by lowestUser (and to the default group of that user). If lowestUser doesn't exist either, or if switching user failed (because the spawn server process does not have the privilege to do so), then the application will be spawned anyway, without reporting an error.

It goes without saying that lowering privilege is only possible if the spawn server is running as root (and thus, by induction, that Passenger and Apache's control process are also running as root). Note that if Apache is listening on port 80, then its control process must be running as root. See "doc/Security of user switching.txt" for a detailed explanation.

appRoot The application root of a RoR application, i.e. the folder that contains 'app/', 'public/', 'config/', etc. This must be a valid directory, but the path does not have to be absolute.
lowerPrivilege Whether to lower the application's privileges.
lowestUser The user to fallback to if lowering privilege fails.
environment The RAILS_ENV/RACK_ENV environment that should be used. May not be empty.
spawnMethod The spawn method to use. Either "smart" or "conservative". See the Ruby class SpawnManager for details.
appType The application type. Either "rails" or "rack".
A smart pointer to an Application object, which represents the application instance that has been spawned. Use this object to communicate with the spawned application.
SpawnException Something went wrong.

void Passenger::SpawnManager::reload ( const string &  appRoot  )  [inline]

Remove the cached application instances at the given application root.

Application code might be cached in memory. But once it a while, it will be necessary to reload the code for an application, such as after deploying a new version of the application. This method makes sure that any cached application code is removed, so that the next time an application instance is spawned, the application code will be freshly loaded into memory.

SystemException Unable to communicate with the spawn server, even after a restart.
SpawnException The spawn server died unexpectedly, and a restart was attempted, but it failed.

pid_t Passenger::SpawnManager::getServerPid (  )  const [inline]

Get the Process ID of the spawn server.

This method is used in the unit tests and should not be used directly.

The documentation for this class was generated from the following file:

Generated on Tue Jun 24 14:03:44 2008 for Passenger by  doxygen 1.5.5