Bureaucrats, editor, reviewer, Administrators
13,550
edits
Changes
Jump to navigation
Jump to search
Asynchronous query execution is recommendable if There are cases in which a client does not, or cannot, wait until a request is fully processed. This is e. g. the case with web browsersThe client may be a browser, which will usually cancel a sends an HTTP request after a specific timeout. In such cases, you can use asynchronous execution to trigger another the server-side process, which will in order to start the another time-consuming processquery 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., and fetch the result later on as soon as the [[Transaction Management#Concurrency Control|Concurrency Control]] allows it is available) or scheduled for repeated execution. Each registered job gets a job id, and the id can be used to retrieve a query result, stop a job, or wait for its termination.
** 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.
→Services
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.
=Services= A job can be registered as ''service'' by supplying the {{Code|service}} option to {{Function|Jobs|jobs:eval}}: <syntaxhighlight lang="xquery">(: register job as service; 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() })</syntaxhighlight> '''Some more notes:''' * All job services 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.* The job definitions are stored in a {{Code|jobs.xml}} file in the database directory. It can also be edited manually. =Basic Functions=
==jobs:current==
|-
| '''Summary'''
|Returns the ids of all jobs that are currently registered. The list includes scheduled, queued, running jobs, stopped, and finished jobs with cached jobsresults.
|-
| '''Examples'''
|* <code>jobs:list()</code> returns the same job id as [[#jobs:current{{Function|Jobs|jobs:current]] }} if no other job is registered.* <code>jobs:list()[. != jobs:current()] ! jobs:stop(.)</code> stops and invalidates all asynchronous queries and results except for the current one.
|}
|-
| '''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 in the text nodeas value. 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 (: <code>scheduled</code>, <code>queued</code>, <code>running</code>, or <code>cached)</code>* <code>user</code>: the user who started the job* <code>duration</code>: evaluation time (for included if a job is running and or if the result was cached jobs)* <code>start</code>: dateTime string with next start of job (for jobs that included if a job will be executed repeatedly)* <code>time</code>: time when job was registered
|-
| '''Examples'''
|* <code>jobs:list-details()</code> returns information on the currently running job and possibly others:<pre classsyntaxhighlight lang="brush:xml">
<job id="job1" type="XQuery" state="running" user="admin" duration="PT0.001S">
XQUERY jobs:list-details()
</job>
</presyntaxhighlight>
|}
|}
==jobs:stop== {| width='100%'|-| width='120' | '''Signatures'''|{{Func|jobs:stop|$id as xs:string|empty-sequence()}}|-| '''Summary'''|Triggeres the cancelation of a job with the specified {{Code|$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.|} ==jobs:waitservices==
{| width='100%'
|-
| width='120' | '''Signatures'''
|{{Func|jobs:waitservices|$id as xs:string|empty-sequenceelement(job)*}}
|-
| '''Summary'''
|Waits for the completion Returns a list of a job with the specified {{Codeall jobs that have been persistently registered as [[#Services|$id}}. If the function is called with the id of a repeatedly executed job, it may never terminateServices]].
|-
| '''Errors'''
|{{Error|selfservices|#Errors}} if the current job is addressedRegistered services cannot be parsed.<br/>
|}
=Asynchronous Execution=
==jobs:eval==
{{Mark|Updated with Version 89.65}}: <code>id</code> option Integers addedas valid start and end times.
{| width='100%'
|-
| width='120' | '''Signatures'''
|{{Func|jobs:eval|$query as xs:stringanyAtomicItem|xs:string}}<br />{{Func|jobs:eval|$query as xs:stringanyAtomicItem, $bindings as map(*)?|xs:string}}<br />{{Func|jobs:eval|$query as xs:stringanyAtomicItem, $bindings as map(*)?, $options as map(xs:string, xs:string*)?|xs:string}}<br />
|-
| '''Summary'''
|Schedules the evaluation of the supplied {{Code|$query}} and returns a query id. The query will be queued, and the result will optionally be cached. Queries can be updating. Variables The query can be a URI or a string, and variables and context items can be declared via {{Code|$bindings}} (see [[XQuery Module#xquery:eval|xquery:eval]] for more details). The following {{Code|$options}} parameter contains scheduling optionscan be supplied:
* {{Code|cache}}: indicates if the query result will be cached or ignored (default: <code>false</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 raises an error, it will be cached and returned instead.
* {{Code|start}}: a dayTimeDuration, time , dateTime or dateTime 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 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 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 exceeds the 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 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 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.
* {{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.
|-
| '''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 is invalid or has already been assigned.<br/>{{Error|options|#Errors}} The specified options are conflicting.
|-
| '''Examples'''
|
* Cache query result. The returned id can be used to pick up the result with [[#jobs:result|jobs:result]]:
<pre classsyntaxhighlight lang='brush:"xquery'">
jobs:eval("1+3", (), map { 'cache': true() })
</presyntaxhighlight>
* A happy birthday mail will be sent at the given date:
<pre classsyntaxhighlight lang="brush:xquery">
jobs:eval("import module namespace mail='mail'; mail:send('Happy birthday!')",
(), map { 'start': '2018-09-01T06:00:00' })}}
</presyntaxhighlight>
* 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 classsyntaxhighlight lang='brush:"xquery'">
declare %rest:POST("{$query}") %rest:path('/start-scheduling') function local:start($query) {
jobs:eval($query, (), map { 'start': '02:00:00', 'interval': 'P1D' })
jobs:stop($id)
};
</presyntaxhighlight>
* Query execution is scheduled for every second, and for 10 seconds in total. As the query itself will take 1.5 seconds, it will only be executed every second time:
<pre classsyntaxhighlight lang="brush:xquery">
jobs:eval("prof:sleep(1500)", (), map { 'interval': 'PT1S', 'end': 'PT10S' })
</presyntaxhighlight>* The query in the specified file will be evaluated once:<syntaxhighlight lang="xquery">jobs:eval(xs:anyURI('cleanup.xq'))</syntaxhighlight>* The following expression, if stored in a file, will be evaluated every 5 seconds:<syntaxhighlight lang="xquery">jobs:eval( static-base-uri(), map { }, map { 'start': 'PT5S' })</syntaxhighlight>
|}
|
* The following [[RESTXQ]] function will either return the result of a previously started job or raise an error:
<pre classsyntaxhighlight lang='brush:"xquery'">
declare %rest:path('/result/{$id}') function local:result($id) {
jobs:result($id)
};
</presyntaxhighlight>* The following query demonstrates how the results of an asynchronously executed query can be returned within the same query(see below why you should avoid this pattern in practice):<pre classsyntaxhighlight lang='brush:"xquery'">let $query := jobs:eval('(1 to 10000000)[. = 1]', map{}, map{ 'cache': true() })
return (
jobs:wait($query),
jobs:result($query)
)
</presyntaxhighlight>Please remember that Queries of this kind can cause deadlocks! If the original query and the new query perform updates on the same database, the second query will cause a deadlock if only be run after the asynchronously first one has been executed , and the first query will be queuedwait for the second query forever. In practice. In practice, you You should avoid this pattern and resort to [[XQuery Module#xquery:fork-join|xquery:fork-join]] if you want to do things in have full control on parallelquery execution.|} ==jobs:stop== {| width='100%'|-| width='120' | '''Signatures'''|{{Func|jobs:stop|$id as xs:string|empty-sequence()}}|-| '''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 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.|-| '''Examples'''| <code>jobs:list()[. != jobs:current()] ! jobs:stop(.)</code> stops and discards all jobs except for the current one.|} ==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}}:* The function will terminate immediately if the job id is unknown. This is the case if a future job has not been queued yet, or if the id has already been discarded after job evaluation.* 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}} The current job is addressed.<br/>
|}
|Description
|-
|{{Code|unknownoptions}}| The supplied query id is unknown or not available anymorespecified options are conflicting.
|-
|{{Code|runningid}}| A query The specified id is still runninginvalid or has already been assigned.
|-
|{{Code|overflow}}
| A specified time or duration is out of range.
|-
|{{Code|idrunning}}| The specified A query is invalid or has already been assignedstill running.
|-
|{{Code|self}}
| The current job cannot be addressed.
|-
|{{Code|service}}
| Registered services cannot be parsed, added or removed.
|-
|{{Code|unknown}}
| The supplied query id is unknown or not available anymore.
|}
=Changelog=
;Version 9.5
* Updated: {{Function|Jobs|jobs:eval}}: integers added as valid start and end times.
;Version 9.4
* Updated: {{Function|Jobs|jobs:eval}}: option added for writing log entries.
* Updated: {{Function|Jobs|jobs:list-details}}: interval added.
;Version 9.2
* Deleted: jobs:invoke (merged with {{Function|Jobs|jobs:eval}})
;Version 9.1
* Updated: {{Function|Jobs|jobs:list-details}}: registration time added.
;Version 9.0
* Added: {{Function|Jobs|jobs:invoke}}, [[#Services|Services]]
;Version 8.6
* Updated: [[#jobs:eval{{Function|Jobs|jobs:eval]]}}: <code>id</code> option added.
The module was introduced with Version 8.5.
