Skip to main content

Using Callbacks

A callback is code that the Work Queue Manager must execute after completing a work item. You can use callbacks for two reasons:

  • To perform work that is dependent on the completion of a work item

  • To signal that all queued work is completed if you choose to complete work items asynchronously

Including Callbacks for Work Items

To add a callback, you call the QueueCallback() method instead of the Queue() method when adding work items to the work queue:

method QueueCallback(work As %String, callback As %String, args... As %String) as %Status

The work and args methods are the same as for the Queue() method. However, the callback argument specifies the callback code to execute using the following syntax:

  • ##class(Classname).ClassMethod for a class method

  • $$entry^rtn for a subroutine

The class method or subroutine must accept the same arguments, in the same order, as the main work item. The master process passes the same arguments to the main work item and to the callback code.

The callback code can access the following public variables:

  • %job, which contains the job ID of the process that actually did the work

  • %status, which contains the %StatusOpens in a new tab value returned by the unit of work

  • %workqueue, which is the OREF of the work queue instance

These public variables are available within the callbacks but not within the work items.

Including Callbacks to Determine Completion

Instead of using the WaitForComplete() method to wait for all the queued work in a work queue to be completed before returning to the master process, you can poll the Work Queue Manager to determine completion as follows:

  • Use the QueueCallback() method instead of the Queue() method to add work items to the work queue as described in the previous section.

  • When the work is completed for all work items, set the public variable %exit to 1 in the callback code.

  • Use the Wait() method instead of the WaitForComplete() method:

    method Wait(qspec As %String, byRef AtEnd As %Boolean) as %Status
    

The Wait() method waits for a signal from a callback to exit back to the caller. Specifically, it waits for the callback code to set the public variable %exit equal to 1. Wait() returns AtEnd by reference. When AtEnd is 1, all the work is completed. Alternatively, if AtEnd is 0, one or more work items are not completed.

FeedbackOpens in a new tab