<!--toc--> |
|
## Introduction |
|
CppCMS has two core orthogonal concepts: |
|
- **Applications** - classes derived from `cppcms::application` - the objects that define how the user application handles requests |
- **HTTP Context** - `cppcms::http::context` - the context of the request, response, session sessions, cache and many other objects connected to the specific Client-Application interaction. |
|
On each incoming request the Context is created and it is associated with the Application class that handles it. |
|
When the request and response are completed, the context |
will be destroyed and the application usually continues to |
run. |
|
CppCMS is designed for high performance, thus it "caches" anything possible. This includes application objects. |
|
Before we begin, it is very important to understand the two distinct types of application: |
|
1. **Synchronous Applications** - the most common type of application: the ordinary applications that are designed to handle normal requests. |
2. **Asynchronous Applications** - the special applications that are designed to handle multiple requests and support long pooling. |
|
## Synchronous Applications |
|
### Single Application |
|
Synchronous applications live in a pool. They are generated by a special `cppcms::applications_pool::factory` object |
that is mounted to the [`applications_pool`](/cppcms_ref_v0_99/classcppcms_1_1applications__pool.html) object. |
|
These object are long-living object and once they are created |
These objects are long-living objects and once they are created |
they are usually cached in the pool for future reuse. |
|
Upon incoming request the application is fetched from the |
Upon an incoming request, the application is fetched from the |
pool or a new one is created. The special `cppcms::http::context` object is assigned to the application during all request processing, |
|
This request is processed in the thread pool by |
calling the `application::main()` virtual function |
that actually handles the request. |
|
Once the request is completed, this context is unassigned |
and the application is returned back to the pool |
for future reuse. |
|
So when you write your own applications, you may assume |
that their constructors are not called frequently. You should also assume that they will "kept alive" for a long time. |
|
It is good idea to cache some general non-mutable |
information withing such objects. |
|
### Applications with Children |
|
Each application can have multiple child-applications, for example: |
|
blog |
admin |
post_editing |
options_editing |
display |
post |
summary |
feeds |
atom |
rss |
|
|
Each child application can be connected to the parent |
via the [`add` or `attach`](/cppcms_ref_v0_99/classcppcms_1_1application.html) member functions |
in the constructor. Each application shares its lifetime and its `cppcms::http::context` with its parent. |
|
Even though they are different objects and different |
classes they are tightly bounded and live |
together as long as topmost-parent lives, `blog` in our case. |
|
|
## Asynchronous Applications |
|
### Lifetime |
|
Unlike synchronous applications that have multiple |
instances in the applications pool and are executed |
in the thread pool, asynchronous applications |
are designed to handle multiple connections |
simultaneously, and thus instead of being called |
in the thread pool per each request, they run exclusively |
in the main [CppCMS Event Loop](/wikipp/en/page/cppcms_1x_event_loop) |
|
Asynchronous applications live as long as their reference |
counter is not 0. Once the reference counter |
decreases to 0 the application is destroyed and automatically |
unmounted from the applications pool. |
|
So in order to keep asynchronous applications alive |
you need to do one of the following: |
|
1. Keep a persistent `intrusive_ptr` smart pointer |
pointer on the application, for example |
in your `main()` function. |
|
This is suitable for a long running applications that |
exist all the time the service is running. |
|
2. Make sure that you have event handlers that hold |
a smart pointer and waiting for the event. |
|
This is usually done by passing `intrusive_ptr` within |
the event handler. |
|
This method is suitable for temporary |
applications that may represent for example |
different information channels like chat rooms |
that may be created or destroyed |
at some point. |
|
### Asynchronous applications and their Children |
|
Each asynchronous application and its children |
share the same reference counter. Thus if a |
children is attached or assigned to a parent |
they will share their references and, for example |
passing a smart pointer the the child class |
keeps the entire hierarchy alive. |
|
Basically, similarly to the synchronous application |
the parent and all its ancestors "born" and "die" together. |
|
### HTTP Context handling |
|
There is once context assigned to the asynchronous application. If the `cppcms::application::main()` |
function completes while the context is still assigned, |
it would be automatically detached and complete the |
response to the client. |
|
In order to postpone the response, the context should |
be manually detached from the application by calling |
`cppcms::application::release_context()` function. |
|
Now it is your responsibility to keep it as long |
as you need and finalize the response by calling |
`cppcms::http::context::complete_response()` |
