Passenger: Passenger::SpawnManager Class Reference

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

Spawning of Ruby on Rails/Rack application instances. More...

`#include <SpawnManager.h>`

List of all members.

## Public Member Functions
| SpawnManager (const string &spawnServerCommand, const string &logFile="", const string &rubyCommand="ruby", const string &user="")
| Construct a new SpawnManager.
ApplicationPtr | spawn (const PoolOptions &PoolOptions)
| Spawn a new instance of an 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.

## 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.

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

## Constructor & Destructor Documentation

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

Construct a new SpawnManager.

Parameters:

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

Exceptions:

  | SystemException | An error occured while trying to setup the spawn server.
  | IOException | The specified log file could not be opened.

## Member Function Documentation

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.

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.

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.

ApplicationPtr Passenger::SpawnManager::spawn | ( | const PoolOptions & | PoolOptions | ) | `[inline]`

Spawn a new instance of an application.

Spawning details are to be passed via the `PoolOptions` parameter.

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:

  | PoolOptions | An object containing the details for this spawn operation, such as which application to spawn. See PoolOptions for details.

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

Exceptions:

  | SpawnException | Something went wrong.
  | boost::thread_interrupted |

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

- SpawnManager.h