Skip to content

Core Concepts

This page is the mental model for building with the Dory Processor SDK: what a processor is, when the platform starts and stops it, the lifecycle it goes through, and the line between what the SDK does for you and what you write.

What a processor is

A processor is a long-running Python program that does some unit of work — reading a sensor, running inference on its stream, maintaining a rolling aggregate — and publishes events. You write the work; the SDK wraps it so the platform can run it as a managed, stateful, relocatable workload.

The key idea is state survives movement. The platform may move your processor to a different node at any time (scaling, spot reclaim, node drain). When it does, the SDK saves your in-memory state on the way out and restores it on the way in, so the new instance picks up where the old one left off.

You build a processor in one of two equivalent styles:

  • Class-based — subclass BaseProcessor and implement run(). Best when you have setup/teardown or multiple methods.
  • Function-based — decorate an async function with @processor from dory.simple. Best for short, simple processors.

Both run through the same engine (DoryApp) and behave identically.

When the platform starts and stops your processor

You never start a processor yourself. Each processor runs one template against one sensor, and the platform starts one the first time a subscription needs that sensor and template together — when the subscription is set up, or when the hourly re-check finds a new match. The platform records that the processor is needed, and the orchestrator starts your container on its next check, with the sensor it should read in its environment (see What your container receives).

A processor is shared. A later subscription that needs the same sensor and template, from any organization, reuses the existing processor instead of starting another. Your code never sees subscriptions: it publishes events, and the platform decides which subscriptions receive them (see Output & Events).

The platform stops a processor for one of two reasons:

  • No subscription needs it any more. The last subscription using it was deleted, or the hourly re-check dropped that sensor and template from every subscription that had them — for example, the sensor was decommissioned or unpublished, or the template was detached from the lens. The processor is released, and the orchestrator stops its container on its next check. A processor that another subscription still uses keeps running.
  • The approval of its template version is revoked. No new processor starts from a revoked version. If the revoked version was the live one, the orchestrator stops the processors running your template on its next check, without waiting for the re-check.

Either way the container is stopped gracefully, through the shutdown step of the lifecycle below: your shutdown() runs and state is saved.

Saved state belongs to one processor

If a subscription later needs the same sensor and template again, the platform starts a new processor. It begins without the state of the one that was stopped.

The lifecycle

DoryApp().run(YourProcessor) is the entry point. It takes your processor class, builds the runtime, and drives a fixed lifecycle:

stateDiagram-v2
    [*] --> Startup
    Startup --> RestoreState: saved state exists
    Startup --> Ready: fresh start
    RestoreState --> Ready
    Ready --> Processing
    Processing --> Processing: run loop / handlers
    Processing --> Shutdown: SIGTERM / shutdown signal
    Shutdown --> SaveState
    SaveState --> [*]
  1. Startup — the SDK loads config, starts the health server, and calls your startup() to initialize resources (load a model, open a connection).
  2. Restore state — if a previous instance left saved state, the SDK calls restore_state(...) before any work begins.
  3. Ready — the SDK marks the processor ready, so its readiness check passes.
  4. Processing — your run() does the work, via request handlers, a run loop, or both.
  5. Shutdown & save — on a shutdown signal, the SDK stops accepting work, calls your shutdown(), then captures state with get_state() and saves it for the next instance.

What's automatic vs. what you write

You write The SDK handles
run() — your main work Health/readiness endpoints and probes
startup() / shutdown() (optional) Restart detection and recovery decisions
stateful attributes or get_state/restore_state Saving state on shutdown, restoring it on startup
Your own log/metric/trace calls Standard logs, metrics, and traces (see Observability)
Graceful shutdown sequencing on SIGTERM

You focus on the work and the state. Everything operational comes for free.

The class-based contract

Subclass BaseProcessor and implement the one required method, run(). The rest are optional hooks with sensible defaults:

Method When it runs Default
run(self) the main processing loop required
startup(self) once, before work begins no-op
shutdown(self) on graceful shutdown no-op
get_state(self) when state is captured returns your stateful attributes
restore_state(self, state) when state is restored restores your stateful attributes
from dory import BaseProcessor, stateful

class MyProcessor(BaseProcessor):
    processed = stateful(0)

    async def startup(self) -> None:
        self.model = load_model()          # set up resources

    async def run(self) -> None:
        async for _ in self.run_loop(interval=1.0):
            self.processed += 1            # your work

    async def shutdown(self) -> None:
        self.model.close()                 # clean up

Inside any method you have self.context, the execution context — your processor's view of where it is running and whether it should keep going. Useful calls (all are methods, so include ()):

  • self.context.logger() — a logger whose output the platform collects.
  • self.context.config() — your application's configuration values.
  • self.context.is_shutdown_requested() — True once shutdown has begun.

Context accessors are methods

config(), logger(), and is_shutdown_requested() are methods — call them with (), not as bare attributes.

State: stateful

Declare persistent state as class attributes with stateful(...). Each one is automatically included when state is saved and put back when it is restored — no get_state/restore_state needed:

class P(BaseProcessor):
    counter = stateful(0)
    sessions = stateful(dict)      # use a factory for mutable defaults

Use a factory for mutable defaults

Pass the callable dict or list — not a literal {} or [] — so each instance gets its own object.

If your state needs custom shaping (computed fields, external lookups), override get_state() and restore_state() instead. See State Management.

Two ways to do work

The run loop

For polling or streaming work, use run_loop(...) — a shutdown-aware async iterator. It runs your body once per interval and stops cleanly when shutdown is requested, so you never hand-write the exit check:

async def run(self) -> None:
    async for i in self.run_loop(interval=1.0):
        await self.process_one()     # runs once per second until shutdown

The first iteration runs immediately, then it sleeps interval seconds between iterations.

Request handlers

Name your async handler methods handle_* and the SDK instruments each call (tracing, request tracking) automatically. The platform does not send requests to your container; your own code calls these methods:

async def handle_frame(self, frame):
    return await self.detect(frame)

A processor can use either pattern, or both.

The function-based style

For simple processors, skip the class entirely. Declare module-level state(...) variables and decorate an async function with @processor:

from dory.simple import processor, state

counter = state(0)

@processor
async def main(ctx):
    async for i in ctx.run_loop(interval=1.0):
        counter.value += 1
  • Access state through .value.
  • ctx exposes run_loop(...) plus ctx.shutdown_requested and ctx.migration_imminent (here they are boolean properties, not method calls).
  • When the module runs as __main__, @processor starts the app for you — no explicit DoryApp().run(...) needed.

Import dory.simple directly

from dory.simple import processor, state — these are not re-exported at the top level, and @processor must be at module top level.

Where to go next