Hatchet’s Python SDK provides a number of ways to handle cancellations, in addition to some important footguns to be aware of when running tasks.

For async tasks, Hatchet uses the cancel method of asyncio’s task to handle cancellation. This means that for any async work, the task will be cancelled at the next await point via a CancelledError exception.

For synchronous tasks, cancellation is more involved (and riskier) because of how Hatchet uses threads to run synchronous work without blocking the event loop. Threads cannot be cancelled the same was as async tasks can, which means that synchronous tasks, when running, cannot be cancelled easily. If you need to have tasks be cancellable, we highly recommend making them async. However, if they really need to be both synchronous and cancellable, Hatchet exposes a configuration option called enable_force_kill_sync_threads, which can be set by setting the HATCHET_CLIENT_ENABLE_FORCE_KILL_SYNC_THREADS to True, which will forcibly kill the thread the task is running on and cause it to exit immediately.

While your task is running, you can manage cancellation by:

1. Checking for cancellation using the Context.exit_flag, which indicates whether a task has been cancelled. You can check this flag at any point in your task to determine whether or not to exit. For example:

@cancellation_workflow.task()
def check_flag(input: EmptyModel, ctx: Context) -> dict[str, str]:
    for i in range(3):
        time.sleep(1)

        # Note: Checking the status of the exit flag is mostly useful for cancelling
        # sync tasks without needing to forcibly kill the thread they're running on.
        if ctx.exit_flag:
            print("Task has been cancelled")
            raise ValueError("Task has been cancelled")

    return {"error": "Task should have been cancelled"}

2. Using Context.cancel or Context.aio_cancel to cancel the task. This method will set the exit_flag to True and will notify the engine that it should cancel the task. For example:

@cancellation_workflow.task()
async def self_cancel(input: EmptyModel, ctx: Context) -> dict[str, str]:
    await asyncio.sleep(2)

    ## Cancel the task
    await ctx.aio_cancel()

    await asyncio.sleep(10)

    return {"error": "Task should have been cancelled"}

Hatchet uses the standard AbortController and AbortSignal interfaces from Node.js to handle cancellation. Each task has access to a context.controller property, which is an instance of AbortController. The AbortController provides a way to signal cancellation to the task and any asynchronous operations it may be performing.

Inside a task, you can check for cancellation by accessing the cancelled property of the Context, which is a boolean value indicating whether the task has been cancelled or not. For example:

export const cancellation = hatchet.task({
  name: 'cancellation',
  fn: async (_, { cancelled }) => {
    await sleep(10 * 1000);

    if (cancelled) {
      throw new Error('Task was cancelled');
    }

    return {
      Completed: true,
    };
  },
});

In this example, the task checks the cancelled flag and aborts.

Additionally, you can register an event listener for the 'abort' event on the signal. This listener will be called when the cancellation signal is received, allowing you to handle the cancellation asynchronously.

Aborting Network Requests

One common use case for cancellation is aborting network requests that are no longer needed. Hatchet’s cancellation mechanism integrates seamlessly with many network libraries that support the AbortSignal interface.

Here’s an example of how to pass the AbortSignal to an axios request:

export const abortSignal = hatchet.task({
  name: 'abort-signal',
  fn: async (_, { controller }) => {
    try {
      const response = await axios.get('https://api.example.com/data', {
        signal: controller.signal,
      });
      // Handle the response
    } catch (error) {
      if (axios.isCancel(error)) {
        // Request was canceled
        console.log('Request canceled');
      } else {
        // Handle other errors
      }
    }
  },
});

In this example, the signal property from the Context.controller is passed as an option to the axios.get request. If the task is canceled while the request is still pending, the request will be automatically aborted, and an error will be thrown. You can catch the error and check if it was due to cancellation using the axios.isCancel method.

Hatchet uses the standard context.WithCancel way of creating a context and passes that to a task. Each task can check for cancellation signals using the Done() method that context package provides.

Here’s an example of how to check for cancellation in a task:

// Create a task that sleeps for 10 seconds and checks if it was cancelled
cancellation := factory.NewTask(
	create.StandaloneTask{
		Name: "cancellation-task",
	}, func(ctx worker.HatchetContext, input CancellationInput) (*CancellationResult, error) {
		// Sleep for 10 seconds
		time.Sleep(10 * time.Second)

		// Check if the context was cancelled
		select {
		case <-ctx.Done():
			return nil, errors.New("Task was cancelled")
		default:
			// Continue execution
		}

		return &CancellationResult{
			Completed: true,
		}, nil
	},
	hatchet,
)