Bureaucrats, editor, reviewer, Administrators
13,554
edits
Changes
Jump to navigation
Jump to search
m
Caching The store is advisable useful if data (a system configuration, maps serving as indexes) needs to be repeatedly accessed. The cache store is persistent: Contents will be written to disk at shutdown time, and the serialized cache store will be retrieved from disk as soon as the cache store is used for the first time. The cache store will be stored in a binary {{Code|cachestore.basex}} file in the database directory.
cachestore:put('version', 1),
cachestore:put('data', map { 'year': 2022 }),
cachestore:write()</syntaxhighlightpre>
Text replacement - "</syntaxhighlight>" to "</pre>"
This [[Module Library|XQuery Module]] provides functions to organize values in a persistent main-memory cachekey-value store.
In addition, custom caches stores can be read and written. Custom cache files use stores have filenames with the filename pattern {{Code|cachestore-NAME.basex}}. The implicit write of the standard cache store at shutdown time will be disabled if a custom cache store is used.
Functions of this module are non-deterministic 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 store have changed.
=Conventions=
All functions and errors in this module are assigned to the <code><nowiki>http://basex.org/modules/cachestore</nowiki></code> namespace, which is statically bound to the {{Code|cachestore}} prefix.<br/>
=Cache EntriesKey-value operations=
==cachestore:get==
{| width='100%'
|-valign="top"| width='120' | '''SignaturesSignature'''|{{Func|cache<pre>store:get|( $key as xs:string|) as item()*}}<br/ pre>|-valign="top"
|'''Summary'''
|Retrieves an entry from the cache store with the given {{Code|$key}}. If the addressed entry does not exist, an empty sequence is returned.
|}
==cachestore:put==
{| width='100%'
|-valign="top"| width='120' | '''SignaturesSignature'''|{{Func|cache<pre>store:put|( $key as xs:string, $value as item()*|) as empty-sequence()}}<br/ pre>|-valign="top"
|'''Summary'''
|Stores an entry with the given {{Code|$key}} and {{Code|$value}} in the cachestore:
* If the value is an empty sequence, the entry is removed.
* If a value refers to an opened database or is [[Lazy Module|a lazy item]], its contents are materialized in main memory.
|}
==cachestore:get-or-put==
{| width='100%'
|-valign="top"| width='120' | '''SignaturesSignature'''|{{Func|cache<pre>store:get-or-put|( $key as xs:string, $put as function(*)) as item()*|item()*}}<br/ pre>|-valign="top"
|'''Summary'''
|Retrieves an entry from the cache store with the given {{Code|$key}}. The {{Code|$put}} function will only be invoked if the entry does not exist, and its result will be stored and returned instead.
|}
==cachestore:remove==
{| width='100%'
|-valign="top"| width='120' | '''SignaturesSignature'''|{{Func|cache<pre>store:remove|( $key as xs:string|) as empty-sequence()}}<br/ pre>|-valign="top"
|'''Summary'''
|Removes an entry with the given {{Code|$key}} from the cachestore. No error will be raised if an addressed entry does not exist.
|}
==cachestore:keys==
{| width='100%'
|-valign="top"| width='120' | '''SignaturesSignature'''|{{Func|cache<pre>store:keys||() as xs:string*}}</pre>|-valign="top"
|'''Summary'''
|Lists the names of all keys.
|}
==cachestore:clear==
{| width='100%'
|-valign="top"| width='120' | '''SignaturesSignature'''|{{Func|cache<pre>store:clear||() as empty-sequence()}}<br/ pre>|-valign="top"
|'''Summary'''
|Resets the cache store by removing all its entries.
|}
=Cache Store Operations=
==cachestore:read==
{| width='100%'
|-valign="top"| width='120' | '''SignaturesSignature'''|{{Func|cache:read||empty-sequence()}}<br/ pre>{{Func|cachestore:read|( $name as xs:string|? := ()) as empty-sequence()}}</pre>|-valign="top"
|'''Summary'''
|Retrieves the standard cache store from disk, or a custom cache store if a {{Code|$name}} is supplied.|-valign="top"
|'''Errors'''
|{{Error|io|#Errors}} The cache store could not be read.<br/>{{Error|name|#Errors}} The specified name is invalid.<br/>{{Error|not-found|#Errors}} A cache store with the specified name does not exist.
|}
==cachestore:write==
{| width='100%'
|-valign="top"| width='120' | '''SignaturesSignature'''|{{Func|cache:write||empty-sequence()}}<br/ pre>{{Func|cachestore:write|( $name as xs:string|? := ()) as empty-sequence()}}</pre>|-valign="top"
|'''Summary'''
|Writes the standard cache store to disk, or to a custom cache store file if a {{Code|$name}} is supplied. If the standard cache store is empty, the cache store file will be deleted.|-valign="top"
|'''Errors'''
|{{Error|io|#Errors}} The cache store could not be written.<br/>{{Error|name|#Errors}} The specified name is invalid.
|}
==cachestore:list==
{| width='100%'
|-valign="top"| width='120' | '''SignaturesSignature'''|{{Func|cache<pre>store:list||() as xs:string*}}</pre>|-valign="top"
|'''Summary'''
|Lists the names of all custom cachesstores.
|}
==cachestore:delete==
{| width='100%'
|-valign="top"| width='120' | '''SignaturesSignature'''|{{Func|cache<pre>store:delete|( $name as xs:string|) as empty-sequence()}}</pre>|-valign="top"
|'''Summary'''
|Deletes a custom cache store from disk.|-valign="top"
|'''Errors'''
|{{Error|name|#Errors}} The specified name is invalid.<br/>{{Error|not-found|#Errors}} A cache store with the specified name does not exist.
|}
'''Use Case 1: Create/update a system configuration in a running BaseX server instance:
<syntaxhighlight pre lang="'xquery"'>
(: store an integer :)
(: retrieve existing or new value, store an element :)
let $license := cachestore:get-or-put('license', function() { 'free' })return cachestore:put('info', <info>{ $license = 'free' ?? 'Free' !! 'Professional' } License</info>),
(: store a map :)
(: serialize configuration to disk :)
The configuration can be requested by further operations, e.g. a client request:
<syntaxhighlight pre lang="'xquery"'>cachestore:get('version')</syntaxhighlightpre>
The cache store will still be available if BaseX is restarted until it is cleared.
'''Use Case 2: Create index for fast lookup operations in the GUI:
<syntaxhighlight pre lang="'xquery"'>
let $map := map:merge(
for $country in db:openget('factbook')//country
for $religion in $country//religions
group by $religion
return map:entry($religion, data($country/@name))
)
return cachestore:put('religions', $map)</syntaxhighlightpre>
A subsequent query can be used to access its contents:
<syntaxhighlight pre lang="'xquery"'>cachestore:get('religions')?Buddhism</syntaxhighlightpre>
Note that the cache store will eventually be written to disk unless it is invalidated before closing the GUI.
=Errors=
! width="110"|Code
|Description
|-valign="top"
|{{Code|io}}
| The cache store could not be read or written.|-valign="top"
|{{Code|name}}
| The specified name is invalid.
|-valign="top"
|{{Code|not-found}}
| A cache store with the specified name does not exist.
|}
