blackbull.actor

blackbull.actor

Actor

Base class for all BlackBull Actors.

Each Actor owns an asyncio.Queue inbox and is expected to run as an asyncio.Task started by its Supervisor. Actors communicate exclusively via :meth:send; they never share mutable state.

Subclasses must override :meth:_handle.

Pass inbox_maxsize to bound the inbox (0 — the default — is unbounded, matching :class:asyncio.Queue). A bounded inbox lets an actor apply back-pressure or, with :meth:asyncio.Queue.put_nowait, an explicit overflow policy.

run() async

Consume the inbox until the task is cancelled.

send(msg) async

Enqueue msg to this Actor's inbox.

Returns immediately for an unbounded inbox (the default). When the Actor was constructed with inbox_maxsize > 0 and the inbox is full, this awaits until a slot frees up — backpressure on the producer, per the bounded-inbox overflow policy.

Message dataclass

Base class for all Level A Actor messages.

Subclasses are plain dataclasses — add fields with standard dataclass syntax. The sender field is excluded from equality comparison so that message identity is determined by payload, not by which Actor sent it.