chorus-actors 0.1.1__tar.gz

chorus_actors-0.1.1/LICENSE

@@ -0,0 +1,7 @@
+Copyright 2026 David Morrison
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

chorus_actors-0.1.1/PKG-INFO

@@ -0,0 +1,57 @@
+Metadata-Version: 2.4
+Name: chorus-actors
+Version: 0.1.1
+Summary: An actor library for Python
+Author: David Morrison
+Author-email: David Morrison <dm236@st-andrews.ac.uk>
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.12
+Project-URL: Repository, https://github.com/progspaces/chorus
+Project-URL: Documentation, https://chorus-actors.readthedocs.io/
+Project-URL: Issues, https://github.com/progspaces/chorus/issues
+Description-Content-Type: text/markdown
+
+# Chorus - A simple actor library for Python
+
+Chorus is a Python package that provides a version of the Actor model of concurrency. It is built ontop of Python's built-in threading package and each Actor has its own thread. Actors can send and recieve messges from other actors as well as spawn new Actors.
+
+The package has three layers:
+
+- `chorus.runtime` a minimal API for managing Python threads using the Actor model, roughly based on Erlangs API. 
+- `chorus.messaging` provides message base classes and request/reply exchanges with `tell` and `ask`.
+- `chorus.dispatch` provides an object-oriented API for sending and receiving messages between actors.
+
+There APIs can be imported directly from the ``chorus`` top-level package.
+
+## Installation
+Chorus requires Python 3.12 or later. The distribution is named `chorus-actors`; the Python import remains `chorus`. To add it to a project using uv:
+
+```sh
+uv add chorus-actors
+```
+
+Or install it with pip:
+
+```sh
+python -m pip install chorus-actors
+```
+
+## Documentation
+The documentation can be found [here](https://chorus-actors.readthedocs.io/en/latest/).
+
+## Examples:
+The [examples](./examples) are grouped by layer:
+
+- [runtime](./examples/runtime/): actors, raw messages, main-thread execution, and drawing.
+- [messaging](./examples/messaging/): message subclasses and request/reply exchanges.
+- [dispatch](./examples/dispatch/): counters, proxies, and GUI event-loop integration.
+
+To run an example from the repository root:
+
+```sh
+uv run examples/dispatch/proxy_counter.py
+```
+
+## License
+This project is licensed under the [MIT licence](./LICENSE).

chorus_actors-0.1.1/README.md

@@ -0,0 +1,43 @@
+# Chorus - A simple actor library for Python
+
+Chorus is a Python package that provides a version of the Actor model of concurrency. It is built ontop of Python's built-in threading package and each Actor has its own thread. Actors can send and recieve messges from other actors as well as spawn new Actors.
+
+The package has three layers:
+
+- `chorus.runtime` a minimal API for managing Python threads using the Actor model, roughly based on Erlangs API. 
+- `chorus.messaging` provides message base classes and request/reply exchanges with `tell` and `ask`.
+- `chorus.dispatch` provides an object-oriented API for sending and receiving messages between actors.
+
+There APIs can be imported directly from the ``chorus`` top-level package.
+
+## Installation
+Chorus requires Python 3.12 or later. The distribution is named `chorus-actors`; the Python import remains `chorus`. To add it to a project using uv:
+
+```sh
+uv add chorus-actors
+```
+
+Or install it with pip:
+
+```sh
+python -m pip install chorus-actors
+```
+
+## Documentation
+The documentation can be found [here](https://chorus-actors.readthedocs.io/en/latest/).
+
+## Examples:
+The [examples](./examples) are grouped by layer:
+
+- [runtime](./examples/runtime/): actors, raw messages, main-thread execution, and drawing.
+- [messaging](./examples/messaging/): message subclasses and request/reply exchanges.
+- [dispatch](./examples/dispatch/): counters, proxies, and GUI event-loop integration.
+
+To run an example from the repository root:
+
+```sh
+uv run examples/dispatch/proxy_counter.py
+```
+
+## License
+This project is licensed under the [MIT licence](./LICENSE).

chorus_actors-0.1.1/pyproject.toml

@@ -0,0 +1,41 @@
+[project]
+name = "chorus-actors"
+version = "0.1.1"
+description = "An actor library for Python"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.12"
+dependencies = []
+
+[[project.authors]]
+name = "David Morrison"
+email = "dm236@st-andrews.ac.uk"
+
+[project.urls]
+Repository = "https://github.com/progspaces/chorus"
+Documentation = "https://chorus-actors.readthedocs.io/"
+Issues = "https://github.com/progspaces/chorus/issues"
+
+[build-system]
+requires = ["uv_build>=0.11.13,<0.12.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "chorus"
+
+[tool.ruff]
+line-length = 88
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+
+[dependency-groups]
+dev = [
+    "pytest>=9.1.1",
+    "ruff>=0.15.21",
+    "shibuya>=2026.7.12",
+    "sphinxcontrib-mermaid>=2.1.1",
+]
+docs = ["sphinx>=9.1.0"]

chorus_actors-0.1.1/pyproject.toml.orig

@@ -0,0 +1,33 @@
+[project]
+name = "chorus-actors"
+version = "0.1.1"
+description = "An actor library for Python"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "David Morrison", email = "dm236@st-andrews.ac.uk" }]
+requires-python = ">=3.12"
+dependencies = []
+
+[project.urls]
+Repository = "https://github.com/progspaces/chorus"
+Documentation = "https://chorus-actors.readthedocs.io/"
+Issues = "https://github.com/progspaces/chorus/issues"
+
+[build-system]
+requires = ["uv_build>=0.11.13,<0.12.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "chorus"
+
+[dependency-groups]
+dev = ["pytest>=9.1.1", "ruff>=0.15.21", "shibuya>=2026.7.12", "sphinxcontrib-mermaid>=2.1.1"]
+docs = ["sphinx>=9.1.0"]
+
+[tool.ruff]
+line-length = 88
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"

chorus_actors-0.1.1/src/chorus/__init__.py

@@ -0,0 +1,60 @@
+from .dispatch import (
+    Call,
+    Error,
+    Invoke,
+    Kill,
+    Proxy,
+    Success,
+    process_pending,
+    spawn_server_with_proxy,
+)
+from .messaging import Event, Message, Request, Response, ask, tell
+from .runtime import (
+    ActorFunction,
+    ActorID,
+    ActorRecord,
+    ActorSystem,
+    ActorUnavailableException,
+    Mailbox,
+    me,
+    receive,
+    run,
+    run_main,
+    send,
+    set_local_actor,
+    register_thread_as_actor,
+    unregister_thread_as_actor,
+    spawn,
+)
+
+__all__ = [
+    "ActorFunction",
+    "ActorID",
+    "ActorRecord",
+    "ActorSystem",
+    "ActorUnavailableException",
+    "Call",
+    "Error",
+    "Event",
+    "Invoke",
+    "Kill",
+    "Mailbox",
+    "Message",
+    "Proxy",
+    "Request",
+    "Response",
+    "Success",
+    "ask",
+    "process_pending",
+    "me",
+    "receive",
+    "run",
+    "run_main",
+    "send",
+    "set_local_actor",
+    "register_thread_as_actor",
+    "unregister_thread_as_actor",
+    "spawn",
+    "spawn_server_with_proxy",
+    "tell",
+]

chorus_actors-0.1.1/src/chorus/dispatch/__init__.py

@@ -0,0 +1,15 @@
+from .handlers import process_pending, server, spawn_server_with_proxy
+from .messages import Call, Invoke, Kill, Error, Success
+from .proxy import Proxy
+
+__all__ = [
+    "server",
+    "process_pending",
+    "spawn_server_with_proxy",
+    "Proxy",
+    "Invoke",
+    "Kill",
+    "Error",
+    "Success",
+    "Call",
+]

chorus_actors-0.1.1/src/chorus/dispatch/handlers.py

@@ -0,0 +1,104 @@
+import inspect
+from typing import Any
+
+from ..messaging import tell
+from ..runtime import receive, spawn
+from .messages import Call, Error, Invoke, Kill, Success
+from .proxy import Proxy
+
+# The router works by getting a Invoke or Call message and finding an object in a
+# chain that can accept that message as a method call.
+# In the case of a Call, it then sends a response
+
+# the chain is a list of objects, refered to as handlers
+
+
+def can_handle(
+    handler: object, name: str, args: tuple[Any, ...], kwargs: dict[str, Any]
+) -> bool:
+    method = getattr(handler, name, None)
+
+    if not callable(method):
+        return False
+
+    try:
+        inspect.signature(method).bind(*args, **kwargs)
+        return True
+    except (TypeError, ValueError):
+        return False
+
+
+def find_handler(
+    handlers: list[object], name: str, args: tuple[Any, ...], kwargs: dict[str, Any]
+) -> object | None:
+    for handler in handlers:
+        if can_handle(handler, name, args, kwargs):
+            return handler  # stops on the first one that can handle
+    return None
+
+
+def dispatch(
+    handlers: list[object], name: str, args: tuple[Any, ...], kwargs: dict[str, Any]
+) -> Any:
+    handler = find_handler(handlers, name, args, kwargs)
+    if handler:
+        method = getattr(handler, name)  # default omitted as method is there
+        return method(*args, **kwargs)
+    else:
+        # todo: consider if this should just add the message back into the mailbox
+        # this would allow it to be handled later in a different way
+        raise ValueError("Cannot find a handler to dispatch the method on.")
+
+
+def dispatch_invoke(message: Invoke, handlers: list[object]) -> None:
+    try:
+        dispatch(handlers, message.name, message.args, message.kwargs)
+    except Exception as e:
+        print(f"Unable to route Invoke: {message}.")
+        print(e)
+
+
+def dispatch_call(message: Call, handlers: list[object]) -> None:
+    try:
+        result = dispatch(handlers, message.name, message.args, message.kwargs)
+        reply = Success(result, exchange_id=message.exchange_id)
+        tell(message.sender, reply)
+    except Exception as reason:
+        error = Error(reason, exchange_id=message.exchange_id)
+        tell(message.sender, error)
+
+
+def process_messages(handlers: list[object], keep_running=False) -> bool:
+    # todo - I am unsure thow to handle timeouts here
+    # currently the receive will just block forever or not block
+    while True:
+        message = receive(block=keep_running)
+        match message:
+            case Invoke():
+                dispatch_invoke(message, handlers)
+            case Call():
+                dispatch_call(message, handlers)
+            case Kill():
+                # this exits the loop and returns False
+                # meaning that the actor should terminate
+                return False
+            case None:
+                # this can only happen when block is false
+                # it tells any outer event-loop that the queue has been
+                # processed successfully
+                return True
+            case _:
+                print(f"Cannot route unknowns message: {message}")
+
+
+def server(handlers: list[object]):
+    process_messages(handlers, keep_running=True)
+
+
+def process_pending(handlers: list[object]):
+    return process_messages(handlers, keep_running=False)
+
+
+def spawn_server_with_proxy(handlers: list[object]) -> Proxy:
+    actor_id = spawn(server, handlers)
+    return Proxy(actor_id)

chorus_actors-0.1.1/src/chorus/dispatch/messages.py

@@ -0,0 +1,33 @@
+from dataclasses import dataclass, field
+from typing import Any
+
+from ..messaging.messages import Event, Request, Response
+
+
+@dataclass
+class Invoke(Event):
+    name: str
+    args: tuple[Any, ...] = ()
+    kwargs: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class Call(Request):
+    name: str
+    args: tuple[Any, ...] = ()
+    kwargs: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class Success(Response):
+    result: Any
+
+
+@dataclass
+class Error(Response):
+    reason: Any
+
+
+@dataclass
+class Kill(Event):
+    pass

chorus_actors-0.1.1/src/chorus/dispatch/proxy.py

@@ -0,0 +1,61 @@
+from abc import ABC, abstractmethod
+from typing import Any
+
+from ..messaging.exchange import ask, tell
+from ..runtime.system import ActorID
+from .messages import Call, Error, Invoke, Kill, Success
+
+
+class Dispatcher(ABC):
+    @abstractmethod
+    def dispatch(self, name: str, *args: Any, **kwargs: Any) -> Any:
+        raise NotImplementedError()
+
+    def __getattr__(self, name: str):
+        def missing(*args: Any, **kwargs: Any):
+            return self.dispatch(name, *args, **kwargs)
+
+        return missing
+
+
+class Teller(Dispatcher):
+    def __init__(self, target_id: ActorID):
+        self.target_id = target_id
+
+    def dispatch(self, name: str, *args: Any, **kwargs: Any) -> None:
+        event = Invoke(name=name, args=args, kwargs=kwargs)
+        tell(self.target_id, event)
+
+
+class Asker(Dispatcher):
+    def __init__(self, target_id: ActorID):
+        self.target_id = target_id
+
+    def dispatch(self, name: str, *args: Any, **kwargs: Any) -> Any:
+        request = Call(name=name, args=args, kwargs=kwargs)
+        response = ask(self.target_id, request)
+        match response:
+            case Success(result):
+                return result
+            case Error(reason):
+                raise reason
+            case _:
+                raise TypeError(f"Unexpected call response: {response!r}")
+
+
+class Proxy:
+    def __init__(self, target_id: ActorID):
+        self.target_id = target_id
+        self.teller = Teller(target_id)
+        self.asker = Asker(target_id)
+
+    @property
+    def tell(self):
+        return self.teller
+
+    @property
+    def ask(self):
+        return self.asker
+
+    def kill(self):
+        tell(self.target_id, Kill())

chorus_actors-0.1.1/src/chorus/messaging/__init__.py

@@ -0,0 +1,11 @@
+from .exchange import ask, tell
+from .messages import Event, Message, Request, Response
+
+__all__ = [
+    "Event",
+    "Message",
+    "Request",
+    "Response",
+    "ask",
+    "tell",
+]

chorus_actors-0.1.1/src/chorus/messaging/exchange.py

@@ -0,0 +1,29 @@
+import itertools
+from typing import Any
+
+from ..runtime.api import me, receive, send
+from ..runtime.system import ActorID
+from .messages import Event, Request, Response
+
+next_exchange_id = itertools.count(1)
+
+
+def make_exchange_id() -> int:
+    return next(next_exchange_id)
+
+
+def tell(id: ActorID, event: Event) -> None:
+    event.sender = me()
+    send(id, event)
+
+
+def ask(id: ActorID, request: Request, timeout: float | None = None) -> Response:
+    request.sender = me()
+    request.exchange_id = make_exchange_id()
+    send(id, request)
+
+    def match_id(msg: Any) -> bool:
+        # todo: there is a type checking issue but I don't know how to fix it
+        return isinstance(msg, Response) and msg.exchange_id == request.exchange_id
+
+    return receive(match_id, timeout=timeout)

chorus_actors-0.1.1/src/chorus/messaging/messages.py

@@ -0,0 +1,23 @@
+from dataclasses import dataclass, field
+
+from ..runtime.system import ActorID
+
+
+@dataclass
+class Message:
+    sender: ActorID = field(init=False)
+
+
+@dataclass
+class Event(Message):
+    pass
+
+
+@dataclass
+class Request(Message):
+    exchange_id: int = field(init=False)
+
+
+@dataclass
+class Response(Message):
+    exchange_id: int = field(kw_only=True)

chorus_actors-0.1.1/src/chorus/runtime/__init__.py

@@ -0,0 +1,27 @@
+from .api import ActorUnavailableException, me, receive, send, spawn
+from .lifecycle import (
+    register_thread_as_actor,
+    run,
+    run_main,
+    unregister_thread_as_actor,
+)
+from .mailbox import Mailbox
+from .system import ActorFunction, ActorID, ActorRecord, ActorSystem, set_local_actor
+
+__all__ = [
+    "ActorFunction",
+    "ActorID",
+    "ActorRecord",
+    "Mailbox",
+    "ActorSystem",
+    "ActorUnavailableException",
+    "me",
+    "receive",
+    "run",
+    "run_main",
+    "send",
+    "set_local_actor",
+    "register_thread_as_actor",
+    "unregister_thread_as_actor",
+    "spawn",
+]

chorus_actors-0.1.1/src/chorus/runtime/api.py

@@ -0,0 +1,76 @@
+"""Main actor API: spawn actors, send and receive messages, and get actor identity."""
+
+from typing import Any, Callable
+
+from .system import ActorFunction, ActorID, thread_context
+
+
+def spawn(target: ActorFunction, *args: Any, **kwargs: Any) -> ActorID:
+    """Spawn a new actor.
+
+    Args:
+        target (ActorFunction): The function to run in the actor.
+
+    Returns:
+        ActorID: The id of the new actor.
+    """
+    return thread_context.actor.system.run(target, *args, **kwargs)
+
+
+class ActorUnavailableException(Exception):
+    """Raised when
+
+    Args:
+        Exception (_type_): _description_
+    """
+
+    def __init__(self, actor_id: ActorID) -> None:
+        super().__init__()
+        self.actor_id = actor_id
+
+
+def send(id: ActorID, message: Any) -> None:
+    """Send an actor a message.
+
+    Messages can be of any type. Convention is strings or tuples.
+    String if the messages have no arguments.
+    Tuples if they have arguments.
+
+    Args:
+        id (ActorID): The id of the target actor.
+        message (Any): The message to send.
+    """
+    actors = thread_context.actor.system.actors
+    try:
+        target = actors[id]
+    except KeyError:
+        raise ActorUnavailableException(id)
+    else:
+        target.mailbox.put(message)
+
+
+def receive(
+    predicate: Callable[[Any], bool] | None = None,
+    block: bool = True,
+    timeout: float | None = None,
+) -> Any:
+    """Recieve the next message in the mailbox.
+
+    Blocks and waits until there is a message in the mailbox then gets it.
+
+    Returns:
+        Any: The next message in the mailbox.
+    """
+    mailbox = thread_context.actor.mailbox
+    return mailbox.get(predicate, block, timeout)
+
+
+def me() -> ActorID:
+    """Get the id of the current actor.
+
+    Equivalent to self in Erlang.
+
+    Returns:
+        ActorID: The id of the current actor.
+    """
+    return thread_context.actor.id

chorus_actors-0.1.1/src/chorus/runtime/lifecycle.py

@@ -0,0 +1,57 @@
+from typing import Any, Tuple
+
+from .system import ActorFunction, ActorID, ActorSystem, set_local_actor
+
+
+def run(
+    target: ActorFunction, *args: Any, **kwargs: Any
+) -> Tuple[ActorID, ActorSystem]:
+    """Run starts the target function as an actor in a new ActorSystem.
+
+    This helper abstracts a common pattern used when programs are started.
+    It let's you just do something like:
+
+    if __name__ == "__main__":
+        run(main)
+
+    where main is the function for an actor.
+
+    Args:
+        target (ActorFunction): The function to run in the actor.
+
+    Returns:
+        Tuple[ActorID, ActorSystem]: The id of the new actor and the system.
+    """
+    system = ActorSystem()
+    id = system.run(target, *args, **kwargs)
+    return id, system
+
+
+def register_thread_as_actor(system: ActorSystem) -> ActorID:
+    actor = system.next_actor()
+    set_local_actor(actor)
+    return actor.id
+
+
+def unregister_thread_as_actor(system: ActorSystem, main_actor_id: ActorID) -> None:
+    system.remove_actor(main_actor_id)
+
+
+def run_main(func: ActorFunction, *args: Any, **kwargs: Any) -> None:
+    """Create an actor for the main thread and then run the passesd function.
+
+    This helper abstracts a common pattern used when programs are started.
+    It let's you just do something like:
+
+    if __name__ == "__main__":
+        run_main(main)
+
+    Args:
+        func (ActorFunction): A function to act as our main.
+    """
+    system = ActorSystem()
+    actor = register_thread_as_actor(system)
+    try:
+        func(*args, **kwargs)
+    finally:
+        unregister_thread_as_actor(system, actor)

chorus_actors-0.1.1/src/chorus/runtime/mailbox.py

@@ -0,0 +1,104 @@
+import time
+from collections import deque
+from threading import Condition
+from typing import Any, Callable
+
+
+class Mailbox:
+    """Mailbox implements a queue of messages used for each actor."""
+
+    def __init__(self) -> None:
+        self.messages: deque[Any] = deque()
+        self.condition = Condition()
+
+    def put(self, message: Any):
+        """Add a message to the mailbox.
+
+        This operation does not block.
+
+        Args:
+            message (Any): A value to use as a message.
+        """
+        with self.condition:
+            self.messages.append(message)  # add new ones to the back
+            self.condition.notify()  # notify threads that are waiting
+
+    def get(
+        self,
+        predicate: Callable[[Any], bool] | None = None,
+        block: bool = True,
+        timeout: float | None = None,
+    ) -> Any:
+        """Gets a message from the mailbox.
+
+        The default behaviour is get the oldest message out of the mailbox.
+        If there isn't one, the method blocks indefinately until on arrives.
+        If block is False it means non-blocking and return immediately (timeout is ignored).
+        If block is True the behaviour is determined by timeout parameter.
+        If timeout is None, this mean block indefinately.
+        Otherwise block for that number of seconds.
+        Note that this means that if timeout is 0.0, this is the same as non-blocking.
+        Selective receive is supported by passing a predicate function that matches message.
+
+        Args:
+            predicate (Callable[..., bool] | None, optional): A condition to use to select a message. Defaults to None.
+            block (bool, optional): Should it block until there is a message. Defaults to True.
+            timeout (float, optional): How long it should block for. Defaults to 0.0.
+
+        Raises:
+            TimeoutError: The get timed out waiting for a message.
+
+        Returns:
+            Any: The message or None.
+        """
+        # this object is used when the queue is EMPTY
+        # this avoids falsey messasges like [] being missed
+        EMPTY = object()
+
+        # if there is a timeout, work out when the deadline is
+        deadline = time.monotonic() + timeout if timeout is not None else None
+
+        def get_next_message() -> Any:
+            """Pop the next message in the messages queue.
+            Return EMPTY if there isn't one.
+            Do not block.
+            """
+            if predicate:
+                # the queue is organised oldest at front
+                for idx, message in enumerate(self.messages):
+                    if predicate(message):
+                        del self.messages[idx]
+                        return message
+                return EMPTY
+            else:
+                if self.messages:
+                    return self.messages.popleft()
+                else:
+                    return EMPTY
+
+        # while there are no message
+        with self.condition:
+            while (message := get_next_message()) is EMPTY:
+                if not block:
+                    # if there is no messages are we are not blocking
+                    message = None
+                    break
+                elif not deadline:
+                    # if there is no message or timeout
+                    # wait until the queue changes
+                    self.condition.wait()
+                else:
+                    # if there are no messages and we are blocking with a timeout
+                    # workout the remaining time
+                    remaining = deadline - time.monotonic()
+
+                    # if it is less than or equal to zero, throw an exception
+                    if remaining <= 0:
+                        raise TimeoutError
+
+                    # otherwise block until message is added to queue or we run
+                    # out of remaining time on the timeout
+                    self.condition.wait(remaining)
+
+        # return the oldest message (new messages are added on the right)
+        return message

chorus_actors-0.1.1/src/chorus/runtime/system.py

@@ -0,0 +1,105 @@
+from __future__ import annotations
+
+import itertools
+from dataclasses import dataclass, field
+from threading import Thread, local
+from typing import Any, Callable
+
+from .mailbox import Mailbox
+
+# an actor function is a function that can have any args and returns None
+ActorFunction = Callable[..., None]
+
+
+@dataclass(frozen=True)
+class ActorID:
+    """Identifies an actor in the system.
+    Equivilent to an Erlang PID.
+
+    If we move to a distributed system, this can be exteneded to a more
+    complex address. Also we could us it as an adapter to fake method style
+    sends. E.g. my_actor.send(()) rather then send(my_actor, ()).
+    """
+
+    identifier: int
+
+    def __str__(self) -> str:
+        return str(self.identifier)
+
+
+@dataclass
+class ActorRecord:
+    """Holds all the information about a specific actor.
+
+    For convinience there is also a reference to the ActorSystem that is
+    running the actor.
+    """
+
+    id: ActorID
+    system: ActorSystem
+    mailbox: Mailbox = field(default_factory=Mailbox)
+
+
+# a thread local object to hold each threads instance of the Actor class
+# See https://docs.python.org/3/library/threading.html#thread-local-data.
+thread_context = local()
+
+
+def set_local_actor(actor: ActorRecord):
+    """Set the actor for this thread.
+
+    Useful when setting the actor for the main thread.
+
+    Args:
+        actor (Actor): The actor to use for this thread.
+    """
+    thread_context.actor = actor
+
+
+class ActorSystem:
+    """A container for the actors."""
+
+    def __init__(self) -> None:
+        self.next_id = itertools.count(1)
+        self.actors: dict[ActorID, ActorRecord] = {}
+
+    def next_actor(self):
+        id = ActorID(next(self.next_id))
+        actor = ActorRecord(id=id, system=self)
+        self.actors[id] = actor
+        return actor
+
+    def remove_actor(self, actor_id: ActorID) -> None:
+        del self.actors[actor_id]
+        del thread_context.actor
+
+    def run(self, target: ActorFunction, *args: Any, **kwargs: Any) -> ActorID:
+        """Creates a new actor in the system based on the function that is passed in.
+
+        Args:
+            target (ActorFunction): The function to run as the actor.
+
+        Returns:
+            ActorID: The actor id object, used to send messages to the actor.
+        """
+
+        actor = self.next_actor()
+
+        def run_actor():
+            set_local_actor(actor)
+            try:
+                target(*args, **kwargs)
+            finally:
+                self.remove_actor(actor.id)
+
+        # initialise the thread to target the run_actor function
+        thread = Thread(target=run_actor)
+
+        try:
+            # start the thread
+            thread.start()
+        except Exception:
+            # if it fails remove it for the actors list
+            del self.actors[actor.id]
+            raise
+        return actor.id