Passenger: Passenger::SpawnManager Class Reference

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

An AbstractSpawnManager implementation. More...

`#include <SpawnManager.h>`

Inheritance diagram for Passenger::SpawnManager:
[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:

- SpawnManager.h