blackbull.actor

blackbull.actor

Single-owner state through serial message handling.

Subclass Actor._handle and Message. Coordinate actors with messages, not shared mutable objects or locks. An inbox is created on first use, allowing construction before an event loop starts.

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 send; they never share mutable state.

Subclasses must override _handle.

Pass inbox_maxsize to bound the inbox (0 — the default — is unbounded, matching asyncio.Queue). A bounded inbox lets an actor apply back-pressure or, with 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.