Passenger: Passenger::StandardApplicationPool Class Reference

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

A standard implementation of ApplicationPool for single-process environments. More...

`#include <StandardApplicationPool.h>`

Inheritance diagram for Passenger::StandardApplicationPool:

[legend]

List of all members.

## Public Member Functions
| StandardApplicationPool (const string &spawnServerCommand, const string &logFile="", const string &rubyCommand="ruby", const string &user="")
| Create a new StandardApplicationPool object.
virtual Application::SessionPtr | get (const string &appRoot)
| Convenience shortcut for calling get() with default spawn options.
virtual Application::SessionPtr | get (const PoolOptions &options)
| Open a new session with the application specified by `PoolOptions.appRoot`.
virtual void | clear ()
| Clear all application instances that are currently in the pool.
virtual void | setMax (unsigned int max)
| Set a hard limit on the number of application instances that this ApplicationPool may spawn.
virtual unsigned int | getActive () const
| Get the number of active applications in the pool.
virtual unsigned int | getCount () const
| Get the number of active applications in the pool.
virtual void | setMaxPerApp (unsigned int maxPerApp)
| Set a hard limit on the number of application instances that a single application may spawn in this ApplicationPool.
virtual pid_t | getSpawnServerPid () const
| Get the process ID of the spawn server that is used.
virtual string | toString (bool lockMutex=true) const
| Returns a textual description of the internal state of the application pool.
virtual string | toXml () const
| Returns an XML description of the internal state of the application pool.

## Detailed Description

A standard implementation of ApplicationPool for single-process environments.

The environment may or may not be multithreaded - StandardApplicationPool is completely thread-safe. Apache with the threading MPM is an example of a multithreaded single-process environment.

This class is unusable in multi-process environments such as Apache with the prefork MPM. The reasons are as follows:

- StandardApplicationPool uses threads internally. Because threads disappear after a fork(), a StandardApplicationPool object will become unusable after a fork().
- StandardApplicationPool stores its internal cache on the heap. Different processes cannot share their heaps, so they will not be able to access each others' pool cache.
- StandardApplicationPool has a connection to the spawn server. If there are multiple processes, and they all use the spawn servers's connection at the same time without some sort of synchronization, then bad things will happen.

(Of course, StandardApplicationPool is usable if each process creates its own StandardApplicationPool object, but that would defeat the point of having a shared pool.)

For multi-process environments, one should use ApplicationPoolServer instead.

## Constructor & Destructor Documentation

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

Create a new StandardApplicationPool object.

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

virtual void Passenger::StandardApplicationPool::clear | ( |  | ) | `[inline, virtual]`

Clear all application instances that are currently in the pool.

This method is used by unit tests to verify that the implementation is correct, and thus should not be called directly.

Implements Passenger::ApplicationPool.

virtual Application::SessionPtr Passenger::StandardApplicationPool::get | ( | const PoolOptions & | options | ) | `[inline, virtual]`

Open a new session with the application specified by `PoolOptions.appRoot`.

See the class description for ApplicationPool, as well as Application::connect(), on how to use the returned session object.

Internally, this method may either spawn a new application instance, or use an existing one.

Parameters:

  | options | An object containing information on which application to open a session with, as well as spawning details. Spawning details will be used if the pool decides that spawning a new application instance is necessary. See SpawnManager and PoolOptions for details.

Returns:
  A session object.

Exceptions:

  | SpawnException | An attempt was made to spawn a new application instance, but that attempt failed.
  | BusyException | The application pool is too busy right now, and cannot satisfy the request. One should either abort, or try again later.
  | IOException | Something else went wrong.
  | thread_interrupted |

Note:
  Applications are uniquely identified with the application root string. So although `appRoot` does not have to be absolute, it should be. If one calls `get("/home/foo")` and `get("/home/../home/foo")`, then ApplicationPool will think they're 2 different applications, and thus will spawn 2 application instances.

Implements Passenger::ApplicationPool.

virtual unsigned int Passenger::StandardApplicationPool::getActive | ( |  | ) | const`[inline, virtual]`

Get the number of active applications in the pool.

This method exposes an implementation detail of the underlying pooling algorithm. It is used by unit tests to verify that the implementation is correct, and thus should not be called directly.

Implements Passenger::ApplicationPool.

virtual unsigned int Passenger::StandardApplicationPool::getCount | ( |  | ) | const`[inline, virtual]`

Get the number of active applications in the pool.

This method exposes an implementation detail of the underlying pooling algorithm. It is used by unit tests to verify that the implementation is correct, and thus should not be called directly.

Implements Passenger::ApplicationPool.

virtual pid_t Passenger::StandardApplicationPool::getSpawnServerPid | ( |  | ) | const`[inline, virtual]`

Get the process ID of the spawn server that is used.

This method exposes an implementation detail. It is used by unit tests to verify that the implementation is correct, and thus should not be used directly.

Implements Passenger::ApplicationPool.

virtual void Passenger::StandardApplicationPool::setMax | ( | unsigned int | max | ) | `[inline, virtual]`

Set a hard limit on the number of application instances that this ApplicationPool may spawn.

The exact behavior depends on the used algorithm, and is not specified by these API docs.

It is allowed to set a limit lower than the current number of spawned applications.

Implements Passenger::ApplicationPool.

virtual void Passenger::StandardApplicationPool::setMaxPerApp | ( | unsigned int | max | ) | `[inline, virtual]`

Set a hard limit on the number of application instances that a single application may spawn in this ApplicationPool.

The exact behavior depends on the used algorithm, and is not specified by these API docs.

It is allowed to set a limit lower than the current number of spawned applications.

Implements Passenger::ApplicationPool.

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

- StandardApplicationPool.h