xdmp:spawn-function

xdmp:spawn-function(
   $function as function() as item()*,
   [$options as (element()|map:map)?]
) as item()*

Summary

Place the specified function value on the task queue for evaluation.

Required Privileges

http://marklogic.com/xdmp/privileges/xdmp-spawn

Usage Notes

The xdmp:spawn-function function places the specified function value in the task queue to be processed. The function will be executed when the task server has the available resources to process it. The tasks are processed in the order in which they are added to the queue.

Once xdmp:spawn-function is called, it cannot be rolled back, even if the transaction from which it is called does not complete. Therefore, use care or preferably avoid calling xdmp:spawn-function from a module that is performing an update transaction. Once a module is spawned, its evaluation is completely asynchronous of the statement in which xdmp:spawn-function was called. Consequently, if you call xdmp:spawn-function from a module that is updating a document, and if the update ends up retrying (for example, if a deadlock is detected), then the entire module is re-evaluated and the xdmp:spawn-function call is therefore called again. This will only happen in update statements, not in query statements. For details on how transactions work in MarkLogic Server, see "Understanding Transactions in MarkLogic Server" in the Application Developer's Guide.

If your function performs an update, then by default it will run in update transaction-mode, which runs as a multi-statement transaction. You must put an explicit xdmp:commit() with a transaction mode of update (otherwise it will automatically roll back). For implicit commits, specify a transaction-mode of update-auto-commit.

Example

  let $message := "Hi!"
  return
    xdmp:spawn-function(function() { xdmp:sleep(1000), xdmp:log($message) })
	
  => Puts the inline function in the task server queue.

Example

for $x in (1 to 10)
return
xdmp:spawn-function(function() {xdmp:document-insert(
  fn:concat("/doc", $x, ".xml"), <foo>{$x * 2}</foo>)}, 
<options xmlns="xdmp:eval">
  <transaction-mode>update-auto-commit</transaction-mode>
</options>)
(: 
   This example uses update-auto-commit for implicit commit.
   If you use <transaction-mode>update</transaction-mode>
   (or if you do not specify an option, and then update
   is the default) then you must put an expicit xdmp:commit() 
   in your function as it is run as a multi-statement transaction,
   and will rollback without an expliit xdmp:commit().
:)

(: spawns functions to create the specified documents on the task server :)