Difference between revisions of "Job Module"
Jump to navigation
Jump to search
Line 51: | Line 51: | ||
|- | |- | ||
| '''Summary''' | | '''Summary''' | ||
− | |Prepares the supplied {{Code|$query}} string for asynchronous execution and returns a query id. The query will be queued as described in the article on [[Transaction Management]].<br/>Variables and context items can be declared via {{Code|$bindings}} (see [[XQuery Module#xquery:eval|xquery:eval]] for more details). The {{Code|$options}} parameter contains evaluation options: | + | |Prepares the supplied {{Code|$query}} string for asynchronous execution and returns a query id. The query will be queued as described in the article on [[Transaction Management]], and the result will be cached in main-memory until it is fetched via [[#async:result|async:result]], or until {{Option|ASYNCTIMEOUT}} is exceeded.<br/>Variables and context items can be declared via {{Code|$bindings}} (see [[XQuery Module#xquery:eval|xquery:eval]] for more details). The {{Code|$options}} parameter contains evaluation options: |
* {{Code|check}}: indicates if the query result will be cached. | * {{Code|check}}: indicates if the query result will be cached. | ||
* {{Code|base-uri}}: set [https://www.w3.org/TR/xquery-31/#dt-static-base-uri base-uri property] for the query. This URI will be used when resolving relative URIs by functions such as {{Code|fn:doc}}. | * {{Code|base-uri}}: set [https://www.w3.org/TR/xquery-31/#dt-static-base-uri base-uri property] for the query. This URI will be used when resolving relative URIs by functions such as {{Code|fn:doc}}. |
Revision as of 17:20, 1 March 2016
This XQuery Module provides functions for evaluating XQuery expressions in separate threads. Query execution can both be parallelized and postponed to be executed asynchronously.
Contents
Conventions
All functions in this module are assigned to the http://basex.org/modules/async
namespace, which is statically bound to the async
prefix. Errors will be bound to the same prefix.
Parallelized Execution
async:fork-join
Signatures | async:fork-join($functions as function(*)*) as item()* async:fork-join($functions as function(*)*, $options as map(xs:string, xs:string)) as item()* |
Summary | This function executes the supplied functions in parallel. The following $options are available:
|
Examples |
async:fork-join( for $i in 1 to 2 return function() { prof:sleep(1000) } )
let $funcs := for $segment in 1 to 4 let $url := 'http://url.com/path' || $segment return function() { http:send-request((), $url) } return async:fork-join($funcs, map { 'threads': 2 }) |
Errors | unexpected : an unexpected error occurred while running a query or function in a separate thread.out-of-range : a supplied option is out of range. |
Asynchronous Execution
async:eval
Signatures | async:eval($query as xs:string) as xs:string async:eval($query as xs:string, $bindings as map(*)) as xs:string async:eval($query as xs:string, $bindings as map(*), $options as map(xs:string, xs:string)) as xs:string |
Summary | Prepares the supplied $query string for asynchronous execution and returns a query id. The query will be queued as described in the article on Transaction Management, and the result will be cached in main-memory until it is fetched via async:result, or until ASYNCTIMEOUT is exceeded.Variables and context items can be declared via $bindings (see xquery:eval for more details). The $options parameter contains evaluation options:
|
Errors | updating : the query contains update operations.
|
Examples |
|
async:update
Signatures | async:update($query as xs:string) as xs:string async:update($query as xs:string, $bindings as map(*)) as xs:string async:update($query as xs:string, $bindings as map(*), $options as map(xs:string, xs:string)) as xs:string |
Summary | Prepares the supplied $query string for asynchronous execution and returns a query id. The query will be queued as described in the article on Transaction Management.See async:eval for information on the $bindings and $options arguments.
|
Errors | non-updating : the query does not contain any update operations. |
Examples |
|
async:result
Signatures | async:result($id as xs:string) as item()*
|
Summary | Returns the result of an asynchronously executed query with the specified query $id :
|
Errors | is-running : the query is still running.unknown : the supplied query id is unknown: The query result may already have been retrieved, or query execution may have been stopped. |
Examples | The following query returns the results of an asynchronously executed query. It will succeed, because both the main and the asynchronous query do not include write operations on concurrently used databases:
let $query := async:eval('(1 to 10000000)[. = 1]') return ( hof:until( function($result) { not(async:is-running($query)) }, function($curr) { prof:sleep(10) }, () ), async:result($query) ) |
async:is-running
Signatures | async:is-running($id as xs:string) as xs:boolean
|
Summary | Indicates if a query with the specified query $id is currently being evaluated.
|
Errors | unknown : the supplied query id is unknown: The query result may already have been retrieved, or query execution may have been stopped. |
async:stop
Signatures | async:stop($id as xs:string) as empty-sequence()
|
Summary | Cancels the execution of a query with the specified query $id .
|
Errors | unknown : the supplied query id is unknown: The query result may already have been retrieved, or query execution may have been stopped. |
Errors
Code | Description |
---|---|
unexpected
|
An unexpected error occurred while running a query or function in a separate thread. |
out-of-range
|
The supplied option is out of range. |
updating
|
A query is expected to be non-updating, but it performs updates. |
non-updating
|
A query is expected to be updating, but it does not perform updates. |
unknown
|
The supplied query id is unknown or not available anymore. |
is-running
|
A query is still running. |
Changelog
The module was introduced with Version 8.5.