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

#include <Application.h>

List of all members.


Detailed Description

Represents a single Ruby on Rails or Rack application instance.

Public Types

typedef shared_ptr< SessionSessionPtr
 Convenient alias for Session smart pointer.

Public Member Functions

 Application (const string &theAppRoot, pid_t pid, const string &listenSocketName, bool usingAbstractNamespace, int ownerPipe)
 Construct a new Application object.
string getAppRoot () const
 Returns the application root for this application.
pid_t getPid () const
 Returns the process ID of this application instance.
SessionPtr connect (const function< void()> &closeCallback) const
 Connect to this application instance with the purpose of sending a request to the application.

Classes

class  Session
 Represents the life time of a single request/response pair of a Ruby on Rails or Rack application. More...

Member Typedef Documentation

Convenient alias for Session smart pointer.


Constructor & Destructor Documentation

Passenger::Application::Application ( const string &  theAppRoot,
pid_t  pid,
const string &  listenSocketName,
bool  usingAbstractNamespace,
int  ownerPipe 
) [inline]

Construct a new Application object.

Parameters:
theAppRoot The application root of an application. In case of a 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.
pid The process ID of this application instance.
listenSocketName The name of the listener socket of this application instance.
usingAbstractNamespace Whether listenSocketName refers to a Unix socket on the abstract namespace. Note that listenSocketName must not contain the leading null byte, even if it's an abstract namespace socket.
ownerPipe The owner pipe of this application instance.
Postcondition:
getAppRoot() == theAppRoot && getPid() == pid


Member Function Documentation

string Passenger::Application::getAppRoot (  )  const [inline]

Returns the application root for this application.

See the constructor for information about the application root.

SessionPtr Passenger::Application::connect ( const function< void()> &  closeCallback  )  const [inline]

Connect to this application instance with the purpose of sending a request to the application.

Once connected, a new session will be opened. This session represents the life time of a single request/response pair, and can be used to send the request data to the application instance, as well as receiving the response data.

The use of connect() is demonstrated in the following example.

   // Connect to the application and get the newly opened session.
   Application::SessionPtr session(app->connect("/home/webapps/foo"));
   
   // Send the request headers and request body data.
   session->sendHeaders(...);
   session->sendBodyBlock(...);
   // Done sending data, so we close the writer channel.
   session->closeWriter();

   // Now read the HTTP response.
   string responseData = readAllDataFromSocket(session->getReader());
   // Done reading data, so we close the reader channel.
   session->closeReader();

   // 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")

Note that a RoR application instance can only process one request at the same time, and thus only one session at the same time. It's unspecified whether Rack applications can handle multiple simultanous sessions.

You must close a session when you no longer need if. If you call connect() without having properly closed a previous session, you might cause a deadlock because the application instance may be waiting for you to close the previous session.

Returns:
A smart pointer to a Session object, which represents the created session.
Parameters:
closeCallback A function which will be called when the session has been closed.
Postcondition:
this->getSessions() == old->getSessions() + 1
Exceptions:
SystemException Something went wrong during the connection process.
IOException Something went wrong during the connection process.


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

Generated on Tue Jun 24 14:03:44 2008 for Passenger by  doxygen 1.5.5