Bureaucrats, editor, reviewer, Administrators
13,550
edits
Changes
Jump to navigation
Jump to search
asyncjobs:eval($query)
asyncjobs:result($id)
asyncjobs:result($query)
|-
|{{Code|unexpected}}
| An unexpected error occurred while running a query or function in a separate thread.
no edit summary
This [[Module Library|XQuery Module]] provides functions for evaluating XQuery expressions in separate threads. Query execution can both be parallelized organizing running commands and postponed queries (mor to be executed asynchronouslycome).
=Conventions=
All functions in this module are assigned to the <code><nowiki>http://basex.org/modules/asyncjobs</nowiki></code> namespace, which is statically bound to the {{Code|asyncjobs}} prefix. Errors will be bound to the same prefix.
=Asynchronous Execution=
Asynchronous query execution is recommendable if a client does not, or cannot, wait until a request is fully processed. This is e. g. the case with web browsers, which will usually cancel a request after a specific timeout. In such cases, you can use asynchronous execution to trigger another server-side process, which will start the time-consuming process, and fetch the result later on as soon as it is available.
==asyncjobs:eval==
{| width='100%'
|-
| width='120' | '''Signatures'''
|{{Func|asyncjobs:eval|$query as xs:string|xs:string}}<br />{{Func|asyncjobs:eval|$query as xs:string, $bindings as map(*)|xs:string}}<br />{{Func|asyncjobs:eval|$query as xs:string, $bindings as map(*), $options as map(xs:string, xs:string)|xs:string}}<br />
|-
| '''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]], and the result will be cached in main-memory until it is fetched via [[#asyncjobs:result|asyncjobs:result]], or until {{Option|ASYNCTIMEOUT}} is exceeded. Queries may be updating.<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|cache}}: indicates if the query result will be cached or ignored (default: <code>true</code>). If the query result will not be cached, the query id will immediately be discarded after query execution, too.
* {{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}} (default: ''empty string'').
| '''Examples'''
|
* {{Code|asyncjobs:eval("1+3")}} returns a query id, e.g. {{Code|Query-abc}}. The result can be retrieved via a second query in the same BaseX context: {{Code|asyncjobs:result("Query-abc")}}<br />
* The following [[RESTXQ]] function will return the id of the query thread, which evaluates the query that has been specified in the body of a POST request:
<pre class='brush:xquery'>
declare %rest:POST("{$query}") %rest:path('/eval') function local:eval($query) {
};
</pre>
|}
==asyncjobs:result==
{| width='100%'
|-
| width='120' | '''Signatures'''
|{{Func|asyncjobs:result|$id as xs:string|item()*}}
|-
| '''Summary'''
|-
| '''Errors'''
|{{Error|is-running|#Errors}} the query is still running.<br/>{{Error|unknown|#Errors}} the supplied query id is unknown: The query result may already have been retrieved, or query execution may have been stopped.<br/>
|-
| '''Examples'''
<pre class='brush:xquery'>
declare %rest:path('/result/{$id}') function local:result($id) {
};
</pre>
* The following query demonstrates how the results of an asynchronously executed query can be returned in a single query. Please remember that this is not the common way how these functions are used in practice:
<pre class='brush:xquery'>
let $query := asyncjobs:eval('(1 to 10000000)[. = 1]')
return (
hof:until(
function($result) { asyncjobs:finished($query) },
function($curr) { prof:sleep(10) },
()
),
)
</pre>
|}
==asyncjobs:finished==
{| width='100%'
|-
| width='120' | '''Signatures'''
|{{Func|asyncjobs:finished|$id as xs:string|xs:boolean}}
|-
| '''Summary'''
|}
==asyncjobs:stop==
{| width='100%'
|-
| width='120' | '''Signatures'''
|{{Func|asyncjobs:stop|$id as xs:string|empty-sequence()}}
|-
| '''Summary'''
|}
==asyncjobs:ids==
{| width='100%'
|-
| width='120' | '''Signatures'''
|{{Func|asyncjobs:ids||xs:string*}}
|-
| '''Summary'''
| '''Examples'''
|
* <code>asyncjobs:ids() ! asyncjobs:stop(.)</code> stops and invalidates all asynchronous queries and results.
|}
! width="110"|Code
|Description
|-
|{{Code|unknown}}
| The supplied query id is unknown or not available anymore.
|-
|{{Code|is-running}}
| A query is still running.
|-
