Job Module - Revision history

CG: Text replacement - "syntaxhighlight" to "pre"

2023-12-01T16:39:27Z

Text replacement - "syntaxhighlight" to "pre"

CG: Text replacement - "" to ""

2023-12-01T16:37:14Z

Text replacement - "</syntaxhighlight>" to "</pre>"

CG: Text replacement - "" to "

2023-12-01T16:29:45Z

Text replacement - "<syntaxhighlight lang="xquery">" to "<pre lang='xquery'>"

CG at 10:18, 26 October 2023

2023-10-26T10:18:20Z

CG at 14:54, 9 March 2023

2023-03-09T14:54:47Z

CG at 13:58, 9 March 2023

2023-03-09T13:58:00Z

CG: Text replacement - "'''Signatures'''" to "'''Signature'''"

2023-03-09T13:05:04Z

Text replacement - "'''Signatures'''" to "'''Signature'''"

CG at 11:06, 9 March 2023

2023-03-09T11:06:32Z

CG: Text replacement - "
" to "
"

2023-03-09T08:16:19Z

Text replacement - "<br />" to "<br/>"

CG: /* Executing Jobs */

2023-02-15T11:06:41Z

Executing Jobs

@@ Line 224: / Line 224: @@
 | '''Examples'''
 | <code>job:list-details()</code> returns information on the currently running job and possibly others:
-<syntaxhighlight lang="xml">
+<pre lang="xml">
 <job id="job1" type="XQuery" state="running" user="admin" duration="PT0.001S">
    XQUERY job:list-details()

@@ Line 19: / Line 19: @@
 (: unregister job :)
 job:remove('cleanup', map { 'service': true() })
-</syntaxhighlight>
+</pre>
 '''Some more notes:'''
@@ Line 67: / Line 67: @@
 <pre lang='xquery'>
 job:eval("1+3", (), map { 'cache': true() })
-</syntaxhighlight>
+</pre>
 * A happy birthday mail will be sent at the given date:
 <pre lang='xquery'>
 job:eval("import module namespace mail='mail'; mail:send('Happy birthday!')",
    (), map { 'start': '2018-09-01T06:00:00' })}}
-</syntaxhighlight>
+</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 lang='xquery'>
@@ Line 81: / Line 81: @@
    job:remove($id)
 };
-</syntaxhighlight>
+</pre>
 * 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 lang='xquery'>
 job:eval("prof:sleep(1500)", (), map { 'interval': 'PT1S', 'end': 'PT10S' })
-</syntaxhighlight>
+</pre>
 * The query in the specified file will be evaluated once:
 <pre lang='xquery'>
 job:eval(xs:anyURI('cleanup.xq'))
-</syntaxhighlight>
+</pre>
 * The following expression, if stored in a file, will be evaluated every 5 seconds:
 <pre lang='xquery'>
@@ Line 97: / Line 97: @@
    map { 'start': 'PT5S' }
+)
-</syntaxhighlight>
+</pre>
 |}
@@ Line 126: / Line 126: @@
    job:result($id)
 };
-</syntaxhighlight>
+</pre>
 * The following query demonstrates how the results of an executed query can be returned within the same query (see below why you should avoid this pattern in practice):
 <pre lang='xquery'>
@@ Line 134: / Line 134: @@
    job:result($query)
+)
-</syntaxhighlight>
+</pre>
 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 only be run after the first one has been executed, and the first query will wait for the second query forever. You should resort to {{Function|XQuery|xquery:fork-join}} if you want to have full control on parallel query execution.
 |}
@@ Line 228: / Line 228: @@
    XQUERY job:list-details()
 </job>
-</syntaxhighlight>
+</pre>
 |}

@@ Line 9: / Line 9: @@
 A job can be registered as ''service'' by supplying the {{Code|service}} option to {{Function||job:eval}}:
-<syntaxhighlight lang="xquery">
+<pre lang='xquery'>
 (: register job as service; will be run every day at 1 am :)
 job:eval('db:drop("tmp")', (), map { 'id':'cleanup', 'start':'01:00:00', 'interval':'P1D', 'service': true() }),
@@ Line 65: / Line 65: @@
+|
 * Cache query result. The returned ID can be used to pick up the result with {{Function||job:result}}:
-<syntaxhighlight lang="xquery">
+<pre lang='xquery'>
 job:eval("1+3", (), map { 'cache': true() })
 </syntaxhighlight>
 * A happy birthday mail will be sent at the given date:
