Difference between revisions of "Job Module"
Jump to navigation
Jump to search
Andy Bunce (talk | contribs) m (contents entry for job:services) |
|||
| Line 56: | Line 56: | ||
==jobs:list-details== | ==jobs:list-details== | ||
| + | |||
| + | {{Mark|Updated with Version 9.1:}} registration time added | ||
{| width='100%' | {| width='100%' | ||
| Line 66: | Line 68: | ||
* <code>id</code>: job id | * <code>id</code>: job id | ||
* <code>type</code>: type of the job (command, query, REST, RESTXQ, etc.) | * <code>type</code>: type of the job (command, query, REST, RESTXQ, etc.) | ||
| − | * <code>state</code>: current state of the job | + | * <code>state</code>: current state of the job: <code>scheduled</code>, <code>queued</code>, <code>running</code>, <code>cached</code> |
| − | * <code>user</code>: | + | * <code>user</code>: user who started the job |
| − | * <code>duration</code>: evaluation time ( | + | * <code>duration</code>: evaluation time (included if a job is running or if the result was cached) |
| − | * <code>start</code>: | + | * <code>start</code>: next start of job (included if a job will be executed repeatedly) |
| + | * <code>time</code>: time when job was registered | ||
|- | |- | ||
| '''Examples''' | | '''Examples''' | ||
| Line 288: | Line 291: | ||
=Changelog= | =Changelog= | ||
| + | |||
| + | ;Version 9.1 | ||
| + | |||
| + | * Updated: {{Function|Jobs|jobs:list-details}}: registration time added. | ||
;Version 9.0 | ;Version 9.0 | ||
Revision as of 15:56, 31 October 2018
This XQuery Module provides functions for organizing scheduled, queued, running and cached jobs. Jobs can be commands, queries, client or HTTP requests.
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.
Services
Jobs can additionally be registered as persistent services. An additional service option has been added to the options list of jobs:eval and jobs:invoke:
(: register job, which will be run every day at 1 am :)
jobs:eval('db:drop("tmp")', (), map { 'id':'cleanup', 'start':'01:00:00', 'interval':'P1D', 'service': true() }),
(: list registered services :)
jobs:services(),
(: result: <job base-uri="..." id="cleanup" interval="P1D" start="01:00:00">db:drop("tmp")</job> :)
(: unregister job :)
jobs:stop('cleanup', map { 'service': true() })
Some more notes:
- All registered jobs will be scheduled for evaluation when the BaseX server or BaseX HTTP server is started.
- If a job service is outdated (e.g. because a supplied end time has been exceeded), it will be removed from the jobs file at startup time.
- Job services can be updated: If a new job is registered, and if there is already a job with the same id, the old entry will be replaced.
- The job definitions are stored in a
jobs.xmlfile in the database directory. It can also be edited manually.
Basic 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 registered. The list includes scheduled, queued, running, stopped, and finished jobs with cached results. |
| Examples | jobs:list() returns the same job id as jobs:current if no other job is registered.
|
jobs:list-details
Template:Mark registration time added
| 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 registered, or on a job with the specified $id (or an empty sequence if this job is not found). The list includes scheduled, queued, running jobs, and cached jobs. A string representation of the job, or its URI, will be returned as value. The returned elements have additional attributes:
|
| Examples | jobs:list-details() returns information on the currently running job and possibly others:
<job id="job1" type="XQuery" state="running" user="admin" duration="PT0.001S"> XQUERY jobs:list-details() </job> |
jobs:finished
| Signatures | jobs:finished($id as xs:string) as xs:boolean
|
| Summary | Indicates if the evaluation of an already running job with the specified $id has finished. As the ids of finished jobs will usually be discarded, unless caching is enabled, the function will also return true for unknown jobs.
|
jobs:services
| Signatures | jobs:services() as element(job)*
|
| Summary | Returns a list of all jobs that have been persistently registered as Services. |
| Errors | services: Registered services cannot be parsed. |
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:stringjobs:eval($query as xs:string, $bindings as map(*)?) as xs:stringjobs:eval($query as xs:string, $bindings as map(*)?, $options as map(*)?) as xs:string |
| Summary | Schedules the evaluation of the supplied $query and returns a query id. The query will be queued, and the result will optionally be cached. Queries can be updating. Variables and context items can be declared via $bindings (see xquery:eval for more details). The following $options can be supplied:
|
| Errors | overflow: Query execution is rejected, because too many jobs are queued or being executed. CACHETIMEOUT can be decreased if the default setting is too restrictive.range: A specified time or duration is out of range.id: The specified id is invalid or has already been assigned.options: The specified options are conflicting.
|
| Examples |
jobs:eval("1+3", (), map { 'cache': true() })
jobs:eval("import module namespace mail='mail'; mail:send('Happy birthday!')",
(), map { 'start': '2018-09-01T06:00:00' })}}
declare %rest:POST("{$query}") %rest:path('/start-scheduling') function local:start($query) {
jobs:eval($query, (), map { 'start': '02:00:00', 'interval': 'P1D' })
};
declare %rest:path('/stop-scheduling/{$id}') function local:stop($id) {
jobs:stop($id)
};
jobs:eval("prof:sleep(1500)", (), map { 'interval': 'PT1S', 'end': 'PT10S' })
jobs:eval(
file:read-text(static-base-uri()),
map { },
map { 'start': 'PT5S' }
)
|
jobs:invoke
| Signatures | jobs:invoke($uri as xs:string) as xs:stringjobs:invoke($uri as xs:string, $bindings as map(*)?) as xs:stringjobs:invoke($uri as xs:string, $bindings as map(*)?, $options as map(*)?) as xs:string |
| Summary | Schedules the evaluation of the XQuery expression located at $uri and returns a query id. For further details, see jobs:eval.
|
| Errors | overflow: Query execution is rejected, because too many jobs are queued or being executed. CACHETIMEOUT can be decreased if the default setting is too restrictive.range: A specified time or duration is out of range.id: The specified id is invalid or has already been assigned.options: The specified options are conflicting.
|
| Examples | Run XQuery expression that may perform some cleanups:
jobs:invoke("cleanup.xq", (), ())
|
jobs:result
| Signatures | jobs:result($id as xs:string) as item()*
|
| Summary | Returns the cached result of a job 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:eval('(1 to 10000000)[. = 1]', map{}, map{ 'cache': true() })
return (
jobs:wait($query),
jobs:result($query)
)
Please note that queries of this kind can cause deadlocks. For example, if both the original query and the query to be executed asynchronously perform updates on the same database, the second query would only be run after the first one has been executed, and the first query will wait forever. This is why you should avoid this pattern in practice and resort to xquery:fork-join if you want to do things in parallel. |
jobs:stop
| Signatures | jobs:stop($id as xs:string) as empty-sequence()
|
| Summary | Triggers the cancelation of a job with the specified $id, drops the cached result of a query, or cancels a scheduled job. Unknown ids are ignored. All jobs are gracefully stopped; it is up to the process to decide when it is safe to shut down. The following $options can be supplied:
|
| Examples | jobs:list()[. != jobs:current()] ! jobs:stop(.) stops and discards all jobs except for the current one.
|
jobs:wait
| Signatures | jobs:wait($id as xs:string) as empty-sequence()
|
| Summary | Waits for the completion of a job with the specified $id:
|
| Errors | self: The current job is addressed. |
Errors
| Code | Description |
|---|---|
options
|
The specified options are conflicting. |
id
|
The specified id is invalid or has already been assigned. |
overflow
|
Too many queries or query results are queued. |
range
|
A specified time or duration is out of range. |
running
|
A query is still running. |
self
|
The current job cannot be addressed. |
service
|
Registered services cannot be parsed, added or removed. |
unknown
|
The supplied query id is unknown or not available anymore. |
Changelog
- Version 9.1
- Updated:
jobs:list-details: registration time added.
- Version 9.0
- Added:
jobs:invoke, Services
- Version 8.6
- Updated: jobs:eval:
idoption added.
The module was introduced with Version 8.5.
