Caching Rows in a Proxy

The proxy can cache rows from a checkpoint in memory to improve read performance. It is an optional process. If a proxy is enabled for checkpoint row caching, the output of the checkpoint get operation is obtained from the cache of the proxy. If the row is not present in the cache, the proxy obtains the row from the nodes and caches the result. When the proxy restarts, the cached information is lost. Query and iterator result rows are not cached.

For more information about how to specify a checkpoint name in the get operation, see Checkpoint Properties.

Configuration

By default, the cache size is 0 and the caching of checkpoint rows is disabled. To enable caching of checkpoint rows for all proxies in a grid or individual proxies, set the maximum size of the cache, in bytes, in the grid property proxy_checkpoint_cache_size. For example, tibdg proxy modify p1 proxy_checkpoint_cache_size=100000000. If the proxy property is set, it overrides the grid property, including disabling of caching by setting the property to 0 (tibdg proxy modify p1 proxy_checkpoint_cache_size=0). If the proxy_checkpoint_cache_size property is modified (either for the grid or proxy) while the proxy is running, the proxy must be restarted for the new value to take effect.

The proxy_checkpoint_cache_size property is a soft limit. The cache may exceed the limit if the cache is full and a new row is fetched from a checkpoint. When the cache is full, the cache uses the least recently used (LRU) algorithm to evict rows.

Client Usage

To refer to the latest successful checkpoint known by a proxy, clients can use the special checkpoint names:

• On a session object: TIBDG_SESSION_CHECKPOINT_NAME_LATEST

• On a table object: TIBDG_TABLE_CHECKPOINT_NAME_LATEST

This checkpoint name is useful for clients that want to read from the latest checkpoint without knowing the checkpoint name, or for grids that are configured to create periodic checkpoints automatically.

If a checkpoint is deleted, the cache of a proxy is not cleared immediately. However, rows from a deleted checkpoint are not obtained from the cache. The memory is reclaimed as the rows are removed from the cache.

At all times, the cache is populated with the rows that are explicitly requested by a client.

Client API Example

When the scope of the checkpoint name property is a table, a client can read from a checkpoint or live data by using the same session object. It is useful for reference tables that are updated infrequently and can be cached in the proxy for faster read performance, whereas other read operations are performed by using live data.

Here is an example API using C language:

tibdgSession session = tibdgConnection_CreateSession(ex, connection, NULL);
// Session is created with empty properties - no checkpoint.
tibdgTable t1 = tibdgSession_OpenTable(ex, session, “t1”, NULL);
// tibdgTable t1 opened on live data
tibProperties props = tibProperties_Create(ex);
tibProperties_SetString(ex, props, TIBDG_TABLE_PROPERTY_STRING_CHECKPOINT_NAME, “c1”);
tibdgTable c1_t1 = tibdgSession_OpenTable(ex, session, “t1”, props);
// tibdgTable c1_t1 opened on checkpoint c1
tibProperties_SetString(ex, props, TIBDG_TABLE_PROPERTY_STRING_CHECKPOINT_NAME, TIBDG_TABLE_CHECKPOINT_NAME_LATEST);
tibdgTable cLatest_t1 = tibdgSession_OpenTable(ex, session, “t1”, props);
// tibdgTable cLatest_t1 opened on the latest successful checkpoint
tibdgRow t1_key = tibdgRow_Create(ex, t1);
tibdgRow_SetLong(ex, t1_key, "key", 0);
tibdgRow t1_live_row = tibdgTable_Get(ex, t1, t1_key);
// row t1_live_row contains row from live data
// live data is not cached in the proxy
tibdgRow c1_t1_key = tibdgRow_Create(ex, c1_t1);
tibdgRow_SetLong(ex, c1_t1_key, "key", 0);
tibdgRow c1_t1_row = tibdgTable_Get(ex, c1_t1, c1_t1_key);
// row c1_t1_row contains row from checkpoint c1
tibdgRow cLatest_t1_key = tibdgRow_Create(ex, cLatest_t1);
tibdgRow_SetLong(ex, cLatest_t1_key, "key", 0);
tibdgRow cLatest_t1_row = tibdgTable_Get(ex, cLatest_t1, cLatest_t1_key);
// row cLatest_t1_row contains row from the latest checkpoint known by the proxy