-<syntaxhighlight lang="xquery">
+<pre lang='xquery'>
 job:eval("import module namespace mail='mail'; mail:send('Happy birthday!')",
    (), 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 will be returned by the first function, which can be used to stop the scheduler via the second function:
-<syntaxhighlight lang="xquery">
+<pre lang='xquery'>
 declare %rest:POST("{$query}") %rest:path('/start-scheduling') function local:start($query) {
    job:eval($query, (), map { 'start': '02:00:00', 'interval': 'P1D' })
@@ Line 83: / Line 83: @@
 </syntaxhighlight>
 * 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:
-<syntaxhighlight lang="xquery">
+<pre lang='xquery'>
 job:eval("prof:sleep(1500)", (), map { 'interval': 'PT1S', 'end': 'PT10S' })
 </syntaxhighlight>
 * The query in the specified file will be evaluated once:
-<syntaxhighlight lang="xquery">
+<pre lang='xquery'>
 job:eval(xs:anyURI('cleanup.xq'))
 </syntaxhighlight>
 * The following expression, if stored in a file, will be evaluated every 5 seconds:
-<syntaxhighlight lang="xquery">
+<pre lang='xquery'>
 job:eval(
    static-base-uri(),
@@ Line 122: / Line 122: @@
+|
 * The following [[RESTXQ]] function will either return the result of a previously started job or raise an error:
-<syntaxhighlight lang="xquery">
+<pre lang='xquery'>
 declare %rest:path('/result/{$id}') function local:result($id) {
    job:result($id)
@@ Line 128: / Line 128: @@
 </syntaxhighlight>
 * The following query demonstrates how the results of an executed query can be returned within the same query (see below why you should avoid this pattern in practice):
-<syntaxhighlight lang="xquery">
+<pre lang='xquery'>
 let $query := job:eval('(1 to 10000000)[. = 1]', map { }, map { 'cache': true() })
 return (

@@ Line 1: / Line 1: @@
 This [[Module Library|XQuery Module]] provides functions for registering new query jobs and orchestrating existing jobs. Jobs can be queries, commands, operations performed by a database client, and HTTP requests.
@@ Line 103: / Line 101: @@
 ==job:result==
 {| width='100%'
@@ Line 143: / Line 139: @@
 ==job:remove==
 {| width='100%'
@@ Line 238: / Line 232: @@
 ==job:bindings==
 {| width='100%'

@@ Line 40: / Line 40: @@
 |<pre>job:eval(
    $query     as xs:anyAtomicType,
-   $bindings  as map(*)?           := (),
+   $bindings  as map(*)?           := map { },
-   $options   as map(*)?           := ()
+   $options   as map(*)?           := map { }
 ) as xs:string</pre>
 |- valign="top"
@@ Line 111: / Line 111: @@
 |<pre>job:result(
    $id       as xs:string,
-   $options  as map(*)     := ()
+   $options  as map(*)?    := map { }
 ) as item()*</pre>
 |- valign="top"
@@ Line 151: / Line 151: @@
 |<pre>job:remove(
    $id       as xs:string,
-   $options  as map(*)?    := ()
+   $options  as map(*)?    := map { }
 ) as empty-sequence()</pre>
 |- valign="top"

@@ Line 38: / Line 38: @@
 |- 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/>
+|<pre>job:eval(
 |- valign="top"
 | '''Summary'''
@@ Line 105: / Line 109: @@
 |- 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()*}}
+|<pre>job:result(
 |- valign="top"
 | '''Summary'''
@@ Line 142: / Line 149: @@
 |- valign="top"
 | width='120' | '''Signatures'''
-|{{Func|job:remove|$id as xs:string|empty-sequence()}}<br/>{{Func|job:remove|$id as xs:string, $options as map(*)?|empty-sequence()}}
+|<pre>job:remove(
 |- valign="top"
 | '''Summary'''
@@ Line 159: / Line 169: @@
 |- valign="top"
 | width='120' | '''Signatures'''
-|{{Func|job:wait|$id as xs:string|empty-sequence()}}
+|<pre>job:wait(
 |- valign="top"
 | '''Summary'''
@@ Line 177: / Line 189: @@
 |- valign="top"
 | width='120' | '''Signatures'''
-|{{Func|job:current||xs:string}}
+|<pre>job:current() as xs:string</pre>
 |- valign="top"
 | '''Summary'''
@@ Line 188: / Line 200: @@
 |- valign="top"
 | width='120' | '''Signatures'''
-|{{Func|job:list||xs:string*}}
+|<pre>job:list() as xs:string*</pre>
 |- valign="top"
 | '''Summary'''
@@ Line 202: / Line 214: @@
 |- valign="top"
 | width='120' | '''Signatures'''
-|{{Func|job:list-details||element(job)*}}<br/>{{Func|job:list-details|$id as xs:string|element(job)*}}
+|<pre>job:list-details(
 |- valign="top"
 | '''Summary'''
@@ Line 230: / Line 244: @@
 |- valign="top"
 | width='120' | '''Signatures'''
-|{{Func|job:bindings|$id as xs:string|map(*)}}
+|<pre>job:bindings(
 |- valign="top"
 | '''Summary'''
@@ Line 241: / Line 257: @@
 |- valign="top"
 | width='120' | '''Signatures'''
-|{{Func|job:finished|$id as xs:string|xs:boolean}}
+|<pre>job:finished(
 |- valign="top"
 | '''Summary'''
@@ Line 254: / Line 272: @@
 |- valign="top"
 | width='120' | '''Signatures'''
-|{{Func|job:services||element(job)*}}
+|<pre>job:services() as element(job)*</pre>
 |- valign="top"
 | '''Summary'''

@@ Line 31: / Line 31: @@
 =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 ID, and the ID can be used to retrieve a query result, stop a job, or wait for its termination.
+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 new query jobs and access existing ones. Jobs can be executed immediately (i.e., as soon as a [[Transaction Management#Concurrency Control|free slot 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.
 ==job:eval==
@@ Line 41: / Line 41: @@
 |- valign="top"
 | '''Summary'''
-|Schedules the evaluation a new query job for the supplied {{Code|$query}} (of type {{Code|xs:string}}, or of type {{Code|xs:anyURI}} if points to a resource), and returns a job ID. 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:
+|Schedules the evaluation a new query job for the supplied {{Code|$query}} (of type {{Code|xs:string}}, or of type {{Code|xs:anyURI}} if points to a resource), and returns a job ID. The job will be queued until a free slot is available, and the query result can be cached. Queries can be updating, and 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|false}}):
 ** The result will be cached in main-memory until it is fetched via {{Function||job:result}}, or until {{Option|CACHETIMEOUT}} is exceeded.