Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
52 changes: 51 additions & 1 deletion docs/reference/mailbox.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,57 @@

# Mailbox

`MailboxProcessor` provides a FIFO queue with one active receiver and multiple
producers. Create the mailbox and call `receive`, `post_and_async_reply`, and
`wait` on its owning running asyncio event loop. `post` and reply channels may
be used from other threads.

```python
import asyncio

from expression import AsyncReplyChannel, MailboxProcessor


async def main() -> None:
async def body(inbox: MailboxProcessor[AsyncReplyChannel[None]]) -> None:
channel = await inbox.receive(timeout=1.0)
channel.reply(None)

agent = MailboxProcessor.start(body)
def request(channel: AsyncReplyChannel[None]) -> AsyncReplyChannel[None]:
return channel

await agent.post_and_async_reply(request, timeout=1.0)
await agent.wait()


asyncio.run(main())
```

Timeouts are optional and measured in **seconds**, following asyncio conventions.
An expired timeout raises `TimeoutError`. Cancelling or timing out a receive
releases the reader without consuming a message. Concurrent receives raise
`RuntimeError`.

`post_and_async_reply` posts immediately. The first reply wins, including `None`;
duplicate replies and replies arriving after cancellation or timeout are ignored.
Cancelling a reply wait does not retract the request or stop its processing.
Without a timeout, a request that is never answered can wait indefinitely.

A cancellation token wakes an idle receiver and cancels a started body. An
already-cancelled token prevents the body coroutine from running, while
`CancellationToken.none()` behaves like an omitted token. `wait()` observes body
completion and propagates its exception or `asyncio.CancelledError`. Cancelling
`wait()` itself leaves the body running. A directly constructed mailbox has no
body to wait for.

Body termination does not close the queue or settle outstanding reply waits.
Use reply timeouts and observe `wait()` when coordinating shutdown. The queue is
unbounded; posting does not provide backpressure. This is a subset of F#'s
MailboxProcessor API: selective scanning and optional-result receive/reply
variants are not provided.

```{eval-rst}
.. automodule:: expression.core.mailbox
:members:
```
```
71 changes: 34 additions & 37 deletions expression/core/aiotools.py
Original file line number Diff line number Diff line change
Expand Up @@ -11,9 +11,10 @@
import asyncio
from asyncio import Future, Task
from collections.abc import Awaitable, Callable
from inspect import iscoroutine
from typing import Any, TypeVar

from expression.system import CancellationToken, OperationCanceledError
from expression.system import CancellationToken, ObjectDisposedException, OperationCanceledError


_TSource = TypeVar("_TSource")
Expand Down Expand Up @@ -68,53 +69,49 @@ def cancel(_: OperationCanceledError) -> None:
__running_tasks: set[Task[Any]] = set()


def start(computation: Awaitable[Any], token: CancellationToken | None = None) -> None:
"""Start computation.

Starts the asynchronous computation in the event loop. Do not await
its result.

If no cancellation token is provided then the default cancellation
token is used.
"""

async def runner() -> Any:
result = await computation
__running_tasks.remove(task)
return result
def _start_task(computation: Awaitable[_TSource], token: CancellationToken | None = None) -> Task[_TSource]:
async def runner() -> _TSource:
if token is not None and token.is_cancellation_requested:
raise asyncio.CancelledError()
return await computation

task = asyncio.create_task(runner())
loop = asyncio.get_running_loop()
task = loop.create_task(runner())
__running_tasks.add(task)
registration = None

def cb():
task.cancel()
def cancel() -> None:
loop.call_soon_threadsafe(task.cancel)

if token:
token.register(cb)
return None
if token is not None:
try:
registration = token.register(cancel)
except ObjectDisposedException:
cancel()

def cleanup(completed: Task[_TSource]) -> None:
__running_tasks.discard(completed)
if registration is not None:
registration.dispose()
# The wrapper may be cancelled before it ever awaits the coroutine.
if iscoroutine(computation):
computation.close()

def start_immediate(computation: Awaitable[Any], token: CancellationToken | None = None) -> None:
"""Start computation immediately.
task.add_done_callback(cleanup)
return task

Runs an asynchronous computation, starting immediately on the
current operating system thread.
"""

async def runner() -> Any:
result = await computation
__running_tasks.remove(task)
return result
def start(computation: Awaitable[Any], token: CancellationToken | None = None) -> None:
"""Schedule a computation on the running event loop."""
_start_task(computation, token)

task = asyncio.create_task(runner())
__running_tasks.add(task)

def cb() -> None:
task.cancel()
def start_immediate(computation: Awaitable[Any], token: CancellationToken | None = None) -> None:
"""Schedule a computation on the running event loop.

if token:
token.register(cb)
return None
Execution begins when the event loop next runs the task.
"""
_start_task(computation, token)


def run_synchronously(computation: Awaitable[_TSource]) -> _TSource:
Expand Down
Loading
Loading