Difference between revisions of "Job Module"
Jump to navigation
Jump to search
Line 4: | Line 4: | ||
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. | 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. | ||
+ | |||
+ | =Functions= | ||
+ | |||
+ | ==jobs:current== | ||
+ | |||
+ | {| width='100%' | ||
+ | |- | ||
+ | | width='120' | '''Signatures''' | ||
+ | |{{Func|jobs:current||xs:string}} | ||
+ | |- | ||
+ | | '''Summary''' | ||
+ | |Returns the id of the current query job. | ||
+ | |} | ||
+ | |||
+ | ==jobs:list== | ||
+ | |||
+ | {| width='100%' | ||
+ | |- | ||
+ | | width='120' | '''Signatures''' | ||
+ | |{{Func|jobs:list||xs:string*}} | ||
+ | |- | ||
+ | | '''Summary''' | ||
+ | |Returns the ids of all jobs that are either being executed asynchronously, or that are still registered because their results have been cached. | ||
+ | |- | ||
+ | | '''Examples''' | ||
+ | | | ||
+ | * <code>jobs:list()</code> returns the same job id as [[#jobs:current|jobs:current]] if no other job is running. | ||
+ | * <code>jobs:list() ! jobs:stop(.)</code> stops and invalidates all asynchronous queries and results. | ||
+ | |} | ||
+ | |||
+ | ==jobs:finished== | ||
+ | |||
+ | {| width='100%' | ||
+ | |- | ||
+ | | width='120' | '''Signatures''' | ||
+ | |{{Func|jobs:finished|$id as xs:string|xs:boolean}} | ||
+ | |- | ||
+ | | '''Summary''' | ||
+ | |Indicates if the evaluation of a job with the specified query {{Code|$id}} has finished. If <code>true</code> is returned, the job has either finished, or the query id is unknown. | ||
+ | |} | ||
+ | |||
+ | ==jobs:stop== | ||
+ | |||
+ | {| width='100%' | ||
+ | |- | ||
+ | | width='120' | '''Signatures''' | ||
+ | |{{Func|jobs:stop|$id as xs:string|empty-sequence()}} | ||
+ | |- | ||
+ | | '''Summary''' | ||
+ | |Cancels the execution of a job with the specified {{Code|$id}}, or drops the cached result of a query. Unknown query ids are ignored. | ||
+ | |} | ||
=Asynchronous Execution= | =Asynchronous Execution= | ||
Line 70: | Line 121: | ||
) | ) | ||
</pre> | </pre> | ||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
|} | |} | ||
Revision as of 00:50, 27 June 2016
This XQuery Module provides functions for organizing running commands and queries (…more to come).
Contents
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 query job. |
jobs:list
Signatures | jobs:list() as xs:string*
|
Summary | Returns the ids of all jobs that are either being executed asynchronously, or that are still registered because their results have been cached. |
Examples |
|
jobs:finished
Signatures | jobs:finished($id as xs:string) as xs:boolean
|
Summary | Indicates if the evaluation of a job with the specified query $id has finished. If true is returned, the job has either finished, or the query id is unknown.
|
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 query ids are ignored.
|
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:
|
Errors | overflow : Too many queries or query results are queued. To fix this, the query results should be retrieved. |
Examples |
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 :
|
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 |
declare %rest:path('/result/{$id}') function local:result($id) { jobs:result($id) };
let $query := jobs:eval('(1 to 10000000)[. = 1]') return ( hof:until( function($result) { jobs:finished($query) }, function($curr) { prof:sleep(10) }, () ), jobs:result($query) ) |
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.