Deferring Work Items

A deferred work item is a unit of work that is added to a work queue in the Work Queue Manager, but is not available to be processed until it is activated. This functionality allows you to schedule work that cannot begin processing immediately, for example because required data is not yet available.

Deferring and Activating Work Items

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

method QueueDeferred(Output dtoken AS %String, work As %String, args... As %String) as %Status

The work and args methods are the same as for the Queue() method. However, the unit of work is not available for processing until the ActivateDeferred() method is called using the dtoken output variable.

To activate a deferred unit of work, you call the ActivateDeferred() method:

method ActivateDeferred(dtoken As %String) as %Status

When this method is called, the corresponding unit of work moves out of its deferred state and is made available for processing.

Usage Notes for Deferred Work Items

Keep the following notes in mind when using deferred work items:

The deferred work item can be activated later within the same process or you can pass the corresponding dtoken to another process and activate the work item from that process.
A work queue can include both active work items (those queued by the Queue() or QueueCallback() methods) and deferred work items.
If you use the QueueDeferred() method to defer work, then you must ensure that you have called ActivateDeferred() on all of the dtokens before calling Sync(). Otherwise, Sync() will hang waiting for all of the deferred items to be activated and finished processing.

Example

The following shows a simple example of using deferred work items:

 Set queue=##class(%SYSTEM.WorkMgr).%New()
 For i=1:1:filelist.Count() {
    Set filename=filelist.GetAt(i)
    Set sc=queue.QueueDeferred(.dtoken,"..Load",filename)
    If $$$ISERR(sc) {
       Return sc
    }
    Set dtokens($i(dtokens))=dtoken
 }
 
 Set waited=0
 While '$Get(^MyApp.BatchReady(batchId)) {
    Hang 5
    Set waited=waited+5
    If waited'<180 {
       Return $$$ERROR($$$GeneralError,"Timed out waiting for data to be ready")
    }
 }
 
 For i = 1:1:dtokens {
    Set sc=queue.ActivateDeferred(dtokens(i))
    If $$$ISERR(sc) {
       Return sc
    }
 }
 
 Set sc=queue.Sync()
 If $$$ISERR(sc) {
    Return sc
 }
 Return sc

The example initializes the Work Queue Manager, creates a queue, then iterates through a list of files. For each file, the code adds a deferred work item that will load the file. The code then checks a global node every five seconds for a flag indicating that the files are ready to be loaded. Once this flag is true, it iterates through each dtoken and activates the corresponding work item using the ActivateDeferred() method. This makes the deferred work items available for processing. Once each work item is activated, the Sync() method is called which will return status information once each work item is finished processing.