Bureaucrats, editor, reviewer, Administrators
13,550
edits
Changes
Jump to navigation
Jump to search
no edit summary
{{Announce|Updated with Version 10:}} Renamed from ''Jobs Module'' to ''Job Module''. The namespace URI has been updated as well.
This [[Module Library|XQuery Module]] provides functions for organizing scheduled, queued, running and cached jobs. Jobs can be commands, queries, client , or HTTP requests.
=Conventions=
=Executing Jobs=
There are cases in which a client does not, or cannot, wait until a request is fully processed. The client may be a browser, which sends an HTTP request to the server to start another time-consuming query job. The functions in this section allow you to register a new query job from a running query. Jobs can be executed immediately (i.e., as soon as the [[Transaction Management#Concurrency Control|Concurrency Control]] allows it) or scheduled for repeated execution. Each registered job gets a job idID, and the id ID can be used to retrieve a query result, stop a job, or wait for its termination.
==job:eval==
|- valign="top"
| '''Summary'''
|Schedules the evaluation of the supplied {{Code|$query}} ({{Code|xs:string}}, or of type {{Code|xs:anyURI}}, pointing to a resource), and returns a query idID. The query will be queued, and the result will optionally be cached. Queries can be updating. Variables and the context value can be declared via {{Code|$bindings}} (see {{Function|XQuery|xquery:eval}} for more details). The following {{Code|$options}} can be supplied:* {{Code|cache}}: indicates if the query result will be cached or ignored (default: <code>{{Code|false</code>}}):
** The result will be cached in main-memory until it is fetched via {{Function||job:result}}, or until {{Option|CACHETIMEOUT}} is exceeded.
** If the query raises an error, it will be cached and returned instead.
* {{Code|start}}: a dayTimeDuration, time, dateTime or integer can be specified to delay the execution of the query:
** If a dayTimeDuration is specified, the query will be queued after the specified duration has passed. Examples for of valid values are: <code>P1D</code> (1 day), <code>PT5M</code> (5 minutes), <code>PT0.1S</code> (100 ms). An error will be raised if a negative value is specified.
** If a dateTime is specified, the query will be executed at this date. Examples for valid values are: <code>2018-12-31T23:59:59</code> (New Year's Eve 2018, close to midnight). An error will be raised if the specified time lies in the past.
** If a time is specified, the query will be executed at this time of the day. Examples for of valid times are: <code>02:00:00</code> (2am local time), <code>12:00:00Z</code> (noon, UTC). If the time lies in the past, the query will be executed the next day.
** An integer will be interpreted as minutes. If the specified number is greater than the elapsed minutes of the current hour, the query will be executed one hour later.
* {{Code|interval}}: a dayTimeDuration string can be specified to execute the query periodically. An error is raised if the specified interval is less than one second (<code>PT1S</code>). If the next scheduled call is due, and if a query with the same id ID is still running, it will be skipped.
* {{Code|end}}: scheduling can be stopped after a given time or duration. The string format is the same as for {{Code|start}}. An error is raised if the resulting end time is smaller than the start time.
* {{Code|base-uri}}: sets the [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, such as with {{Code|fn:doc}}.
* {{Code|id}}: sets a custom job idID. The id ID must not start with the standard <code>job</code> prefix, and it can only be assigned if no job with the same name exists.
* {{Code|service}}: additionally registers the job as [[#Services|service]]. Registered services must have no variable bindings.
* {{Code|log}}: writes the specified string to the [[Logging|database logs]]. Two log entries are stored, one at the beginning and another one after the execution of the job.
|- valign="top"
| '''Errors'''
|{{Error|overflow|#Errors}} Query execution is rejected, because too many jobs are queued or being executed. {{Option|CACHETIMEOUT}} can be decreased if the default setting is too restrictive.<br/>{{Error|range|#Errors}} A specified time or duration is out of range.<br/>{{Error|id|#Errors}} The specified id ID is invalid or has already been assigned.<br/>{{Error|options|#Errors}} The specified options are conflicting.
|- valign="top"
| '''Examples'''
|
* Cache query result. The returned id ID can be used to pick up the result with {{Function||job:result}}:
<syntaxhighlight lang="xquery">
job:eval("1+3", (), map { 'cache': true() })
(), map { 'start': '2018-09-01T06:00:00' })}}
</syntaxhighlight>
* The following [[RESTXQ]] functions can be called to execute a query at 2 am every day. An id ID will be returned by the first function, which can be used to stop the scheduler via the second function:
<syntaxhighlight lang="xquery">
declare %rest:POST("{$query}") %rest:path('/start-scheduling') function local:start($query) {
|- valign="top"
| width='120' | '''Signatures'''
|{{Func|job:stop|$id as xs:string|empty-sequence()}}<br/>{{Func|job:stop|$id as xs:string, $options as map(*)?|empty-sequence()}}
|- valign="top"
| '''Summary'''
|Triggers the cancelation of a job with the specified {{Code|$id}}, drops the cached result of a query, or cancels a scheduled job. Unknown ids 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 {{Code|$options}} can be supplied:
* {{Code|service}}: additionally removes the job from the [[#Services|job services]] list.
|- valign="top"
| '''Summary'''
|Waits for the completion of a job with the specified {{Code|$id}}:
* The function will terminate immediately if the job id ID is unknown. This is the case if a future job has not been queued yet, or if the id ID has already been discarded after job evaluation.* If the function is called with the id ID of a queued job, or repeatedly executed job, it may stall and never terminate.
|- valign="top"
| '''Errors'''
|- valign="top"
| '''Summary'''
|Returns the id ID of the current job.
|}
|- valign="top"
| '''Summary'''
|Returns the ids IDs of all jobs that are currently registered. The list includes scheduled, queued, running, stopped, and finished jobs with cached results.
|- valign="top"
| '''Examples'''
| <code>job:list()</code> returns the same job id ID as {{Function||job:current}} if no other job is registered.
|}
|- valign="top"
| '''Summary'''
|Returns information on all jobs that are currently registered, or on a job with the specified {{Code|$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 a value. The returned elements have additional attributes:* <code>id</code>: job idID
* <code>type</code>: type of the job (command, query, REST, RESTXQ, etc.)
* <code>state</code>: current state of the job: <code>scheduled</code>, <code>queued</code>, <code>running</code>, <code>cached</code>
|- valign="top"
| '''Summary'''
|Indicates if the evaluation of an already running job with the specified {{Code|$id}} has finished. As the ids IDs of finished jobs will usually be discarded, unless caching is enabled, the function will also return <code>true</code> for unknown jobs.
* <code>false</code> indicates that the job ID is scheduled, queued, or currently running.
* <code>true</code> will be returned if the job has either finished, or if the ID is unknown (because the IDs of all finished jobs will not be cached).
|- valign="top"
|{{Code|id}}
| The specified id ID is invalid or has already been assigned.
|- valign="top"
|{{Code|overflow}}
