Difference between revisions of "Lazy Module"
Line 39: | Line 39: | ||
{| width='100%' | {| width='100%' | ||
− | |- | + | |- valign="top" |
| width='120' | '''Signatures''' | | width='120' | '''Signatures''' | ||
|{{Func|lazy:cache|$items as item()*|item()*}}<br/>{{Func|lazy:cache|$items as item()*, $lazy as xs:boolean|item()*}} | |{{Func|lazy:cache|$items as item()*|item()*}}<br/>{{Func|lazy:cache|$items as item()*, $lazy as xs:boolean|item()*}} | ||
− | |- | + | |- valign="top" |
| '''Summary''' | | '''Summary''' | ||
|Caches the data of lazy {{Code|$items}} in a sequence:<br /> | |Caches the data of lazy {{Code|$items}} in a sequence:<br /> | ||
Line 49: | Line 49: | ||
* If {{Code|$lazy}} is set to {{Code|true()}}, caching will be deferred until the data is eventually requested. Streaming will be disabled: Data will always be cached before a stream is returned. | * If {{Code|$lazy}} is set to {{Code|true()}}, caching will be deferred until the data is eventually requested. Streaming will be disabled: Data will always be cached before a stream is returned. | ||
Caching is advisable if an item will be processed more than once, or if the data may not be available anymore at a later stage. | Caching is advisable if an item will be processed more than once, or if the data may not be available anymore at a later stage. | ||
− | |- | + | |- valign="top" |
| '''Example''' | | '''Example''' | ||
|In the following example, a file will be deleted before its content is returned. To avoid a “file not found” error when serializing the result, the content must be cached: | |In the following example, a file will be deleted before its content is returned. To avoid a “file not found” error when serializing the result, the content must be cached: | ||
Line 62: | Line 62: | ||
{| width='100%' | {| width='100%' | ||
− | |- | + | |- valign="top" |
| width='120' | '''Signatures''' | | width='120' | '''Signatures''' | ||
|{{Func|lazy:is-lazy|$item as item()|xs:boolean}} | |{{Func|lazy:is-lazy|$item as item()|xs:boolean}} | ||
− | |- | + | |- valign="top" |
| '''Summary''' | | '''Summary''' | ||
|Checks whether the specified {{Code|$item}} is lazy. | |Checks whether the specified {{Code|$item}} is lazy. | ||
Line 73: | Line 73: | ||
{| width='100%' | {| width='100%' | ||
− | |- | + | |- valign="top" |
| width='120' | '''Signatures''' | | width='120' | '''Signatures''' | ||
|{{Func|lazy:is-cached|$item as item()|xs:boolean}} | |{{Func|lazy:is-cached|$item as item()|xs:boolean}} | ||
− | |- | + | |- valign="top" |
| '''Summary''' | | '''Summary''' | ||
|Checks whether the contents of the specified {{Code|$item}} are cached. The function will always return {{Code|true}} for non-lazy items. | |Checks whether the contents of the specified {{Code|$item}} are cached. The function will always return {{Code|true}} for non-lazy items. |
Revision as of 14:18, 20 July 2022
This XQuery Module contains functions for handling lazy items.
In contrast to standard XQuery items, a lazy item contains a reference to the actual data, and the data itself will only be retrieved if it is requested. Hence, possible errors will be postponed, and no memory will be occupied by a lazy item as long as its content has not been requested yet.
The following BaseX functions return lazy items:
- Lazy Base64 binaries:
- Lazy strings:
Some functions are capable of consuming the contents of lazy items in a streamable fashion: data will not be cached, but instead passed on to another target (file, the calling expression, etc.). The following streaming functions are currently available:
- Archive Module (most functions)
- Conversion Module:
convert:binary-to-string
- File Module:
file:write-binary-text
,file:write-text
(if no encoding is specified) - Database Module:
db:put-binary
- Hashing Module (all functions)
The XQuery expression below serves as an example on how large files can be downloaded and written to a file with constant memory consumption:
<syntaxhighlight lang="xquery"> file:write-binary('output.data', fetch:binary('http://files.basex.org/xml/xmark111mb.zip')) </syntaxhighlight>
If lazy items are serialized, they will be streamed as well.
Conventions
All functions and errors in this module are assigned to the http://basex.org/modules/lazy
namespace, which is statically bound to the lazy
prefix.
Functions
lazy:cache
Signatures | lazy:cache($items as item()*) as item()* lazy:cache($items as item()*, $lazy as xs:boolean) as item()*
|
Summary | Caches the data of lazy $items in a sequence:
Caching is advisable if an item will be processed more than once, or if the data may not be available anymore at a later stage. |
Example | In the following example, a file will be deleted before its content is returned. To avoid a “file not found” error when serializing the result, the content must be cached:
<syntaxhighlight lang="xquery"> let $file := 'data.txt' let $text := lazy:cache(file:read-text($file)) return (file:delete($file), $text) </syntaxhighlight> |
lazy:is-lazy
Signatures | lazy:is-lazy($item as item()) as xs:boolean
|
Summary | Checks whether the specified $item is lazy.
|
lazy:is-cached
Signatures | lazy:is-cached($item as item()) as xs:boolean
|
Summary | Checks whether the contents of the specified $item are cached. The function will always return true for non-lazy items.
|
Changelog
- Version 9.1
- Updated:
lazy:cache
:$lazy
argument added; support for sequences.
- Version 9.0
- Updated: Renamed from Streaming Module to Lazy Module.
- Added:
lazy:is-cached
- Version 8.0
- Updated:
stream:materialize
extended to sequences.
This module was introduced with Version 7.7.