feat: asyncio-native Actor framework with supervision, middleware, and pluggable mailbox

Lightweight actor library built on asyncio primitives (~800 lines):

- Actor base class with lifecycle hooks (on_started/on_stopped/on_restart)
- ActorRef with tell (fire-and-forget) and ask (request-response)
- Supervision: OneForOne/AllForOne strategies with restart limits
- Middleware pipeline for cross-cutting concerns
- Pluggable Mailbox interface (MemoryMailbox default, RedisMailbox optional)
- ReplyRegistry + ReplyChannel: ask() works across any mailbox backend
- System-level thread pool for blocking I/O (run_in_executor)
- Dead letter handling, poison message quarantine, parallel shutdown
- 22 tests + benchmark suite
This commit is contained in:
greatmengqi
2026-03-30 23:35:28 +08:00
parent 9e3d484858
commit 3e17417122
11 changed files with 1851 additions and 0 deletions
@@ -0,0 +1,40 @@
"""Async Actor framework — lightweight, asyncio-native, supervision-ready.
Usage::
from deerflow.actor import Actor, ActorSystem
class Greeter(Actor):
async def on_receive(self, message):
return f"Hello, {message}!"
async def main():
system = ActorSystem("app")
ref = await system.spawn(Greeter, "greeter")
reply = await ref.ask("World", timeout=5.0)
print(reply) # Hello, World!
await system.shutdown()
"""
from .actor import Actor, ActorContext
from .mailbox import Mailbox, MemoryMailbox
from .middleware import Middleware
from .ref import ActorRef, ReplyChannel
from .supervision import AllForOneStrategy, Directive, OneForOneStrategy, SupervisorStrategy
from .system import ActorSystem, DeadLetter
__all__ = [
"Actor",
"ActorContext",
"ActorRef",
"ActorSystem",
"AllForOneStrategy",
"DeadLetter",
"Directive",
"Mailbox",
"MemoryMailbox",
"Middleware",
"OneForOneStrategy",
"ReplyChannel",
"SupervisorStrategy",
]