Main  /  Edit version 9  /  Edit version 10  /   /  Users Area

Difference "cppcms::cache_iface" ver. 9 versus ver. 10

Content:

## Table of Contents
- [Role](#role)
- [Objects stored in cache](#obj)
- [General](#gen)
- [Trigger-less Cache](#tlc)
- [Web Pages](#tlc1)
- [C++ Objects and HTML Frames](#tlc2)
- [Cache with triggers](#trig)
- [Concept](#concept)
- [Manual Triggers Management](#man)
- [Semi-automatic Triggers Management](#auto)
- [Triggers for objects](#tobj)
- [Notes](#not)
- [General Functions](#func)
## <span id="role"></span>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.
## <span id="obj"></span>Objects that are stored in cache:
Various objects can be stored in cache using unique key.
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.
3. [Serializable](/wikipp/en/page/ref_cppcms_serializable) objects.
Each one of them has little bit different semantics and API.
_Note:_ Keys starting with underscore "_" are reserved for internal CppCMS use.
## <span id="gen"></span>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
## <span id="tlc"></span>Trigger-less cache access
### <span id="tlc1"></span>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.
### <span id="tlc2"></span>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.
## <span id="trig"></span>Triggers based cache
### <span id="concept"></span>Concept
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 #1234 in blog that may be displayed in several places:
- Summary of all topics (summary)
- Rss feed (rss)
- Summary for specific category #5 it belongs to.
- Article itself
So the structure of triggers may look like this
- `summary` depends on `article_1234`, `article_1233` and `article_1232`, `summary`
- `rss` would depend on `article_1234` up to `article_1224` and `rss`
- `cat_5` would depend on `article_1234` and `article_1100` and `cat_5`
- `post_1234` would depend on `article_1234` and `post_1234`.
So, if we "rise" trigger `article_1234` by calling `rise("article_1234")`, all these cached entries would be automatically dropped.
So every cached object has a set of triggers associated with it that would cause its cleanup. This is the general idea of CppCMS cache system.
### <span id="man"></span>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:
void 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.
### <span id="auto"></span>Semi-automatic dependencies management
CppCMS cache system provides some automation of dependencies management.
For example, if you have general cached C++ objects or some prepared HTML parts like headers, footers, than you may want to make sure that their updates would cause cleanup of dependent pages and keeping them consistent.
When you call `store_frame`, `store_data`, `fetch_frame`, `fetch_data` with parameter `notriggers` set to **false** (this is default) it's triggers are automatically added to dependencies of current page.
For example:
if(cache.fetch_page("main"))
return;
if(!cache.fetch_data("options",opts)) {
load_opts(opts);
cache.store_data("options",opts);
}
/// Generate some HTML here
cache.store_page("main");
Because we call `fetch_data` and `store_data` with default parameter `notriggers=false` --- trigger "options" is automatically added to key "main"
So next time, you update "options" and rise it's trigger, all pages that actually used options would be automatically cleaned up.
### <span id="tobj"></span>Setting Triggers for Stored Objects
You can also manage triggers for stored objects:
void store_frame(string const &key,
string const &frame,
set<string> const &trig=set<string>(),
int timeout=-1,
bool notriggers=false);
void store_data(string const &key,
serializable const &data,
set<string> const &trig=set<string>(),
int timeout=-1,
bool notriggers=false);
You can specify the set of trigger for specific object and define whether you want them to be added to current page triggers set.
_Note:_ You should specify these dependencies manually.
For example:
if(cache.fetch_page("main"))
return;
if(!cache.fetch_data("options",opts)) {
load_opts(opts);
cache.store_data("options",opts);
}
if(!cache.fetch_frame("sidebar",sidebar)) {
/// Generate sidebar
set<string> tags;
tags.insert("options");
cache.store_frame("sidebar",sidebar,tags);
}
/// Generate some HTML here using sidebar;
cache.store_page("main");
Now, in this case, `main` depends on `sidebar` and `options` and `sidebar` depends on `options` only.
### <span id="not"></span>Some Important Notes
- Storing data is cache never rises its trigger. You should rise trigger manually
- If you manage cache consistency correctly you may never use timeouts at all
- In some cases, full cache consistency may hurt performance (think of sidebar that includes hits statistics) and cleanup pages too frequently.
In such cases, it is better to work without full triggers, but in this case you must specify reasonable timeouts.
- Function **`void reset();`** allows to clear all triggers that where added to current page.
## <span id="func"></span>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.

About

CppCMS is a web development framework for performance demanding applications.

Support This Project

SourceForge.net Logo

Поддержать проект

CppCMS needs You


Navigation

Main Page


Valid CSS | Valid XHTML 1.0