Job Module
This XQuery Module provides functions for organizing queued and running jobs (commands, queries, REST and RESTXQ request).
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.
Functions
jobs:current
Signatures | jobs:current() as xs:string
|
Summary | Returns the id of the current job. |
jobs:list
Signatures | jobs:list() as xs:string*
|
Summary | Returns the ids of all jobs that are currently queued or executed. |
Examples |
|
jobs:list-details
Signatures | jobs:list-details() as element(job)* jobs:list-details($id as xs:string) as element(job)*
|
Summary | Returns information on all jobs that are currently queued or executed. The input comprises the job id, the type (XQuery, a command, REST, RESTXQ), the time a job is already being evaluated, the state (queued, running, stopped, timeout, memory) and the user who started the job. |
Examples |
<job id="job1" type="XQuery" duration="PT0S" state="running" user="admin"> XQUERY jobs:list-details() </job> |
jobs:finished
Signatures | jobs:finished($id as xs:string) as xs:boolean
|
Summary | Indicates if the evaluation of a job with the specified $id has finished:
|
jobs:stop
Signatures | jobs:stop($id as xs:string) as empty-sequence()
|
Summary | Cancels the execution of a job with the specified $id , or drops the cached result of a query. Unknown ids are ignored. All jobs are gracefully stopped; it is up to the process to decide when it is safe to shut down.
|
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:schedule
Signatures | jobs:schedule($query as xs:string) as xs:string jobs:schedule($query as xs:string, $bindings as map(*)) as xs:string jobs:schedule($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 CACHETIMEOUT 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:
|
Errors | overflow : Too many queries or query results are queued. CACHETIMEOUT can be decreased if the default setting is too restrictive. |
Examples |
declare %rest:POST("{$query}") %rest:path('/eval') function local:schedule($query) { jobs:schedule($query) }; |
jobs:result
Signatures | jobs:result($id as xs:string) as item()*
|
Summary | Returns the cached result of a query with the specified job $id :
|
Errors | running : the job is still running.unknown : the supplied id is unknown: The id is unknown, or the result has already been retrieved. |
Examples |
declare %rest:path('/result/{$id}') function local:result($id) { jobs:result($id) };
let $query := jobs:schedule('(1 to 10000000)[. = 1]', map{}, map{ 'cache': true() }) return ( hof:until( function($f) { jobs:finished($query) }, function($f) { prof:sleep(10) }, () ), jobs:result($query) ) |
jobs:results
Signatures | jobs:results() as xs:string*
|
Summary | Returns the ids of all jobs for which results are cached. |
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.