Difference between revisions of "Job Module"

From BaseX Documentation
Jump to navigation Jump to search
Line 1: Line 1:
−
This [[Module Library|XQuery Module]] provides functions for evaluating XQuery expressions in separate threads. Query execution can both be parallelized and postponed to be executed asynchronously.
+
This [[Module Library|XQuery Module]] provides functions for organizing running commands and queries (mor to come).
  
 
=Conventions=
 
=Conventions=
  
−
All functions in this module are assigned to the <code><nowiki>http://basex.org/modules/async</nowiki></code> namespace, which is statically bound to the {{Code|async}} prefix. Errors will be bound to the same prefix.
+
All functions in this module are assigned to the <code><nowiki>http://basex.org/modules/jobs</nowiki></code> namespace, which is statically bound to the {{Code|jobs}} prefix. Errors will be bound to the same prefix.
  
 
=Asynchronous Execution=
 
=Asynchronous Execution=
Line 9: Line 9:
 
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.
 
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.
  
−
==async:eval==
+
==jobs:eval==
  
 
{| width='100%'
 
{| width='100%'
 
|-
 
|-
 
| width='120' | '''Signatures'''
 
| width='120' | '''Signatures'''
−
|{{Func|async:eval|$query as xs:string|xs:string}}<br />{{Func|async:eval|$query as xs:string, $bindings as map(*)|xs:string}}<br />{{Func|async:eval|$query as xs:string, $bindings as map(*), $options as map(xs:string, xs:string)|xs:string}}<br />
+
|{{Func|jobs:eval|$query as xs:string|xs:string}}<br />{{Func|jobs:eval|$query as xs:string, $bindings as map(*)|xs:string}}<br />{{Func|jobs:eval|$query as xs:string, $bindings as map(*), $options as map(xs:string, xs:string)|xs:string}}<br />
 
|-
 
|-
 
| '''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]], and the result will be cached in main-memory until it is fetched via [[#async:result|async: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:
+
|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 [[#jobs:result|jobs: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|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'').
 
* {{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'').
Line 26: Line 26:
 
| '''Examples'''
 
| '''Examples'''
 
|
 
|
−
* {{Code|async: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|async:result("Query-abc")}}<br />
+
* {{Code|jobs: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|jobs: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:
 
* 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'>
 
<pre class='brush:xquery'>
 
declare %rest:POST("{$query}") %rest:path('/eval') function local:eval($query) {
 
declare %rest:POST("{$query}") %rest:path('/eval') function local:eval($query) {
−
   async:eval($query)
+
   jobs:eval($query)
 
};
 
};
 
</pre>
 
</pre>
 
|}
 
|}
  
−
==async:result==
+
==jobs:result==
  
 
{| width='100%'
 
{| width='100%'
 
|-
 
|-
 
| width='120' | '''Signatures'''
 
| width='120' | '''Signatures'''
−
|{{Func|async:result|$id as xs:string|item()*}}
+
|{{Func|jobs:result|$id as xs:string|item()*}}
 
|-
 
|-
 
| '''Summary'''
 
| '''Summary'''
Line 48: Line 48:
 
|-
 
|-
 
| '''Errors'''
 
| '''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/>
+
|{{Error|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'''
 
| '''Examples'''
Line 55: Line 55:
 
<pre class='brush:xquery'>
 
<pre class='brush:xquery'>
 
declare %rest:path('/result/{$id}') function local:result($id) {
 
declare %rest:path('/result/{$id}') function local:result($id) {
−
   async:result($id)
+
   jobs:result($id)
 
};
 
};
 
</pre>
 
</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:
 
* 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'>
 
<pre class='brush:xquery'>
−
let $query := async:eval('(1 to 10000000)[. = 1]')
+
let $query := jobs:eval('(1 to 10000000)[. = 1]')
 
return (
 
return (
 
   hof:until(
 
   hof:until(
−
     function($result) { async:finished($query) },
+
     function($result) { jobs:finished($query) },
 
     function($curr) { prof:sleep(10) },
 
     function($curr) { prof:sleep(10) },
 
     ()
 
     ()
 
   ),
 
   ),
−
   async:result($query)
+
   jobs:result($query)
 
)
 
)
 
</pre>
 
</pre>
 
|}
 
|}
  
−
==async:finished==
+
==jobs:finished==
  
 
{| width='100%'
 
{| width='100%'
 
|-
 
|-
 
| width='120' | '''Signatures'''
 
| width='120' | '''Signatures'''
−
|{{Func|async:finished|$id as xs:string|xs:boolean}}
+
|{{Func|jobs:finished|$id as xs:string|xs:boolean}}
 
|-
 
|-
 
| '''Summary'''
 
| '''Summary'''
Line 86: Line 86:
 
|}
 
|}
  
−
==async:stop==
+
==jobs:stop==
  
 
{| width='100%'
 
{| width='100%'
 
|-
 
|-
 
| width='120' | '''Signatures'''
 
| width='120' | '''Signatures'''
−
|{{Func|async:stop|$id as xs:string|empty-sequence()}}
+
|{{Func|jobs:stop|$id as xs:string|empty-sequence()}}
 
|-
 
|-
 
| '''Summary'''
 
| '''Summary'''
Line 100: Line 100:
 
|}
 
|}
  
−
==async:ids==
+
==jobs:ids==
  
 
{| width='100%'
 
{| width='100%'
 
|-
 
|-
 
| width='120' | '''Signatures'''
 
| width='120' | '''Signatures'''
−
|{{Func|async:ids||xs:string*}}
+
|{{Func|jobs:ids||xs:string*}}
 
|-
 
|-
 
| '''Summary'''
 
| '''Summary'''
Line 112: Line 112:
 
| '''Examples'''
 
| '''Examples'''
 
|
 
|
−
* <code>async:ids() ! async:stop(.)</code> stops and invalidates all asynchronous queries and results.
+
* <code>jobs:ids() ! jobs:stop(.)</code> stops and invalidates all asynchronous queries and results.
 
|}
 
|}
  
Line 120: Line 120:
 
! width="110"|Code
 
! width="110"|Code
 
|Description
 
|Description
−
|-
 
−
|{{Code|unexpected}}
 
−
| An unexpected error occurred while running a query or function in a separate thread.
 
 
|-
 
|-
 
|{{Code|unknown}}
 
|{{Code|unknown}}
 
| The supplied query id is unknown or not available anymore.
 
| The supplied query id is unknown or not available anymore.
 
|-
 
|-
−
|{{Code|is-running}}
+
|{{Code|running}}
 
| A query is still running.
 
| A query is still running.
 
|-
 
|-

Revision as of 11:46, 26 June 2016

This XQuery Module provides functions for organizing running commands and queries (mor to come).

Conventions

All functions in this module are assigned to the http://basex.org/modules/jobs namespace, which is statically bound to the jobs 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.

jobs:eval

Signatures jobs:eval($query as xs:string) as xs:string
jobs:eval($query as xs:string, $bindings as map(*)) as xs:string
jobs: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 jobs:result, or until ASYNCTIMEOUT is exceeded. Queries may be updating.
Variables and context items can be declared via $bindings (see xquery:eval for more details). The $options parameter contains evaluation options:
  • cache: indicates if the query result will be cached or ignored (default: true). If the query result will not be cached, the query id will immediately be discarded after query execution, too.
  • base-uri: set base-uri property for the query. This URI will be used when resolving relative URIs by functions such as fn:doc (default: empty string).
Errors overflow: Too many queries or query results are queued. To fix this, the query results should be retrieved.
Examples
  • jobs:eval("1+3") returns a query id, e.g. Query-abc. The result can be retrieved via a second query in the same BaseX context: jobs:result("Query-abc")
  • 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:
declare %rest:POST("{$query}") %rest:path('/eval') function local:eval($query) {
  jobs:eval($query)
};

jobs:result

Signatures jobs:result($id as xs:string) as item()*
Summary Returns the result of an asynchronously executed query with the specified query $id:
  • Results can only be retrieved once. After retrieval, the cached result will be discarded.
  • If the query raised an error, the error will be raised instead.
Errors 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 RESTXQ function will either return the result of a previously started query or an error:
declare %rest:path('/result/{$id}') function local:result($id) {
  jobs:result($id)
};
  • 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:
let $query := jobs:eval('(1 to 10000000)[. = 1]')
return (
  hof:until(
    function($result) { jobs:finished($query) },
    function($curr) { prof:sleep(10) },
    ()
  ),
  jobs:result($query)
)

jobs:finished

Signatures jobs:finished($id as xs:string) as xs:boolean
Summary Indicates if the evaluation of a query with the specified query $id has finished. If false is returned, the query is still running. An error will be raised if the query result was not cached or has already been retrieved.
Errors unknown: the supplied query id is unknown: The query result may already have been retrieved, or query execution may have been stopped.

jobs:stop

Signatures jobs:stop($id as xs:string) as empty-sequence()
Summary Cancels the execution of a query with the specified query $id, or drops the query result if it has already been executed.
Errors unknown: the supplied query id is unknown: The query result may already have been retrieved, or query execution may have been stopped.

jobs:ids

Signatures jobs:ids() as xs:string*
Summary Returns the ids of all queries that are either being executed asynchronously, or that have been executed and the results of which have been cached.
Examples
  • jobs:ids() ! jobs:stop(.) stops and invalidates all asynchronous queries and results.

Errors

Code Description
unknown The supplied query id is unknown or not available anymore.
running A query is still running.
overflow Too many queries or query results are queued.

Changelog

The module was introduced with Version 8.5.

Retrieved from "http://docs.basex.org/index.php?title=Job_Module&oldid=12829"