Difference between revisions of "Lazy Module"

From BaseX Documentation
Jump to navigation Jump to search
m (Typos)
Line 1: Line 1:
 
This [[Module Library|XQuery Module]] contains functions for handling ''lazy'' items.
 
This [[Module Library|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 contents has not been reqested yet.
+
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:
 
The following BaseX functions return lazy items:

Revision as of 17:07, 21 November 2017

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:

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:

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'))

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($item as item()) as item()
Summary Caches the contents of a lazy $item:
  • contents of lazy items will be retrieved and cached in the item.
  • non-lazy items or lazy items with cached contents will simply be passed through.

Caching of a lazy items is advisable if the the targeted contents will 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:
let $file := 'data.txt'
let $text := lazy:cache(file:read-text($file))
return (file:delete($file), $text)

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.0
  • Updated: Renamed from Streaming Module to Lazy Module.
  • Added: lazy:is-cached
Version 8.0

This module was introduced with Version 7.7.