Changes

This [[Module Library|XQuery Module]] provides functions for organizing scheduled, queued, running and cached jobs. Jobs can be commands and , queries (…more to come), client or HTTP requests.

|Returns the ids of all jobs that are currently registered. The list includes scheduled, queued or executed, running jobs, and cached jobs.

* <code>jobs:list()</code> returns the same job id as [[#jobs:current|jobs:current]] if no other job is runningregistered.

|Returns information on all jobs that are currently registered. The list includes scheduled, queued, running jobs, and cached jobs. A string representation of the job will be returned in the text node. The returned elements have additional attributes:* <code>id</code>: job id* <code>type</code>: type of the job (command, query, REST, RESTXQ, etc.)* <code>state</code>: current state of the job (scheduled, queued , running, or cached)* <code>user</code>: the user who started the job* <code>duration</code>: evaluation time (for running and cached jobs)* <code>start</code>: dateTime string with next start (for jobs that will be executed.repeatedly)

<job id="job76job1" durationtype="XQuery" state="running" user="PT0Sadmin" typeduration="XQueryPT0.001S"> XQUERY jobs:list-details()</job>

|Indicates if the evaluation of a an already running job with the specified {{Code|$id}} has finished:* . As the ids of finished jobs will usually be discarded, unless caching is enabled, the function will also return <code>true</code> indicates that the job has either finished, or that the id is for unknownjobs.* <code>false</code> indicates that the job id is still 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).

|Cancels Triggeres the execution cancelation of a job with the specified {{Code|$id}}, or 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.|} ==jobs:wait== {| width='100%'|-| width='120' | '''Signatures'''|{{Func|jobs:wait|$id as xs:string|empty-sequence()}}|-| '''Summary'''|Waits for the completion of a job with the specified {{Code|$id}}. If the function is called with the id of a queued job, or repeatedly executed job, it may stall and never terminate.|-| '''Errors'''|{{Error|self|#Errors}} if the current job is addressed.<br/>

|{{Func|jobs:eval|$query as xs:string|xs:string}}<br />{{Func|jobs:eval|$query as xs:string, $bindings as map(*)?|xs:string}}<br />{{Func|jobs:eval|$query as xs:string, $bindings as map(*)?, $options as map(xs:string, xs:string)|xs:string}}<br />

|Prepares Schedules the evaluation of the supplied {{Code|$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 optionally be cached in main-memory until it is fetched via [[#jobs:result|jobs:result]], or until {{Option|CACHETIMEOUT}} is exceeded. Queries may can be updating.<br/>Variables and context items can be declared via {{Code|$bindings}} (see [[XQuery Module#xquery:eval|xquery:eval]] for more details). The {{Code|$options}} parameter contains evaluation scheduling options:* {{Code|cache}}: indicates if the query result will be cached or ignored (default: <code>truefalse</code>):** The result will be cached in main-memory until it is fetched via [[#jobs:result|jobs:result]], or until {{Option|CACHETIMEOUT}} is exceeded. ** If the query result raises an error, it will not be cachedand returned instead.* {{Code|start}}: a dayTimeDuration, time or dateTime can be specified to delay the execution of the query:** If a dayTimeDuration is specified, the query id will immediately be discarded queued after the specified duration has passed. Examples for 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 time is specified, the query will be executed at this time of the day. Examples for valid times are: <code>02:00:00</code> (2am), <code>12:00:00</code> (noon). If the time lies in the past, the query will be executed next day.** 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.* {{Code|interval}}: a dayTimeDuration string can be specified to execute the query executionperiodically. 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 is still running, tooit 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}}: set 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 by functions , such as with {{Code|fn:doc}} (default.* {{Code|id}}: ''empty string'')sets a custom job id. The 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.

|{{Error|overflow|#Errors}} Too Query execution is rejected, because too many queries or query results jobs are queuedor 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 is invalid or has already been assigned.

* {{Code|jobs:eval("1+3", map{}, map{ 'cache': true() })}} returns a Cache query id, e.g. {{Code|Job-123}}result. The result returned id can be retrieved via a second query in used to pick up the same BaseX contextresult with [[#jobs: {{Coderesult|jobs:result("Job-123")}}<br />* 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:

jobs:eval("1+3", (), map { 'cache': true() })</pre>* A happy birthday mail will be sent at the given date:<pre class="brush:xquery">jobs:eval("import module namespace mail='mail'; mail:send('Happy birthday!')", (), map { 'start': '2018-09-01T06:00:00' })}}</pre>* The following [[RESTXQ]] functions can be called to execute a query at 2 am every day. An id will be returned by the first function, which can be used to stop the scheduler via the second function:<pre class='brush:xquery'>declare %rest:POST("{$query}") %rest:path('/evalstart-scheduling') function local:evalstart($query) { jobs:eval($query, (), map { 'start': '02:00:00', 'interval': 'P1D' })};declare %rest:path('/stop-scheduling/{$id}') function local:stop($id) { jobs:stop($id)

|Returns the cached result of a query job with the specified job {{Code|$id}}:

* If the query original job has raised an error, the cached error will be raised instead.

|{{Error|running|#Errors}} the query job is still running.<br/>{{Error|unknown|#Errors}} the supplied query id is unknown: The query id is unknown, or the result may has already have been retrieved, or query execution may have been stopped.<br/>

* The following [[RESTXQ]] function will either return the result of a previously started query job or raise an error:

* The following query demonstrates how the results of an asynchronously executed query can be returned in a single within the same query. Please remember that this is not the common way how these functions are used in practice:

let $query := jobs:eval('(1 to 10000000)[. = 1]', map{}, map{ 'cache': true() })

hof:until( function($result) { jobs:finishedwait($query) }, function($curr) { prof:sleep(10) }, () ),

|} ==jobsPlease note that this query can easily cause a deadlock if the asynchronously executed query will be queued. In practice. In practice, you should avoid this pattern and resort to [[XQuery Module#xquery:results== {| width='100%'|fork-| width='120' | '''Signatures'''|{{Func|jobs:results|join|xsxquery:string*}}|fork-| '''Summary'''|Returns the ids of all jobs for which results are cachedjoin]] if you want to do things in parallel.