API reference

This is a quick overview of the API surface you’d be interacting with most of the time. There’s also a full API reference available.

dispatch.function

Function decorator that makes any function resumable. Wrapped function has a dispatch method to invoke it.

import dispatch


@dispatch.function
def greet(name):
    print("Hello", name)


dispatch.run(lambda: greet.dispatch("Jane"))

dispatch.batch

Execute multiple functions in parallel, without waiting for their completion.

import dispatch


@dispatch.function
def greet(name):
    print("Hello", name)


@dispatch.function
def greet_everyone():
    batch = dispatch.batch()
    batch.add(greet, "Jane")
    batch.add(greet, "Mike")
    batch.add(greet, "Hopper")
    batch.dispatch()


dispatch.run(lambda: greet_everyone.dispatch())

dispatch.gather

Execute multiple functions in parallel, wait for their completion and return their results.

import dispatch


@dispatch.function
def create_greeting(name):
    return "Hello " + name


@dispatch.function
async def greet_everyone():
    names = ["Jane", "Mike", "Hopper"]

    greetings = await dispatch.gather(*[create_greeting(name) for name in names])

    for greeting in greetings:
        print(greeting)


dispatch.run(lambda: green_everyone.dispatch())

dispatch.run

Run the HTTP server for communication between your application and Dispatch. It takes an optional function argument, which is called when initializion has completed.

import dispatch


@dispatch.function
def example():
    print("I'm executed asynchronously!")


dispatch.run(lambda: example.dispatch())

dispatch.run must be used together with our CLI, which sets up the necessary configuration for dispatch.run to successfully connect to Dispatch.

dispatch run -- python app.py

Note

If your application uses FastAPI, Dispatch SDK provides a built-in integration for FastAPI that removes the need for dispatch.run.

dispatch.register_error_type

Register a handler for an exception. Handler function is expected to return a Status, which determines Dispatch behavior.

import dispatch
from dispatch import Status


class FatalException(Exception):
    pass


dispatch.register_error_type(FatalException, Status.PERMANENT_ERROR)


@dispatch.function
def example():
    raise FatalException()


dispatch.run(lambda: example.dispatch())

dispatch.register_output_type

Register a handler for resumable function’s return value upon completion. It’s useful in case function executes successfully, but you might still want to retry it later. Note that for handler to be executed, your resumable function must return a class instance.

import dispatch
from dispatch import Status


class Result:
    def __init__(self, success):
        self.success = success


def handle_result(result: Result):
    if result.success:
        return Status.OK

    return Status.TEMPORARY_ERROR


dispatch.register_output_type(Result, handle_result)


@dispatch.function
def example():
    return Result(success=False)


dispatch.run(lambda: example.dispatch())

Status

Status enum is expected to be returned from handlers registered with dispatch.register_error_type or dispatch.register_output_type. Each status instructs Dispatch whether to retry executing a resumable function or not. In addition to retries, status can impact the concurrency rate at which Dispatch executes your resumable function. For example, when status indicates an error, concurrency rate is decreased to reduce the load on your system. When status indicates success, concurrency rate is increased.

Status.OK

Retry: No.
Concurrency: Increase.

Function completed successfully.

Status.TEMPORARY_ERROR

Retry: Yes.
Concurrency: Decrease.

Function encountered a temporary error that may resolve soon.

Status.PERMANENT_ERROR

Retry: No.
Concurrency: Increase.

Function encountered a permanent error.

Status.TIMEOUT

Retry: Yes.
Concurrency: Decrease.

Function encountered a timeout.

Status.THROTTLED

Retry: Yes.
Concurrency: Decrease.

Function was throttled.

Status.UNAUTHENTICATED

Retry: No.
Concurrency: Increase.

Function attempted to perform an operation without authentication.

Status.PERMISSION_DENIED

Retry: No.
Concurrency: Increase.

Function attempted to perform an operation without permission.

Status.NOT_FOUND

Retry: No.
Concurrency: Increase.

FUnction attempted to access a non-existent resource.

Status.INVALID_ARGUMENT

Retry: No.
Concurrency: Increase.

Function was provided invalid input.

Status.INVALID_RESPONSE

Retry: No.
Concurrency: Increase.

Function encountered an unexpected response from other part of the system.

Status.DNS_ERROR

Retry: Yes.
Concurrency: Decrease.

Function encountered a DNS error.

Status.TCP_ERROR

Retry: Yes.
Concurrency: Decrease.

Function encountered a TCP error.

Status.TLS_ERROR

Retry: Yes.
Concurrency: Decrease.

Function encountered a TLS error.

Status.HTTP_ERROR

Retry: Yes.
Concurrency: Decrease.

Function encountered an HTTP error.

Status.UNSPECIFIED

Retry: No.
Concurrency: Increase.

A generic default status.