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

An AbstractSpawnManager implementation. More...

#include <SpawnManager.h>

Inheritance diagram for Passenger::SpawnManager:
Inheritance graph
[legend]

List of all members.

Public Member Functions

 SpawnManager (const string &spawnServerCommand, const ServerInstanceDir::GenerationPtr &generation, const AccountsDatabasePtr &accountsDatabase=AccountsDatabasePtr(), const string &rubyCommand="ruby", const AnalyticsLoggerPtr &analyticsLogger=AnalyticsLoggerPtr(), int logLevel=0, const string &debugLogFile="")
 Construct a new SpawnManager.
virtual ProcessPtr spawn (const PoolOptions &options)
 Spawn a new application process.
virtual void reload (const string &appRoot)
 Shutdown the ApplicationSpawner server that's running at the given application root.
virtual void killSpawnServer () const
 Forcefully kill the spawn server.
virtual pid_t getServerPid () const
 Returns the spawn server's PID.

Protected Member Functions

virtual void spawnServerStarted ()
 A method which is called after the spawn server has started.

Detailed Description

An AbstractSpawnManager implementation.

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 a process 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.


Constructor & Destructor Documentation

Passenger::SpawnManager::SpawnManager ( const string &  spawnServerCommand,
const ServerInstanceDir::GenerationPtr &  generation,
const AccountsDatabasePtr &  accountsDatabase = AccountsDatabasePtr(),
const string &  rubyCommand = "ruby",
const AnalyticsLoggerPtr &  analyticsLogger = AnalyticsLoggerPtr(),
int  logLevel = 0,
const string &  debugLogFile = "" 
) [inline]

Construct a new SpawnManager.

Parameters:
spawnServerCommand The filename of the spawn server to use.
generation The server instance dir generation in which generation-specific are stored.
accountsDatabase An accounts database. SpawnManager will automatically create a new account for each spawned process, assigning it the rights as set in the PoolOptions object. This account is also automatically deleted when no longer needed. May be a null pointer.
rubyCommand The Ruby interpreter's command.
Exceptions:
RuntimeException An error occurred while creating a Unix server socket.
SystemException An error occured while trying to setup the spawn server.
IOException An error occurred while generating random data.

Member Function Documentation

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

Returns the spawn server's PID.

Used within unit tests.

Implements Passenger::AbstractSpawnManager.

virtual void Passenger::SpawnManager::killSpawnServer (  )  const [inline, virtual]

Forcefully kill the spawn server.

This AbstractSpawnManager's state will not be modified, so that it won't know that the spawn server is killed until next time it sends a command to it.

Used within unit tests.

Implements Passenger::AbstractSpawnManager.

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

Shutdown the ApplicationSpawner server that's running at the given application root.

This method should be called when it's time to reload an application.

Exceptions:
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.

Implements Passenger::AbstractSpawnManager.

virtual ProcessPtr Passenger::SpawnManager::spawn ( const PoolOptions options  )  [inline, virtual]

Spawn a new application process.

Spawning details are to be passed via the options argument.

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.

Parameters:
options An object containing the details for this spawn operation, such as which application to spawn. See PoolOptions for details.
Returns:
A smart pointer to a Process object, which represents the application process that has been spawned. Use this object to communicate with the spawned process.
Exceptions:
SpawnException Something went wrong.
boost::thread_interrupted 
Anything thrown by options.environmentVariables->getItems().

Implements Passenger::AbstractSpawnManager.

virtual void Passenger::SpawnManager::spawnServerStarted (  )  [inline, protected, virtual]

A method which is called after the spawn server has started.

It doesn't do anything by default and serves as a hook for unit tests.


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

Generated by  doxygen 1.6.2