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, string appGroupName="", const string &appType="rails", const string &environment="production", const string &spawnMethod="smart-lv2", const string &user="", const string &group="", const string &defaultUser="", const string &defaultGroup="", long frameworkSpawnerTimeout=-1, long appSpawnerTimeout=-1, const string &baseURI="/", unsigned long maxRequests=0, unsigned long minProcesses=0, bool useGlobalQueue=false, bool showVersionInHeader=true, unsigned long statThrottleRate=0, const string &restartDir="", Account::Rights rights=DEFAULT_BACKEND_ACCOUNT_RIGHTS, bool debugger=false, bool analytics=false, const AnalyticsLogPtr &log=AnalyticsLogPtr())
| Creates a new PoolOptions object with the given values.
| PoolOptions (const vector< string > &vec, unsigned int startIndex=0, AnalyticsLoggerPtr analyticsLogger=AnalyticsLoggerPtr())
| Creates a new PoolOptions object from the given string vector.
void | toVector (vector< string > &vec, bool storeEnvVars=true) const
| Append the information in this PoolOptions object to the given string vector.
string | getAppGroupName () const
| Returns the app group name.
string | serializeEnvironmentVariables () const
| Serializes the items in environmentVariables into a string, which can be used to create a SimpleStringListCreator object.
## Public Attributes
string | appRoot
| The root directory of the application to spawn.
string | appGroupName
| A name used by ApplicationPool to uniquely identify an application.
string | appType
| The application type.
string | environment
| The RAILS_ENV/RACK_ENV environment that should be used.
string | spawnMethod
| Method with which application processes should be spawned.
string | user
| See overview.
string | group
| See class overview.
string | defaultUser
| See class overview.
string | defaultGroup
| See class overview.
long | frameworkSpawnerTimeout
| The idle timeout, in seconds, of framework spawners.
long | appSpawnerTimeout
| The idle timeout, in seconds, of application spawners.
StringListCreatorPtr | environmentVariables
| Environment variables which should be passed to the spawned application process.
string | baseURI
| The base URI on which the application runs.
unsigned long | maxRequests
| The maximum number of requests that the spawned application may process before exiting.
unsigned long | minProcesses
| The minimum number of processes for the current group that the application pool's cleaner thread should keep around.
bool | useGlobalQueue
| Whether to use a global queue instead of a per-backend process queue.
bool | showVersionInHeader
| Whether to show the Phusion Passenger version number in the X-Powered-By header.
unsigned long | statThrottleRate
| A throttling rate for file stats.
string | restartDir
| The directory which contains restart.txt and always_restart.txt.
Account::Rights | rights
| Any rights that the spawned application process may have.
bool | debugger
| Whether debugger support should be enabled.
bool | analytics
| In case an app process needs to be spawned, whether analytics logging should be enabled.
AnalyticsLogPtr | log
| An analytics log object to log things to.
bool | initiateSession
| Whether the session returned by ApplicationPool::Interface::get() should be automatically initiated.
bool | printExceptions
| Whether application processes should print exceptions that occurred during application initialization.

## Detailed Description

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

## Privilege lowering support

If user is given and isn't the empty string, then the application process will run as the given username. Otherwise, the owner of the application's startup file (e.g. config/environment.rb or config.ru) will be used.

If group is given and isn't the empty string, then the application process will run as the given group name. If it's set to the special value "!STARTUP_FILE!", then the startup file's group will be used. Otherwise, the primary group of the user that the application process will run as, will be used as group.

If the user or group that the application process attempts to switch to doesn't exist, then default_user and default_group, respectively, will be used.

Phusion Passenger will attempt to avoid running the application process as root: if user or group is set to the root user or the root group, or if the startup file is owned by root, then default_user and default_group will be used instead.

All this only happen if Phusion Passenger has root privileges. If not, then these options have no effect.

## 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`,
|  | AnalyticsLoggerPtr | analyticsLogger = `AnalyticsLoggerPtr()` |
| ) |  |  | `[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.
  | analyticsLogger | If given, and the vector contains logging information, then the 'log' member will be constructed using this logger.

## Member Function Documentation

string Passenger::PoolOptions::getAppGroupName | ( |  | ) | const`[inline]`

Returns the app group name.

If there is no explicitly set app group name then the app root is considered to be the app group name.

string Passenger::PoolOptions::serializeEnvironmentVariables | ( |  | ) | const`[inline]`

Serializes the items in environmentVariables into a string, which can be used to create a SimpleStringListCreator object.

Exceptions:

  | Anything | thrown by environmentVariables->getItems().

void Passenger::PoolOptions::toVector | ( | vector< string > & | vec,
|  | bool | storeEnvVars = `true` |
| ) |  |  | 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.

Parameters:

  | vec | The vector to store the information in.
  | storeEnvVars | Whether to store environment variable information into vec as well.

Exceptions:

  | Anything | thrown by environmentVariables->getItems().

## Member Data Documentation

string Passenger::PoolOptions::appGroupName

A name used by ApplicationPool to uniquely identify an application.

If one tries to get() from the application pool with name "A", then get() again with name "B", then the latter will spawn a new application process, even if both get() requests have the same app root.

If left empty (the default), then the app root is used as the app group name.

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

See the "Spawning methods explained" section of the users guide for information about 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.

string Passenger::PoolOptions::appType

The application type.

Either "rails" (default), "rack" or "wsgi".

string Passenger::PoolOptions::baseURI

The base URI on which the application runs.

If the application is running on the root URI, then this value must be "/".

Invariant:
  baseURI != ""

bool Passenger::PoolOptions::debugger

Whether debugger support should be enabled.

string Passenger::PoolOptions::defaultGroup

See class overview.

Defaults to the defaultUser's primary group.

string Passenger::PoolOptions::defaultUser

See class overview.

Defaults to "nobody".

string Passenger::PoolOptions::environment

The RAILS_ENV/RACK_ENV environment that should be used.

May not be an empty string. The default is "production".

StringListCreatorPtr Passenger::PoolOptions::environmentVariables

Environment variables which should be passed to the spawned application process.

If a new application process is started, then the getItems() method on this object will be called, which is to return environment variables that should be passed to the newly spawned backend process. Odd indices in the resulting array contain keys, even indices contain the value for the key in the previous index.

May be set to NULL.

Invariant:
  environmentVariables.size() is an even number.

long Passenger::PoolOptions::frameworkSpawnerTimeout

The idle timeout, in seconds, of framework spawners.

See the "Spawning methods explained" section of the users guide for information about 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.

string Passenger::PoolOptions::group

See class overview.

bool Passenger::PoolOptions::initiateSession

Whether the session returned by ApplicationPool::Interface::get() should be automatically initiated.

Defaults to true.

AnalyticsLogPtr Passenger::PoolOptions::log

An analytics log object to log things to.

May be the null pointer, in which case analytics logging is disabled for this request.

unsigned long Passenger::PoolOptions::maxRequests

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

A value of 0 means unlimited.

bool Passenger::PoolOptions::printExceptions

Whether application processes should print exceptions that occurred during application initialization.

Defaults to true.

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.

Account::Rights Passenger::PoolOptions::rights

Any rights that the spawned application process may have.

The SpawnManager will create a new account for each spawned app, and that account will be assigned these rights.

string Passenger::PoolOptions::spawnMethod

Method with which application processes should be spawned.

Different methods have different performance and compatibility properties. Available methods are "smart-lv2" (default), "smart" and "conservative". The different spawning methods are explained in the "Spawning methods explained" section of the users guide.

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.

string Passenger::PoolOptions::user

See overview.

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

- PoolOptions.h