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

Represents a single Ruby on Rails or Rack application instance. More...

#include <Application.h>

List of all members.

Classes

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

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, const string &listenSocketType, 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.


Detailed Description

Represents a single Ruby on Rails or Rack application instance.

Member Typedef Documentation

Convenient alias for Session smart pointer.


Constructor & Destructor Documentation

Passenger::Application::Application ( const string &  theAppRoot,
pid_t  pid,
const string &  listenSocketName,
const string &  listenSocketType,
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.
listenSocketType The type of the listener socket, e.g. "unix" for Unix domain sockets.
ownerPipe The owner pipe of this application instance.
Postcondition:
getAppRoot() == theAppRoot && getPid() == pid


Member Function Documentation

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->shutdownWriter();

   // Now read the HTTP response.
   string responseData = readAllDataFromSocket(session->getReader());
   // Done reading data, so we close the reader channel.
   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")

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.

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

Returns the application root for this application.

See the constructor for information about the application root.


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

Generated on Wed Apr 8 22:35:12 2009 for Passenger by  doxygen 1.5.8