Main Page » Cache Functions

Cache Functions

Added: New Module.

This module provides functions to store transient data in main-memory caches.

Computing a result can be expensive. If it is frequently needed, for example in a Web Application, it can be cheaper to cache it in main memory. The architecture has the following properties:

  • Data can be distributed across multiple caches, which are identified by names. If no name is specified in a cache operation, data is stored in the default cache (named "").
  • A single cache is limited to a maximum number of entries, defined by CACHEMAX. The number can be adjusted at startup time, depending on server characteristics.
  • The caches use the LRU replacement policy: Least recently used entries are dropped first.

The Key-/Value Store provides similar functionality, but entries in the store never expire, and can be made persistent.

Functions of this module are nondeterministic and side-effecting: Updates will immediately be visible, and a repeated call of the same function may yield different results if the contents of the cache have changed.

Conventions

All functions and errors in this module are assigned to the http://basex.org/modules/cache namespace, which is statically bound to the cache prefix.

Key-value Operations

cache:get

Signature
cache:get(
  $key   as xs:string,
  $name  as xs:string?  := ""
) as item()*
SummaryRetrieves an entry with the given $key from the default cache, or from a custom cache if $name is specified:
  • If the addressed entry does not exist, an empty sequence is returned.
  • When a cache entry is accessed, it will remain longer in the cache.

cache:put

Signature
cache:put(
  $key    as xs:string,
  $value  as item()*,
  $name   as xs:string?  := ""
) as empty-sequence()
SummaryStores an entry with the given $key and $value in the default cache, or in a custom cache if $name is specified:
  • If the addressed store does not exist yet, it will be created automatically.
  • Before a value is stored, it is compactified (see prof:shrink for more information).
  • Additionally, if a value refers to an opened database or is a lazy item, its contents are materialized in main memory.
  • Values with function items are rejected.

cache:get-or-put

Signature
cache:get-or-put(
  $key   as xs:string,
  $put   as fn() as item()*,
  $name  as xs:string?       := ""
) as item()*
SummaryRetrieves an entry with the given $key from the default cache, or from a custom cache if $name is specified. The $put function will only be invoked if the entry does not exist, and its result will be cached and returned instead.

cache:size

Signature
cache:size(
  $name  as xs:string?  := ""
) as xs:integer
SummaryReturns the number of entries in the default cache, or in a custom cache if $name is specified.

Organize Caches

cache:list

Signature
cache:list() as xs:string*
SummaryLists the names of all custom caches.

cache:delete

Signature
cache:delete(
  $name  as xs:string?  := ""
) as empty-sequence()
SummaryRemoves all entries from the default cache, or deletes a custom cache if $name is specified.

cache:clear

Signature
cache:clear() as empty-sequence()
SummaryClears the default cache and removes all other caches.

Examples

Use Case: Cache RESTXQ responses 
declare
  %rest:path('/person/{$name}')
function local:search(
  $name  as xs:string
) as element()* {
  let $result := fn() { db:get('persons')//person/name[text() contains text { $name }] }
  return cache:get-or-put('person:' || $name, $result)
};

If many clients request the same RESTXQ endpoint, it can be cheaper to cache the result instead of computing it again and again. In this example, person data is looked up in a database. If a cache entry for the given person exists, a previously computed result will be returned. Otherwise, the result will be generated and returned to the client.

Changelog

Version 13
  • Added: New module.
⚡Generated with XQuery
 
Login | Changelog | TOC | Imprint
Cache Functions