Difference between revisions of "Lazy Module"
m (Text replacement - "<syntaxhighlight lang="xquery">" to "<pre lang='xquery'>") |
|||
Line 24: | Line 24: | ||
The XQuery expression below serves as an example on how large files can be downloaded and written to a file with constant memory consumption: | The XQuery expression below serves as an example on how large files can be downloaded and written to a file with constant memory consumption: | ||
− | < | + | <pre lang='xquery'> |
file:write-binary('output.data', fetch:binary('http://files.basex.org/xml/xmark111mb.zip')) | file:write-binary('output.data', fetch:binary('http://files.basex.org/xml/xmark111mb.zip')) | ||
</syntaxhighlight> | </syntaxhighlight> | ||
Line 55: | Line 55: | ||
| '''Example''' | | '''Example''' | ||
|In the following example, a file is 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 is deleted before its content is returned. To avoid a “file not found” error when serializing the result, the content must be cached: | ||
− | < | + | <pre lang='xquery'> |
let $file := 'data.txt' | let $file := 'data.txt' | ||
let $text := lazy:cache(file:read-text($file)) | let $text := lazy:cache(file:read-text($file)) |
Revision as of 18:30, 1 December 2023
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 processed. 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:
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 <code>http://basex.org/modules/lazy</code> namespace, which is statically bound to the {{Code|lazy}} prefix.<br/>
=Functions=
==lazy:cache==
{| width='100%'
|- valign="top"
| width='120' | '''Signature'''
|<pre>lazy:cache(
$input as item()*,
$lazy as xs:boolean? := false()
) as item()*
|- valign="top"
| Summary
|Caches the data of lazy $input
items:
- data of lazy items are retrieved and cached inside the item.
- non-lazy items, or lazy items with cached data, are simply passed through.
- If
$lazy
is set totrue()
, caching is deferred until the data is eventually requested. Streaming will be disabled: Data will be cached before a stream is returned.
Caching is advisable if an item is processed more than once, or if the data may not be available anymore at a later stage. |- valign="top" | Example |In the following example, a file is deleted before its content is returned. To avoid a “file not found” error when serializing the result, the content must be cached:
let $file := 'data.txt'
let $text := lazy:cache(file:read-text($file))
return (file:delete($file), $text)
</syntaxhighlight>
|}
==lazy:is-lazy==
{| width='100%'
|- valign="top"
| width='120' | '''Signature'''
|<pre>lazy:is-lazy(
$item as item()
) as xs:boolean
|- valign="top"
| Summary
|Checks whether the specified $item
is lazy.
|}
lazy:is-cached
Signature | 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.