<!--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 objects are long-living objects and once they are created
|
they are usually cached in the pool for future reuse.
|
|
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
|
feedsSo in order to keep asynchronous applications alive you need to do one of the following:
|
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 the 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
|
on the application, for example
|
in your `main()` function.
|
|
This is suitable for a long running application that
|
exists 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
|
child is attached or assigned to a parent
|
they will share their references and, for example
|
passing a smart pointer to the child class
|
keeps the entire hierarchy alive.
|
|
Basically, similar to the synchronous applications,
|
the parent and all its children "live" 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()` |
`cppcms::http::context::complete_response()`
|
|
|
---
|
|
← [Event Loop][prev]
|
| [Top](#maincontent)
|
| [Thread Safety][next] →
|
|
[prev]: /wikipp/en/page/cppcms_1x_event_loop
|
[next]: /wikipp/en/page/thread_safety |
