execution_control.md

Execution Control and Flow Management in Workflow Class

Introduction to Execution Control and Flow Management

The execution lifecycle of a workflow is a crucial aspect of its behavior in Temporal. Managing the flow of a workflow involves controlling how it starts, executes, pauses, resumes, and ultimately terminates. The Workflow class in ChronoForge provides a robust framework for managing these lifecycle stages, ensuring that workflows are both reliable and responsive to external events or signals.

This section discusses how the Workflow class manages the execution control and flow of workflows, key methods like execute, and how developers can implement pausing, resuming, or terminating workflows. It also provides insights into managing long-running workflows and handling cancellations effectively.

Key Methods for Execution Control

The Workflow class provides several key methods and mechanisms for controlling the execution flow of workflows:

1. execute Method:

   • The execute method is the main entry point for defining a workflow's logic. It contains the core business logic that needs to be executed when the workflow runs.
   • Purpose: Defines the sequence of steps and operations that make up the workflow.
   • Usage: Developers override this method in their custom workflow classes to implement the desired behavior.

   import { Workflow } from 'temporal-forge';
   
   @Temporal()
   export class ExampleWorkflow extends Workflow {
     async execute(params: any): Promise<void> {
       // Main workflow logic goes here
       console.log('Workflow is executing with parameters:', params);
       
       // Example: Simple loop
       for (let i = 0; i < 5; i++) {
         console.log(`Step ${i + 1}`);
         await this.sleep(1000); // Simulate a delay
       }
     }
   }

   • Explanation:
     • The execute method is where the workflow's main operations are defined.
     • In this example, a loop is used to perform some actions with a simulated delay.

2. Pausing and Resuming Workflows:

   • Workflows can be paused and resumed based on external signals or conditions. This is particularly useful for workflows that require human intervention or are dependent on external events.

   • Pausing Workflows:

     • You can pause a workflow by using a signal handler that sets the workflow's state to "paused" and waits for a condition to be met before proceeding.

   • Resuming Workflows:

     • To resume a paused workflow, another signal handler can be defined that updates the workflow's state to "resumed" and continues execution.

   import { Workflow, Signal } from 'temporal-forge';
   
   @Temporal()
   export class PausableWorkflow extends Workflow {
     private paused: boolean = false;
   
     @Signal()
     async pause(): Promise<void> {
       this.paused = true;
       console.log('Workflow is paused.');
     }
   
     @Signal()
     async resume(): Promise<void> {
       this.paused = false;
       console.log('Workflow is resumed.');
     }
   
     async execute(params: any): Promise<void> {
       while (this.paused) {
         await this.sleep(1000); // Wait until resumed
       }
       console.log('Workflow is executing after being resumed.');
     }
   }

   • Explanation:
     • The pause and resume methods are defined using the @Signal decorator.
     • The execute method checks the paused state and waits if the workflow is paused, ensuring that the workflow can be resumed from where it left off.

3. Terminating Workflows:

   • Workflows can be terminated explicitly when certain conditions are met, or upon receiving a specific signal.
   • To terminate a workflow, you can throw an exception or use Temporal's built-in termination methods.

   import { Workflow, Signal } from 'temporal-forge';
   
   @Temporal()
   export class TerminableWorkflow extends Workflow {
   
     @Signal()
     async terminate(): Promise<void> {
       console.log('Workflow is being terminated.');
       throw new Error('Workflow terminated by signal.');
     }
   
     async execute(params: any): Promise<void> {
       // Workflow logic
     }
   }

   • Explanation:
     • The terminate method throws an error to terminate the workflow when the signal is received.

Managing Long-Running Workflows

Long-running workflows are common in Temporal applications where processes can span minutes, hours, or even days. The Workflow class provides several mechanisms to manage long-running workflows effectively:

1. Handling Workflow State and Continuation:

   • Workflows need to manage state across different execution paths to handle long-running operations. Using the StatefulWorkflow class can help manage persistent state across multiple runs and ensure the state is consistent.

2. Periodic State Checks and Updates:

   • Developers can implement periodic checks within the execute method to update the workflow state or perform maintenance tasks. This can be done using simple loops, timers, or by leveraging Temporal's ContinueAsNew feature.

   async execute(params: any): Promise<void> {
     while (true) {
       // Long-running process logic
       await this.sleep(60000); // Wait for 1 minute before the next iteration
     }
   }

3. Using ContinueAsNew for Long-Running Workflows:

   • The ContinueAsNew feature allows workflows to start a new run with a clean state after a certain number of iterations or when specific conditions are met. This helps manage memory and state size for very long-running workflows.
   • Usage Example:

   import { Workflow, Hook } from 'temporal-forge';
   
   @Temporal()
   export class ContinuableWorkflow extends Workflow {
     private iteration = 0;
   
     @Hook({ after: 'execute' })
     protected async checkForContinuation() {
       if (this.iteration >= 10000) {
         await this.continueAsNew();
       }
     }
   
     async execute(params: any): Promise<void> {
       this.iteration++;
       // Workflow execution logic
     }
   }

   • Explanation:
     • The checkForContinuation method checks if the workflow should continue as new after a certain number of iterations. This is useful for managing memory and state size in long-running workflows.

Handling Workflow Cancellations

Workflows can be canceled either by the system or manually by an operator or external system. Handling cancellations properly ensures that resources are cleaned up, and the system remains consistent.

• Graceful Cancellation:

  • Implement signal handlers that listen for cancellation signals and perform cleanup tasks before terminating the workflow.

  @Signal()
  async cancel(): Promise<void> {
    console.log('Cancelling workflow and performing cleanup...');
    // Perform any cleanup tasks
    throw new Error('Workflow cancelled by user.');
  }

• Temporal's Cancellation Scope:

  • Temporal provides a cancellation scope that can be used within workflows to handle cleanup and perform necessary rollback operations when a workflow is canceled.

Conclusion

The Workflow class in ChronoForge provides comprehensive tools for managing the execution lifecycle and flow of workflows. By leveraging key methods like execute, pause, resume, and terminate, and using features like ContinueAsNew, developers can build workflows that are responsive, resilient, and capable of handling complex, long-running processes. Effective execution control is essential for building robust workflows that perform well in dynamic, real-world environments.

For more detailed examples and best practices, refer to the Complete Usage Example section.