## Role |
|
This class provides access to cache API of cppcms. It is usually accessed by `cache` member of `application` or `worker_thread`. |
|
In order to use cache, you should [enable it](/wikipp/en/page/ref_config#cache) in CppCMS configurations, otherwise, dummy cache would be used. |
|
## Objects that are stored in cache: |
|
1. Output pages -- including two versions compressed and not for user agents that support gzip compression or not. |
2. HTML Frames -- or simple strings stored in cache. |
3. [Serializable]((/wikipp/en/page/ref_cppcms_serializable) objects. |
|
Each one of them has little bit different semantics and API. |
|
## General |
|
CppCMS provides sophisticated cache system that allows keep its consistency using special triggers that allow cleanup dependent groups of entries using single call. |
|
However, in many cases, timeout only based approach is good enough. So, we would divide the API into two sections: |
|
1. Trigger-less cache access |
2. Full trigger based cache access |
|
|
## Trigger-less cache access |
|
### Web Page |
|
- **`bool fetch_page(string const &key)`** -- fetch page from cache. If it is fetched, `true` is returned and output is prepared, otherwise false is returned. |
|
_Note:_ The output is prepared according to request of user agent --- compressed or not compressed format. Thus, output stream may include already compressed data, so you should not try to append any output after you use this function. |
|
- **`void store_page(string const &key,int timeout=-1);`** -- store prepared output in cache using `timeout` in seconds. |
|
_Note_: default timeout = -1 -- infinite. |
|
For example: |
|
if(cache.fetch_page("main")) |
return; |
... |
render(...) |
cache.store_page("main",3600); |
|
The page can be removed from cache calling: |
|
- **`void rise(string const &key)`** -- that removes data associated with this key. |
|
|
### HTML frames and C++ Objects. |
|
You can fetch such objects using: |
|
bool fetch_frame(string const &key, |
string &result, |
bool notriggers=false); |
bool fetch_data(string const &key, |
serializable &data, |
bool notriggers=false); |
|
_Note:_ Because we work without triggers you should specify `notriggers` as true. |
|
For example: |
|
roles user_roles; // some serializable object |
if(cache.fetch_data("user_"+user_id,user_roles,true)) |
.... |
|
|
You can store these objects using: |
|
void store_frame(string const &key, |
string const &frame, |
int timeout, |
bool notriggers=false); |
void store_data(string const &key, |
serializable const &data, |
int timeout, |
bool notriggers=false); |
|
_Notes:_ |
|
- When working without triggers, specify `notriggers` to `true`, |
- You specify timeout in seconds, when -1 is infinity. |
- `notriggers` option for `store_data` and `store_frame` are available from cppcms v0.0.3. |
|
For example: |
|
roles user_roles; // some serializable object |
string key="user_"+user_id; |
if(!cache.fetch_data(key,user_roles,true)) { |
load_user_roles_from_db(user_id,user_roles); |
cache.store_data(key,user_roles,-1,true); |
} |
|
As in case of web pages you can clean data from cache using `void rise(string const &key)` member function. |
|
|
## Triggers based cache |
|
First of all basic concept --- every stored key has triggers --- other keys that can be risen and the cache would be clean. |
Each key has at least one trigger --- itself. |
|
For example you have article in blog that may be displayed in several places: |
|
- Summary of all topics |
- Rss feed |
- Summary for specific category it belongs to. |
|
So, if we add trigger "article\_1234" for these pages, whe we call `rise("article_1234")`, all these cached entries would |
be automatically dropped. |
|
### Manual Triggers Management |
|
You can add triggers to current HTML page calling |
|
void add_trigger(string const &trigger); |
|
Thus, when the page is stored calling `store_page(key,timeout)`, this trigger would be automatically added. For example |
|
for(i=0;i<articles.size();i++) { |
content.articles_summary.push_back(articles[i]); |
cache.add_trigger("article_" + articles[i].id); |
} |
render("summary",content); |
cache.store_page("summary",3600); |
|
Then when we update some content we simply call `rise()` to cleanup all dependent pages: |
|
on_update_article(article a) |
{ |
save_article_to_db(a); |
cache.rise("article_"+a.id); |
} |
|
Such triggers allows keep cache consistent in relatively simple way. |
|
|
## General Operations |
|
- **`void clear()`** -- clear all cache in the system. |
- **`bool stats(unsigned &keys,unsigned &triggers)`** -- fetch statistics from cache system. |
|
_Note:_ function returns false if cache system is disabled. |
