Difference between revisions of "Job Module"

From BaseX Documentation
Jump to navigation Jump to search
Line 121: Line 121:
 
|-
 
|-
 
| '''Errors'''
 
| '''Errors'''
|{{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/>
+
|{{Error|running|#Errors}} the job is still running.<br/>{{Error|unknown|#Errors}} the supplied id is unknown: The id is unknown, or the result has already been retrieved.<br/>
 
|-
 
|-
 
| '''Examples'''
 
| '''Examples'''

Revision as of 14:09, 30 June 2016

This XQuery Module provides functions for organizing running commands and queries (…more 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.

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() returns the same job id as jobs:current if no other job is running.
  • jobs:list()[. != jobs:current()] ! jobs:stop(.) stops and invalidates all asynchronous queries and results except for the current one.

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
  • jobs:list-details() returns information on the currently running job and possibly others:
<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:
  • true indicates that the job has either finished, or that the id is unknown.
  • false indicates that the job id is still queued or currently running.

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:
  • 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. CACHETIMEOUT can be decreased if the default setting is too restrictive.
Examples
  • jobs:schedule("1+3", map{}, map{ 'cache': true() }) returns a query id, e.g. Job-123. The result can be retrieved via a second query in the same BaseX context: jobs:result("Job-123")
  • 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: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:
  • Results can only be retrieved once. After retrieval, the cached result will be dropped.
  • If the original query has raised an error, the cached error will be raised instead.
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
  • 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:schedule('(1 to 10000000)[. = 1]')
return (
  hof:until(
    function($result) { jobs:finished($query) },
    function($curr) { 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.