Mailbox

casty.Mailbox

Async message queue for actor message delivery.

Wraps an asyncio.Queue with configurable capacity and overflow handling. When no capacity is set the mailbox is unbounded.

Parameters:

Name	Type	Description	Default
capacity	int | None	Maximum number of messages. None for unbounded.	None
overflow	MailboxOverflowStrategy	Policy when the mailbox is full.	drop_new

Examples:

>>> from casty import Mailbox, MailboxOverflowStrategy
>>> mb = Mailbox[str](capacity=10, overflow=MailboxOverflowStrategy.drop_new)

__init__(capacity=None, overflow=MailboxOverflowStrategy.drop_new)

put(msg)

Enqueue a message, applying the overflow strategy if full.

Parameters:

Name	Type	Description	Default
msg	M	The message to enqueue.	required

Raises:

Type	Description
QueueFull	When the overflow strategy is reject and the mailbox is at capacity.

Examples:

>>> mb = Mailbox[int](capacity=2)
>>> mb.put(1)
>>> mb.put(2)

put_async(msg) async

Enqueue a message, waiting if the mailbox is full.

Parameters:

Name	Type	Description	Default
msg	M	The message to enqueue.	required

Examples:

>>> mb = Mailbox[str](capacity=5)
>>> await mb.put_async("hi")

get() async

Dequeue the next message, waiting if the mailbox is empty.

Returns:

Type	Description
M	The next message in the queue.

Examples:

>>> mb = Mailbox[str]()
>>> mb.put("hello")
>>> msg = await mb.get()

size()

Return the number of messages currently in the mailbox.

Returns:

Type	Description
int	Current queue depth.

Examples:

>>> mb = Mailbox[int]()
>>> mb.put(42)
>>> mb.size()
1

empty()

Return whether the mailbox has no messages.

Returns:

Type	Description
bool	True if the mailbox is empty.

Examples:

>>> mb = Mailbox[int]()
>>> mb.empty()
True

casty.MailboxOverflowStrategy

Bases: Enum

Policy applied when a bounded mailbox is full.

Examples:

>>> from casty import MailboxOverflowStrategy
>>> MailboxOverflowStrategy.drop_new
<MailboxOverflowStrategy.drop_new: 1>

drop_new = auto() class-attribute instance-attribute

drop_oldest = auto() class-attribute instance-attribute

reject = auto() class-attribute instance-attribute