Passenger: Passenger::PoolOptions Struct Reference

# Passenger::PoolOptions Struct Reference

This struct encapsulates information for ApplicationPool::get() and for SpawnManager::spawn(), such as which application is to be spawned. More...

`#include <PoolOptions.h>`

List of all members.

## Public Member Functions
| PoolOptions ()
| Creates a new PoolOptions object with the default values filled in.
| PoolOptions (const string &appRoot, bool lowerPrivilege=true, const string &lowestUser="nobody", const string &environment="production", const string &spawnMethod="smart", const string &appType="rails", long frameworkSpawnerTimeout=-1, long appSpawnerTimeout=-1, unsigned long maxRequests=0, unsigned long memoryLimit=0, bool useGlobalQueue=false, unsigned long statThrottleRate=0, const string &restartDir="")
| Creates a new PoolOptions object with the given values.
| PoolOptions (const vector< string > &vec, unsigned int startIndex=0)
| Creates a new PoolOptions object from the given string vector.
void | toVector (vector< string > &vec) const
| Append the information in this PoolOptions object to the given string vector.
## Public Attributes
string | appRoot
| The root directory of the application to spawn.
bool | lowerPrivilege
| Whether to lower the application's privileges.
string | lowestUser
| The user to fallback to if lowering privilege fails.
string | environment
| The RAILS_ENV/RACK_ENV environment that should be used.
string | spawnMethod
| The spawn method to use.
string | appType
| The application type.
long | frameworkSpawnerTimeout
| The idle timeout, in seconds, of Rails framework spawners.
long | appSpawnerTimeout
| The idle timeout, in seconds, of Rails application spawners.
unsigned long | maxRequests
| The maximum number of requests that the spawned application may process before exiting.
unsigned long | memoryLimit
| The maximum amount of memory (in MB) the spawned application may use.
bool | useGlobalQueue
| Whether to use a global queue instead of a per-backend process queue.
unsigned long | statThrottleRate
| A throttling rate for file stats.
string | restartDir
| The directory which contains restart.txt and always_restart.txt.

## Detailed Description

This struct encapsulates information for ApplicationPool::get() and for SpawnManager::spawn(), such as which application is to be spawned.

## Notes on privilege lowering support

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

## Constructor & Destructor Documentation

Passenger::PoolOptions::PoolOptions | ( |  | ) | `[inline]`

Creates a new PoolOptions object with the default values filled in.

One must still set appRoot manually, after having used this constructor.

Passenger::PoolOptions::PoolOptions | ( | const vector< string > & | vec,
|  | unsigned int | startIndex = `0` |
| ) |  |  | `[inline]`

Creates a new PoolOptions object from the given string vector.

This vector contains information that's written to by toVector().

For example:

       PoolOptions options(...);
       vector<string> vec;

       vec.push_back("my");
       vec.push_back("data");
       options.toVector(vec);  // PoolOptions information will start at index 2.

       PoolOptions copy(vec, 2);

Parameters:

  | vec | The vector containing spawn options information.
  | startIndex | The index in vec at which the information starts.

## Member Function Documentation

void Passenger::PoolOptions::toVector | ( | vector< string > & | vec | ) | const`[inline]`

Append the information in this PoolOptions object to the given string vector.

The resulting array could, for example, be used as a message to be sent to the spawn server.

## Member Data Documentation

string Passenger::PoolOptions::appRoot

The root directory of the application to spawn.

In case of a Ruby on Rails application, this is the folder that contains 'app/', 'public/', 'config/', etc. This must be a valid directory, but the path does not have to be absolute.

long Passenger::PoolOptions::appSpawnerTimeout

The idle timeout, in seconds, of Rails application spawners.

A timeout of 0 means that the application spawner should never idle timeout. A timeout of -1 means that the default timeout value should be used.

For more details about Rails application spawners, please read the documentation on the Railz::ApplicationSpawner Ruby class.

string Passenger::PoolOptions::appType

The application type.

Either "rails", "rack" or "wsgi".

string Passenger::PoolOptions::environment

The RAILS_ENV/RACK_ENV environment that should be used.

May not be an empty string.

long Passenger::PoolOptions::frameworkSpawnerTimeout

The idle timeout, in seconds, of Rails framework spawners.

A timeout of 0 means that the framework spawner should never idle timeout. A timeout of -1 means that the default timeout value should be used.

For more details about Rails framework spawners, please read the documentation on the Railz::FrameworkSpawner Ruby class.

bool Passenger::PoolOptions::lowerPrivilege

Whether to lower the application's privileges.

unsigned long Passenger::PoolOptions::maxRequests

The maximum number of requests that the spawned application may process before exiting.

A value of 0 means unlimited.

unsigned long Passenger::PoolOptions::memoryLimit

The maximum amount of memory (in MB) the spawned application may use.

A value of 0 means unlimited.

string Passenger::PoolOptions::restartDir

The directory which contains restart.txt and always_restart.txt.

An empty string means that the default directory should be used.

string Passenger::PoolOptions::spawnMethod

The spawn method to use.

Either "smart" or "conservative". See the Ruby class `SpawnManager` for details.

unsigned long Passenger::PoolOptions::statThrottleRate

A throttling rate for file stats.

When set to a non-zero value N, restart.txt and other files which are usually stat()ted on every ApplicationPool::get() call will be stat()ed at most every N seconds.

bool Passenger::PoolOptions::useGlobalQueue

Whether to use a global queue instead of a per-backend process queue.

This option is only used by ApplicationPool::get().

If enabled, when all backend processes are active, get() will wait until there's at least one backend process that's idle, instead of queuing the request into a random process's private queue. This is especially useful if a website has one or more long-running requests.

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

- PoolOptions.h