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

#include <ApplicationPool.h>

Inheritance diagram for Passenger::ApplicationPool:

Inheritance graph
[legend]

List of all members.

Detailed Description

A persistent pool of Applications.

Spawning application instances, especially Ruby on Rails ones, is a very expensive operation. Despite best efforts to make the operation less expensive (see SpawnManager), it remains expensive compared to the cost of processing an HTTP request/response. So, in order to solve this, some sort of caching/pooling mechanism will be required. ApplicationPool provides this.

Normally, one would use SpawnManager to spawn a new RoR/Rack application instance, then use Application::connect() to create a new session with that application instance, and then use the returned Session object to send the request and to read the HTTP response. ApplicationPool replaces the first step with a call to Application::get(). For example: 

   ApplicationPool pool = some_function_which_creates_an_application_pool();
   
   // Connect to the application and get the newly opened session.
   Application::SessionPtr session(pool->get("/home/webapps/foo"));
   
   // Send the request headers and request body data.
   session->sendHeaders(...);
   session->sendBodyBlock(...);
   // Done sending data, so we shutdown the writer stream.
   session->shutdownWriter();

   // Now read the HTTP response.
   string responseData = readAllDataFromSocket(session->getStream());
   // Done reading data, so we shutdown the reader stream.
   session->shutdownReader();

   // This session has now finished, so we close the session by resetting
   // the smart pointer to NULL (thereby destroying the Session object).
   session.reset();

   // We can connect to an Application multiple times. Just make sure
   // the previous session is closed.
   session = app->connect("/home/webapps/bar")

Internally, ApplicationPool::get() will keep spawned applications instances in memory, and reuse them if possible. It wil*

Exceptions:
l try to keep spawning to a minimum. Furthermore, if an application instance hasn't been used for a while, it will be automatically shutdown in order to save memory. Restart requests are honored: if an application has the file 'restart.txt' in its 'tmp' folder, then get() will shutdown existing instances of that application and spawn a new instance (this is useful when a new version of an application has been deployed). And finally, one can set a hard limit on the maximum number of applications instances that may be spawned (see ApplicationPool::setMax()).
Note that ApplicationPool is just an interface (i.e. a pure virtual class). For concrete classes, see StandardApplicationPool and ApplicationPoolServer. The exact pooling algorithm depends on the implementation class.

Public Member Functions

virtual bool connected () const
 Checks whether this ApplicationPool object is still connected to the ApplicationPool server.
virtual Application::SessionPtr get (const PoolOptions &options)=0
 Open a new session with the application specified by PoolOptions.appRoot.
virtual Application::SessionPtr get (const string &appRoot)
 Convenience shortcut for calling get() with default spawn options.
virtual void clear ()=0
 Clear all application instances that are currently in the pool.
virtual void setMax (unsigned int max)=0
 Set a hard limit on the number of application instances that this ApplicationPool may spawn.
virtual unsigned int getActive () const =0
 Get the number of active applications in the pool.
virtual unsigned int getCount () const =0
 Get the number of active applications in the pool.
virtual void setMaxPerApp (unsigned int max)=0
 Set a hard limit on the number of application instances that a single application may spawn in this ApplicationPool.
virtual pid_t getSpawnServerPid () const =0
 Get the process ID of the spawn server that is used.

Member Function Documentation

virtual bool Passenger::ApplicationPool::connected (  )  const [inline, virtual]

Checks whether this ApplicationPool object is still connected to the ApplicationPool server.

If that's not the case, then one should reconnect to the ApplicationPool server.

This method is only meaningful for instances of type ApplicationPoolServer::Client. The default implementation always returns true.

virtual Application::SessionPtr Passenger::ApplicationPool::get ( const PoolOptions &  options  )  [pure 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.

Implemented in Passenger::StandardApplicationPool.

virtual void Passenger::ApplicationPool::clear (  )  [pure 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.

Implemented in Passenger::StandardApplicationPool.

virtual void Passenger::ApplicationPool::setMax ( unsigned int  max  )  [pure 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.

Implemented in Passenger::StandardApplicationPool.

virtual unsigned int Passenger::ApplicationPool::getActive (  )  const [pure 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.

Implemented in Passenger::StandardApplicationPool.

virtual unsigned int Passenger::ApplicationPool::getCount (  )  const [pure 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.

Implemented in Passenger::StandardApplicationPool.

virtual void Passenger::ApplicationPool::setMaxPerApp ( unsigned int  max  )  [pure 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.

Implemented in Passenger::StandardApplicationPool.

virtual pid_t Passenger::ApplicationPool::getSpawnServerPid (  )  const [pure 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.

Implemented in Passenger::StandardApplicationPool.

The documentation for this class was generated from the following file:
Generated on Tue Mar 31 14:00:30 2009 for Passenger by  doxygen 1.5.5