State Management¶
A Dory processor keeps its working data in memory, but the platform can move that processor at any time — to a new node, after a restart, or during a graceful shutdown. State management is how your in-memory data survives that move: the SDK captures it, carries it with the processor, and restores it on the other side, so the move is effectively zero-downtime.
The good news: for most processors you don't write any save/restore code. You just declare which variables matter.
Declare what to preserve¶
Mark the attributes that hold your working data with stateful(...). The SDK saves and restores them automatically across every move:
from dory import DoryApp, BaseProcessor, stateful
class MyProcessor(BaseProcessor):
counter = stateful(0) # simple value
sessions = stateful(dict) # mutable default — pass the factory, not {}
async def run(self):
async for _ in self.run_loop(interval=1):
self.counter += 1
if __name__ == "__main__":
DoryApp().run(MyProcessor)
Use a plain value for immutable defaults (stateful(0), stateful("")) and a factory for mutable ones (stateful(dict), stateful(list)) so instances don't share the same object.
Keep state JSON-serializable
Saved state is serialized, so store plain data — numbers, strings, lists, dicts. Reconstruct anything heavier (open connections, model handles) on startup rather than trying to preserve it.
The function-based API¶
If you write your processor as a function instead of a class, use state(...) the same way — these variables are saved and restored on every move too:
from dory.simple import processor, state
counter = state(0)
@processor
async def main(ctx):
async for _ in ctx.run_loop(interval=1):
counter.value += 1
Custom save / restore¶
When your state doesn't live in stateful attributes — say it's a derived cache or an external cursor — override the two hooks. get_state() returns a dict to preserve; restore_state(state) rebuilds from it on startup:
class MyProcessor(BaseProcessor):
async def startup(self):
self.cursor = 0
def get_state(self) -> dict:
return {"cursor": self.cursor}
async def restore_state(self, state: dict) -> None:
self.cursor = state.get("cursor", 0)
By default (when you don't override these) the SDK uses your stateful variables, so most processors never need to touch them.
State travels with the processor¶
When the platform moves your processor, your state goes with it. The SDK captures it from the old instance and restores it into the new one before the new instance starts handling work:
sequenceDiagram
participant Old as Processor (old instance)
participant Platform as Dory platform
participant New as Processor (new instance)
Note over Old: running, holding in-memory state
Platform->>Old: time to move
Old->>Platform: get_state() → captured state
Platform->>New: start new instance
Platform->>New: restore_state(state)
New->>New: resume from where it left off
Note over Old,New: no work lost — zero-downtime move
Where state is stored¶
By default, state is kept in a lightweight built-in store that travels with the processor. It's simple and requires no setup, and it's meant for small state — keep it modest (think kilobytes, not megabytes).
If your processor needs to preserve larger or more durable state, the platform supports other backends suited to that. The SDK API you write — stateful, get_state, restore_state — stays exactly the same regardless of which backend is in use; only platform configuration changes.
Keep state small
The default store is best for small working state — a counter, a few session keys, a cursor. If you find yourself wanting to preserve large blobs, that's usually a sign the data belongs in your own datastore, with only a pointer to it kept in processor state.
Related¶
- Core Concepts — where
statefuland the processor lifecycle are introduced. - Resilience — surviving flaky dependencies between moves.
- Configuration — platform settings, including state backend selection.