Waiting for Conditions

tip

If you want to wait for something to happen outside the WfRun, like a callback or a webhook, what you want is our External Events feature.

Sometimes you want a single ThreadRun in your workflow to block until some condition is true, where that condition can be represented by variables in your WfRun.

Use-Cases

Use of this feature is advanced; and it only makes sense when you have Child ThreadRun's or Child WfRun's who can mutate the values of Variables in your parent ThreadRun while it waits for the condition to be true. Otherwise, the ThreadRun will block forever.

The three patterns for using the Wait-for-Condition feature are described below. In all three cases, a child ThreadRun or WfRun mutates the LHS variable in the condition we are waiting for.

Child Threads

Any child ThreadRun may mutate the value of variables in its parent.

Most use-cases in which you want to wait for a child ThreadRun to do something before proceeding forward in the parent can be covered by a WAIT_FOR_THREADS node. However, sometimes a parent may want to wait for some intermediate step inside the child ThreadRun to complete before proceeding. In this case, the WAIT_FOR_CONDITION provides a mechanism for the child to "wake up" the parent.

Interrupt Handler

You can use an Interrupt Handler to mutate the value of a Variable in a WfRun by posting an ExternalEvent. This is because the Interrupt Handler causes a Child ThreadRun to be run, and the child ThreadRun may mutate variables in the parent.

For example, you might have an ExternalEvent that runs every 30 seconds to report the status of some infrastructure that is being deployed. The Interrupt Handler sets the status variable. The parent ThreadRun might do something like:

wf.waitForCondition(wf.condition(status, EQUALS, "HEALTHY"));

Child Workflows

Child workflows can also mutate PUBLIC variables in their parents, just like Child ThreadRuns. You would use Child Workflows instead of Child Threads when either:

• Forces outside of the parent WfSpec need to decide when to run child WfRuns, and Interrupts are not sufficient.
• You need to run thousands of children. A single WfRun should not have more than 1,000 ThreadRuns due to serialization performance.

Implementation

To wait for a condition inside a WfSpec, you can do the following:

Java

public void wfExample(WorkflowThread wf) {
    WfRunVariable myVar = wf.addVariable("my-var", VariableType.STR);

    // register interrupt handler or spawn child thread that may mutate `my-var`.
    // Alternatively, rely on child workflows to mutate it.

    // Once `my-var` gets set to "some-value", the thread continues
    wf.waitForCondition(wf.condition(myVar, Comparator.EQUALS, "some-value"));

    // ...
}

Go

This feature is not yet supported in the Go sdk.

Python

This feature is not yet supported in the Python sdk.

C#

public void WfExample(WorkflowThread wf)
{
    WfRunVariable myVar = wf.DeclareStr("my-var");

    // register interrupt handler or spawn child thread that may mutate `my-var`.
    // Alternatively, rely on child workflows to mutate it.

    // Once `my-var` gets set to "some-value", the thread continues
    wf.WaitForCondition(wf.Condition(myVar, Comparator.Equals, "some-value"));

    // ...
}

note

In the near future, we will add the following:

• Timeouts on a WAIT_FOR_CONDITION Node with the ability to specify an EXCEPTION to throw upon timeout.
• Support for WAIT_FOR_CONDITION nodes in our Python and Go SDK's