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=
(: unregister job :)
job:stopremove('cleanup', map { 'service': true() })
</syntaxhighlight>
=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==
{| width='100%'
|-valign="top"
| width='120' | '''Signatures'''
|{{Func|job:eval|$query as xs:anyAtomicType|xs:string}}<br />{{Func|job:eval|$query as xs:anyAtomicType, $bindings as map(*)?|xs:string}}<br />{{Func|job:eval|$query as xs:anyAtomicType, $bindings as map(*)?, $options as map(*)?|xs:string}}<br />
|-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) {
};
declare %rest:path('/stop-scheduling/{$id}') function local:stop($id) {
job:stopremove($id)
};
</syntaxhighlight>
==job:result==
{{Announce|Version 10:}} options argument added.
{| width='100%'
|-valign="top"
| width='120' | '''Signatures'''
|{{Func|job:result|$id as xs:string|item()*}}<br/>{{Func|job:result|$id as xs:string, $options as map(*)|item()*}}|-valign="top"
| '''Summary'''
|Returns the cached result of a job with the specified job {{Code|$id}}:
* If the original job has raised an error, the cached error will be raised instead.
* Results can only be retrieved once. After retrieval, the The cached result or error will be droppedafter it has been retrieved.* If the result has already not been retrieved, cached or if it has not been cacheddropped, an empty sequence is returned.The following {{Code|$options}} can be supplied:* {{Code|keep}}: Keep the cached result or error after retrieval. |-valign="top"
| '''Examples'''
|
|}
==job:stopremove== {{Announce|Updated with Version 10:}} Renamed from {{Code|jobs:stop}}.
{| width='100%'
|-valign="top"
| width='120' | '''Signatures'''
|{{Func|job:stopremove|$id as xs:string|empty-sequence()}}<br/>{{Func|job:remove|$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 jobor removes a cached result. 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"
| '''Examples'''
| * <code>job:list()[. != job:current()] ! job:stopremove(.)</code> stops and discards all jobs except for the current one.* <code>job:remove(job:current())</code> interrupts the current job.
|}
{| width='100%'
|-valign="top"
| width='120' | '''Signatures'''
|{{Func|job:wait|$id as xs:string|empty-sequence()}}
|-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'''
|{{Error|self|#Errors}} The current job is addressed.<br/>
{| width='100%'
|-valign="top"
| width='120' | '''Signatures'''
|{{Func|job:current||xs:string}}
|-valign="top"
| '''Summary'''
|Returns the id ID of the current job.
|}
{| width='100%'
|-valign="top"
| width='120' | '''Signatures'''
|{{Func|job:list||xs:string*}}
|-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.
|}
{| width='100%'
|-valign="top"
| width='120' | '''Signatures'''
|{{Func|job:list-details||element(job)*}}<br/>{{Func|job:list-details|$id as xs:string|element(job)*}}
|-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>
* <code>start</code>: next start of job (included if a job will be executed repeatedly)
* <code>time</code>: time when job was registered
|-valign="top"
| '''Examples'''
| <code>job:list-details()</code> returns information on the currently running job and possibly others:
{| width='100%'
|-valign="top"
| width='120' | '''Signatures'''
|{{Func|job:bindings|$id as xs:string|map(*)}}
|-valign="top"
| '''Summary'''
|Returns the variable bindings of an existing job with the specified {{Code|$id}}. If no variables have been bound to this job, an empty map is returned.
{| width='100%'
|-valign="top"
| width='120' | '''Signatures'''
|{{Func|job:finished|$id as xs:string|xs:boolean}}
|-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).
{| width='100%'
|-valign="top"
| width='120' | '''Signatures'''
|{{Func|job:services||element(job)*}}
|-valign="top"
| '''Summary'''
|Returns a list of all jobs that have been persistently registered as [[#Services|Services]].
|-valign="top"
| '''Errors'''
|{{Error|services|#Errors}} Registered services cannot be parsed.<br/>
! width="110"|Code
|Description
|-valign="top"
|{{Code|options}}
| The specified options are conflicting.
|-valign="top"
|{{Code|id}}
| The specified id ID is invalid or has already been assigned.|-valign="top"
|{{Code|overflow}}
| Too many queries or query results are queued.
|-valign="top"
|{{Code|range}}
| A specified time or duration is out of range.
|-valign="top"
|{{Code|running}}
| A query is still running.
|-valign="top"
|{{Code|self}}
| The current job cannot be addressed.
|-valign="top"
|{{Code|service}}
| Registered services cannot be parsed, added or removed.
;Version 10.0
* Updated: Renamed from ''Jobs Module'' to ''Job Module''. The namespace URI has been updated as well.
* Updated: {{Function||job:remove}} renamed from {{Code|jobs:stop}}.
* Updated: {{Function||job:result}}: options argument added.
* Added: {{Function||job:bindings}}
