Passenger: Passenger::Application Class Reference

# 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< Session > | SessionPtr
| 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

typedef shared_ptr<Session> Passenger::Application::SessionPtr

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:

- Application.h