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
BaseProcessorand implementrun(). Best when you have setup/teardown or multiple methods. - Function-based — decorate an async function with
@processorfromdory.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 --> [*]
- Startup — the SDK loads config, starts the health server, and calls your
startup()to initialize resources (load a model, open a connection). - Restore state — if a previous instance left saved state, the SDK calls
restore_state(...)before any work begins. - Ready — the SDK marks the processor ready, so its readiness check passes.
- Processing — your
run()does the work, via request handlers, a run loop, or both. - Shutdown & save — on a shutdown signal, the SDK stops accepting work, calls your
shutdown(), then captures state withget_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()—Trueonce 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:
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. ctxexposesrun_loop(...)plusctx.shutdown_requestedandctx.migration_imminent(here they are boolean properties, not method calls).- When the module runs as
__main__,@processorstarts the app for you — no explicitDoryApp().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¶
- Subscriptions & Events — how subscriptions choose, share and release processors
- State Management — how state is saved, restored, and recovered
- Resilience — circuit breakers, retries, recovery
- Observability — logs, metrics, traces
- API Reference — full signatures