asimpy 0.2.0__py3-none-any.whl → 0.3.0__py3-none-any.whl

asimpy/__init__.py

@@ -1,8 +1,12 @@
 """Discrete event simulation using async/await."""
 
+from .allof import AllOf as AllOf
+from .barrier import Barrier as Barrier
 from .environment import Environment as Environment
-from .gate import Gate as Gate
+from .event import Event as Event
+from .firstof import FirstOf as FirstOf
 from .interrupt import Interrupt as Interrupt
 from .process import Process as Process
 from .queue import Queue as Queue, PriorityQueue as PriorityQueue
 from .resource import Resource as Resource
+from .timeout import Timeout as Timeout

asimpy/_adapt.py

@@ -0,0 +1,25 @@
+import inspect
+from .event import Event
+from .process import Process
+
+def ensure_event(env, obj):
+    if isinstance(obj, Event):
+        return obj
+
+    if inspect.iscoroutine(obj):
+        evt = Event(env)
+        _Runner(env, evt, obj)
+        return evt
+
+    raise TypeError(f"Expected Event or coroutine, got {type(obj)}")
+
+
+
+class _Runner(Process):
+    def init(self, evt, obj):
+        self.evt = evt
+        self.obj = obj
+
+    async def run(self):
+        result = await self.obj
+        self.evt.succeed(result)

asimpy/allof.py

@@ -0,0 +1,50 @@
+"""Wait for all events in a set to complete."""
+
+from typing import Any
+from .environment import Environment
+from .event import Event
+from ._adapt import ensure_event
+
+
+class AllOf(Event):
+    """Wait for all of a set of events."""
+    
+    def __init__(self, env: Environment, **events: Any):
+        """
+        Construct new collective wait.
+
+        Args:
+            env: simulation environment.
+            events: name=thing items to wait for.
+
+        Example:
+
+        ```
+        name, value = await AllOf(env, a=q1.get(), b=q2.get())
+        ```
+        """
+        assert len(events) > 0
+        super().__init__(env)
+
+        self._events = {}
+        self._results = {}
+
+        for key, obj in events.items():
+            evt = ensure_event(env, obj)
+            self._events[key] = evt
+            evt._add_waiter(_AllOfWatcher(self, key))
+
+
+    def _child_done(self, key, value):
+        self._results[key] = value
+        if len(self._results) == len(self._events):
+            self.succeed(self._results)
+
+
+class _AllOfWatcher:
+    def __init__(self, parent, key):
+        self.parent = parent
+        self.key = key
+
+    def _resume(self, value):
+        self.parent._child_done(self.key, value)

asimpy/barrier.py

@@ -0,0 +1,33 @@
+"""Barrier that holds multiple processes until released."""
+
+from typing import TYPE_CHECKING
+from .event import Event
+
+if TYPE_CHECKING:
+    from .environment import Environment
+
+
+class Barrier:
+    """Barrier to hold multiple processes."""
+
+    def __init__(self, env: "Environment"):
+        """
+        Construct barrier.
+
+        Args:
+            env: simulation environment.
+        """
+        self._env = env
+        self._waiters = []
+
+    async def wait(self):
+        """Wait until barrier released."""
+        evt = Event(self._env)
+        self._waiters.append(evt)
+        await evt
+
+    async def release(self):
+        """Release processes waiting at barrier."""
+        for evt in self._waiters:
+            evt.succeed()
+        self._waiters.clear()

asimpy/environment.py

@@ -1,121 +1,51 @@
 """Simulation environment."""
 
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 import heapq
-from .actions import BaseAction
-from .process import Process
+import itertools
+from typing import Callable
 
+from .timeout import Timeout
 
-class Environment:
-    """Simulation environment."""
-
-    def __init__(self, logging: bool = False):
-        """
-        Construct a new simulation environment.
 
-        Args:
-            logging: print log messages while executing.
-        """
-        self.now = 0
-        self._queue = []
+class Environment:
+    def __init__(self, logging=False):
+        self._now = 0
         self._logging = logging
+        self._pending = []
 
-    def immediate(self, proc: Process):
-        """
-        Start a new process immediately.
-
-        Args:
-            proc: `Process`-derived object to schedule and run.
-        """
-        self.schedule(self.now, proc)
-
-    def schedule(self, time: float | int, proc: Process):
-        """
-        Schedule a process to run at a specified time (*not* after a delay).
-
-        Args:
-            time: when the process should be scheduled to run.
-            proc: `Process`-derived object to run.
-        """
-        heapq.heappush(self._queue, _Pending(time, proc))
+    @property
+    def now(self):
+        return self._now
 
-    def sleep(self, delay: float | int) -> "_Sleep":
-        """
-        Suspend the caller for a specified length of time.
+    def schedule(self, time, callback):
+        heapq.heappush(self._pending, _Pending(time, callback))
 
-        Args:
-            delay: how long to sleep.
-
-        Returns: awaitable representing delay.
-        """
-        return _Sleep(self, delay)
-
-    def run(self, until: float | int | None = None):
-        """
-        Run the whole simulation.
-
-        Args:
-            until: when to stop (run forever if not provided).
-        """
-        while self._queue:
-            if self._logging:
-                print(self)
-
-            pending = heapq.heappop(self._queue)
+    def timeout(self, delay):
+        return Timeout(self, delay)
 
+    def run(self, until=None):
+        while self._pending:
+            pending = heapq.heappop(self._pending)
             if until is not None and pending.time > until:
                 break
+            self._now = pending.time
+            pending.callback()
 
-            self.now = pending.time
-            proc = pending.proc
-
-            try:
-                if proc._interrupt is None:
-                    awaited = proc._coro.send(None)
-                else:
-                    exc, proc._interrupt = proc._interrupt, None
-                    awaited = proc._coro.throw(exc)
+    def _immediate(self, callback):
+        self.schedule(self._now, callback)
 
-                awaited.act(proc)
+    def __str__(self):
+        return f"Env(t={self._now})"
 
-            except StopIteration:
-                continue
 
-    def __str__(self) -> str:
-        """
-        Format environment as printable string.
-
-        Returns: string representation of environment time and queue.
-        """
-        return f"Env(t={self.now}, {' | '.join(str(p) for p in self._queue)})"
-
-
-# ----------------------------------------------------------------------
-
-
-@dataclass
+@dataclass(order=True)
 class _Pending:
-    """Keep track of a waiting process."""
+    _counter = itertools.count()
 
     time: float
-    proc: Process
-
-    def __lt__(self, other: "_Pending") -> bool:
-        return self.time < other.time
-
-    def __str__(self) -> str:
-        return f"Pend({self.time}, {self.proc})"
-
-
-class _Sleep(BaseAction):
-    """Wait for a specified simulated time."""
-
-    def __init__(self, env: Environment, delay: float | int):
-        super().__init__(env)
-        self._delay = delay
-
-    def act(self, proc: Process):
-        self._env.schedule(self._env.now + self._delay, proc)
+    serial: int = field(init=False, repr=False, compare=True)
+    callback: Callable = field(compare=False)
 
-    def __str__(self) -> str:
-        return f"_Sleep({self._delay})"
+    def __post_init__(self):
+        self.serial = next(self._counter)

asimpy/event.py

@@ -0,0 +1,56 @@
+"""Events."""
+
+from typing import TYPE_CHECKING, Any
+if TYPE_CHECKING:
+    from .environment import Environment
+
+class Event:
+    """Manage an event."""
+
+    def __init__(self, env: "Environment"):
+        """
+        Construct a new event.
+
+        Args:
+            env: simulation environment.
+        """
+        self._env = env
+        self._triggered = False
+        self._cancelled = False
+        self._value = None
+        self._waiters = []
+        self._on_cancel = None
+
+    def succeed(self, value: Any = None):
+        """
+        Handle case of event succeeding.
+
+        Args:
+            value: value associated with event.
+        """
+        if self._triggered or self._cancelled:
+            return
+        self._triggered = True
+        self._value = value
+        for proc in self._waiters:
+            proc._resume(value)
+        self._waiters.clear()
+
+    def cancel(self):
+        """Cancel event."""
+        if self._triggered or self._cancelled:
+            return
+        self._cancelled = True
+        self._waiters.clear()
+        if self._on_cancel:
+            self._on_cancel()
+
+    def _add_waiter(self, proc):
+        if self._triggered:
+            proc._resume(self._value)
+        elif not self._cancelled:
+            self._waiters.append(proc)
+
+    def __await__(self):
+        value = yield self
+        return value

asimpy/firstof.py

@@ -0,0 +1,56 @@
+"""Wait for the first of a set of events."""
+
+from typing import Any
+from .environment import Environment
+from .event import Event
+from ._adapt import ensure_event
+
+
+class FirstOf(Event):
+    """Wait for the first of a set of events."""
+
+    def __init__(self, env: Environment, **events: Any):
+        """
+        Construct new collective wait.
+
+        Args:
+            env: simulation environment.
+            events: name=thing items to wait for.
+
+        Example:
+
+        ```
+        name, value = await FirstOf(env, a=q1.get(), b=q2.get())
+        ```
+        """
+        assert len(events) > 0
+        super().__init__(env)
+
+        self._done = False
+        self._events = {}
+
+        for key, obj in events.items():
+            evt = ensure_event(env, obj)
+            self._events[key] = evt
+            evt._add_waiter(_FirstOfWatcher(self, key, evt))
+
+    def _child_done(self, key, value, winner):
+        if self._done:
+            return
+        self._done = True
+
+        for evt in self._events.values():
+            if evt is not winner:
+                evt.cancel()
+
+        self.succeed((key, value))
+
+
+class _FirstOfWatcher:
+    def __init__(self, parent, key, evt):
+        self.parent = parent
+        self.key = key
+        self.evt = evt
+
+    def _resume(self, value):
+        self.parent._child_done(self.key, value, self.evt)

asimpy/interrupt.py

@@ -1,25 +1,20 @@
-"""Interruption exceptions."""
+"""Interrupt exceptions."""
 
 from typing import Any
 
 
 class Interrupt(Exception):
-    """Custom exception class for interruptions."""
+    """Interrupt raised inside a process."""
 
     def __init__(self, cause: Any):
         """
-        Construct a new interruption exception.
+        Construct interruption exception.
 
         Args:
-            cause: reason for interruption.
+            cause: reason for interrupt.
         """
         super().__init__()
         self.cause = cause
 
-    def __str__(self) -> str:
-        """
-        Format interruption as printable string.
-
-        Returns: string representation of interruption and cause.
-        """
+    def __str__(self):
         return f"Interrupt({self.cause})"

asimpy/process.py

@@ -1,7 +1,7 @@
-"""Base class for processes."""
+"""Base class for active process."""
 
 from abc import ABC, abstractmethod
-from typing import Any, TYPE_CHECKING
+from typing import TYPE_CHECKING, Any
 
 from .interrupt import Interrupt
 
@@ -10,47 +10,83 @@ if TYPE_CHECKING:
 
 
 class Process(ABC):
-    """Base class for active processes."""
+    """Abstract base class for active process."""
 
-    def __init__(self, env: "Environment", *args: Any):
+    def __init__(self, env: "Environment", *args: Any, **kwargs: Any):
         """
-        Construct a new process by performing common initialization,
-        calling the user-defined `init()` method (no underscores),
-        and registering the coroutine created by the `run()` method
-        with the environment.
+        Construct new process.
 
         Args:
             env: simulation environment.
-            *args: to be passed to `init()` for custom initialization.
+            args: extra constructor arguments passed to `init()`.
         """
-        self.env = env
+        self._env = env
+        self._done = False
         self._interrupt = None
-
-        self.init(*args)
-
+        self.init(*args, **kwargs)
         self._coro = self.run()
-        self.env.immediate(self)
+        self._env._immediate(self._loop)
 
-    def init(self, *args: Any, **kwargs: Any) -> None:
+    def init(self, *args: Any, **kwargs: Any):
         """
-        Default (do-nothing) post-initialization method.
+        Extra construction after generic setup but before coroutine created.
 
-        To satisfy type-checking, derived classes must also declare `*args`
-        rather than listing specific parameters by name.
+        Args:
+            args: extra constructor arguments passed to `init()`.
+            kwargs: extra construct arguments passed to `init()`.
         """
         pass
 
+    @abstractmethod
+    def run(self):
+        """Implementation of process behavior."""
+        pass
+
+    @property
+    def now(self):
+        """Shortcut to access simulation time."""
+        return self._env.now
+
+    def timeout(self, delay: int | float):
+        """
+        Delay this process for a specified time.
+
+        Args:
+            delay: how long to wait.
+        """
+        return self._env.timeout(delay)
+
     def interrupt(self, cause: Any):
         """
-        Interrupt this process by raising an `Interrupt` exception the
-        next time the process is scheduled to run.
+        Interrupt this process
 
         Args:
-            cause: reason for interrupt (attacked to `Interrupt` exception).
+            cause: reason for interrupt.
         """
-        self._interrupt = Interrupt(cause)
+        if not self._done:
+            self._interrupt = Interrupt(cause)
+            self._env._immediate(self._loop)
 
-    @abstractmethod
-    def run(self):
-        """Actions for this process."""
-        pass
+    def _loop(self, value=None):
+        if self._done:
+            return
+
+        try:
+            if self._interrupt is None:
+                yielded = self._coro.send(value)
+            else:
+                exc = self._interrupt
+                self._interrupt = None
+                yielded = self._coro.throw(exc)
+            yielded._add_waiter(self)
+
+        except StopIteration:
+            self._done = True
+
+        except Exception as exc:
+            self._done = True
+            raise exc
+
+    def _resume(self, value=None):
+        if not self._done:
+            self._env._immediate(lambda: self._loop(value))

asimpy/queue.py

@@ -1,147 +1,64 @@
-"""Queues."""
+"""FIFO and priority queues."""
 
-from abc import ABC, abstractmethod
 import heapq
-from typing import TYPE_CHECKING
-from .actions import BaseAction
+from typing import TYPE_CHECKING, Any
+from .event import Event
 
 if TYPE_CHECKING:
     from .environment import Environment
 
-
-class BaseQueue(ABC):
-    """Base class for all queues."""
+class Queue:
+    """FIFO queue."""
 
     def __init__(self, env: "Environment"):
         """
-        Generic queue construction.
+        Construct queue.
 
         Args:
             env: simulation environment.
         """
         self._env = env
-        self._gets = []
+        self._items = []
+        self._getters = []
 
     async def get(self):
-        """Get an item from the queue when one is available."""
-        return await _Get(self)
-
-    async def put(self, obj):
-        """Add an item to the queue."""
-        await _Put(self, obj)
-
-    @abstractmethod
-    def _dequeue(self):
-        pass
-
-    @abstractmethod
-    def _empty(self):
-        pass
-
-    @abstractmethod
-    def _enqueue(self, obj):
-        pass
-
-
-# ----------------------------------------------------------------------
-
-
-class Queue(BaseQueue):
-    """FIFO queue."""
-
-    def __init__(self, env):
+        """Get one item from the queue."""
+        if self._items:
+            item = self._items.pop(0)
+            evt = Event(self._env)
+            self._env._immediate(lambda: evt.succeed(item))
+            evt._on_cancel = lambda: self._items.insert(0, item)
+            return await evt
+
+        evt = Event(self._env)
+        self._getters.append(evt)
+        return await evt
+
+    async def put(self, item: Any):
         """
-        Construct queue.
+        Add one item to the queue.
 
         Args:
-            env: simulation environment.
+            item: to add to the queue.
         """
-        super().__init__(env)
-        self._items = []
-
-    def _dequeue(self):
-        assert len(self._items) > 0
-        return self._items.pop(0)
-
-    def _enqueue(self, obj):
-        self._items.append(obj)
-
-    def _empty(self):
-        return len(self._items) == 0
-
-    def __str__(self):
-        return f"Queue({', '.join(str(i) for i in self._items)})"
-
-
-# ----------------------------------------------------------------------
+        if self._getters:
+            evt = self._getters.pop(0)
+            evt.succeed(item)
+        else:
+            self._items.append(item)
 
 
-class PriorityQueue(BaseQueue):
-    """Priority queue (lower values have higher priority)."""
+class PriorityQueue(Queue):
+    """Ordered queue."""
 
-    def __init__(self, env):
+    async def put(self, item: Any):
         """
-        Construct queue.
+        Add one item to the queue.
 
         Args:
-            env: simulation environment.
+            item: comparable item to add to queue.
         """
-        super().__init__(env)
-        self._items = []
-
-    def _dequeue(self):
-        assert len(self._items) > 0
-        return heapq.heappop(self._items)
-
-    def _enqueue(self, obj):
-        heapq.heappush(self._items, obj)
-
-    def _empty(self):
-        return len(self._items) == 0
-
-    def __str__(self):
-        return f"PriorityQueue({', '.join(str(i) for i in self._items)})"
-
-
-# ----------------------------------------------------------------------
-
-
-class _Get(BaseAction):
-    """Get an item from the queue."""
-
-    def __init__(self, queue):
-        super().__init__(queue._env)
-        self._queue = queue
-        self._proc = None
-        self._item = None
-
-    def act(self, proc):
-        if self._queue._empty():
-            self._proc = proc
-            self._queue._gets.append(self)
-        else:
-            self._item = self._queue._dequeue()
-            self._env.schedule(self._env.now, proc)
-
-    def __await__(self):
-        yield self
-        return self._item
-
-
-class _Put(BaseAction):
-    """Put an item in a queue."""
-
-    def __init__(self, queue, obj):
-        super().__init__(queue._env)
-        self._queue = queue
-        self.obj = obj
-
-    def act(self, proc):
-        self._queue._enqueue(self.obj)
-
-        if len(self._queue._gets) > 0:
-            waiting_get = self._queue._gets.pop(0)
-            waiting_get._item = self._queue._dequeue()
-            self._env.schedule(self._env.now, waiting_get._proc)
-
-        self._env.schedule(self._env.now, proc)
+        heapq.heappush(self._items, item)
+        if self._getters:
+            evt = self._getters.pop(0)
+            evt.succeed(heapq.heappop(self._items))

asimpy/resource.py

@@ -1,76 +1,69 @@
 """Shared resource with limited capacity."""
 
 from typing import TYPE_CHECKING
-from .actions import BaseAction
-from .process import Process
+from .event import Event
 
 if TYPE_CHECKING:
     from .environment import Environment
 
-
 class Resource:
-    """Shared resource with limited capacity."""
+    """A shared resource with limited capacity."""
 
     def __init__(self, env: "Environment", capacity: int = 1):
         """
-        Create a new resource.
+        Construct resource.
 
         Args:
             env: simulation environment.
-            capacity: maximum simultaneous users.
+            capacity: maximum capacity.
         """
+        assert capacity > 0
         self._env = env
-        self._capacity = capacity
+        self.capacity = capacity
         self._count = 0
-        self._waiting = []
+        self._waiters = []
 
     async def acquire(self):
-        """Acquire one unit of the resource."""
-        await _Acquire(self)
+        """Acquire one unit of resource."""
+        if self._count < self.capacity:
+            await self._acquire_available()
+        else:
+            await self._acquire_unavailable()
 
     async def release(self):
-        """Release one unit of the resource."""
-        await _Release(self)
-
-    async def __aenter__(self):
-        """Acquire one unit of the resource using `async with`."""
-        await self.acquire()
-        return self
-
-    async def __aexit__(self, exc_type, exc, tb):
-        """Release one unit of the resource acquired with `async with`."""
-        await self.release()
-
+        """Release one unit of resource."""
+        self._count -= 1
+        if self._waiters:
+            evt = self._waiters.pop(0)
+            evt.succeed()
 
-# ----------------------------------------------------------------------
+    async def _acquire_available(self):
+        self._count += 1
+        evt = Event(self._env)
 
+        def cancel():
+            self._count -= 1
 
-class _Acquire(BaseAction):
-    """Acquire a resource."""
+        evt._on_cancel = cancel
+        self._env._immediate(evt.succeed)
+        await evt
 
-    def __init__(self, resource: Resource):
-        super().__init__(resource._env)
-        self._resource = resource
+    async def _acquire_unavailable(self):
+        evt = Event(self._env)
+        self._waiters.append(evt)
 
-    def act(self, proc: Process):
-        if self._resource._count < self._resource._capacity:
-            self._resource._count += 1
-            self._env.schedule(self._env.now, proc)
-        else:
-            self._resource._waiting.append(proc)
+        def cancel():
+            if evt in self._waiters:
+                self._waiters.remove(evt)
 
+        evt._on_cancel = cancel
+        await evt
 
-class _Release(BaseAction):
-    """Release a resource."""
+        self._count += 1
 
-    def __init__(self, resource: Resource):
-        super().__init__(resource._env)
-        self._resource = resource
+    async def __aenter__(self):
+        await self.acquire()
+        return self
 
-    def act(self, proc: Process):
-        self._resource._count -= 1
-        if self._resource._waiting:
-            next_proc = self._resource._waiting.pop(0)
-            self._resource._count += 1
-            self._env.schedule(self._env.now, next_proc)
-        self._env.schedule(self._env.now, proc)
+    async def __aexit__(self, exc_type, exc, tb):
+        await self.release()

asimpy/timeout.py

@@ -0,0 +1,23 @@
+"""Wait for a simulated time to pass."""
+
+from typing import TYPE_CHECKING
+from .event import Event
+
+if TYPE_CHECKING:
+    from .environment import Environment
+
+
+class Timeout(Event):
+    """Timeout event for sleeping."""
+
+    def __init__(self, env: "Environment", delay: float | int):
+        """
+        Construct timeout.
+
+        Args:
+            env: simulation environment.
+            delay: how long to wait.
+        """
+        assert delay >= 0
+        super().__init__(env)
+        env.schedule(env.now + delay, lambda: self.succeed())

asimpy-0.3.0.dist-info/METADATA

@@ -0,0 +1,241 @@
+Metadata-Version: 2.4
+Name: asimpy
+Version: 0.3.0
+Summary: A simple discrete event simulator using async/await
+Author-email: Greg Wilson <gvwilson@third-bit.com>
+Maintainer-email: Greg Wilson <gvwilson@third-bit.com>
+License-File: LICENSE.md
+Keywords: discrete event simulation,open source
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.13
+Provides-Extra: dev
+Requires-Dist: build>=1.4.0; extra == 'dev'
+Requires-Dist: markdown-include>=0.8.1; extra == 'dev'
+Requires-Dist: mkdocs-awesome-pages-plugin>=2.10.1; extra == 'dev'
+Requires-Dist: mkdocs-material>=9.7.1; extra == 'dev'
+Requires-Dist: mkdocs>=1.6.1; extra == 'dev'
+Requires-Dist: mkdocstrings[python]>=1.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.14.10; extra == 'dev'
+Requires-Dist: taskipy>=1.14.1; extra == 'dev'
+Requires-Dist: twine>=6.2.0; extra == 'dev'
+Requires-Dist: ty>=0.0.11; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# asimpy
+
+A simple discrete event simulation framework in Python using `async`/`await`.
+
+-   [Documentation][docs]
+-   [Package][package]
+-   [Repository][repo]
+-   [Examples][examples]
+
+*Thanks to the creators of [SimPy][simpy] for inspiration.*
+
+## What This Is
+
+This discrete-event simulation framework uses Python's `async`/`await` without `asyncio`.
+Key concepts include:
+
+-   Simulation time is virtual, not wall-clock time.
+-   Processes are active entities (customers, producers, actors).
+-   Events are things that happen at specific simulation times.
+-   `await` is used to pause a process until an event occurs.
+-   A single-threaded event loop (the `Environment` class) advances simulated time and resumes processes.
+
+The result feels like writing synchronous code, but executes deterministically.
+
+## The Environment
+
+The `Environment` class is the core of `asimpy`.
+It store upcoming events in a heap that keeps entries ordered by (simulated) time.
+`env.run()` repeatedly pops the earliest scheduled callback,
+advances `env._now` to that time,
+and runs the callback.
+
+> The key idea is that *nothing runs until the environment schedules it*.
+
+## Events
+
+An `Event` represents something that may happen later (similar to an `asyncio` `Future`).
+When a process runs:
+
+```python
+value = await some_event
+```
+
+the following happens:
+
+1.  `Event.__await__()` yields the event object.
+1.  The process is suspended.
+1.  The process is registered as a waiter on that event.
+
+When `event.succeed(value)` is called:
+
+1.  The event is marked as triggered.
+1.  All waiting processes are resumed.
+1.  Each of those processes receives `value` as the result of `await`.
+
+One way to understand `Event` is to look at the purpose of its key attributes.
+
+### `_triggered`
+
+The Boolean `_triggered` indicates whether this event has already successfully occurred.
+It is initially `False`,
+and is set to `True` when `evt.succeed(value)` is called.
+If the event has been triggered before,
+and some process wants to wait on it later,
+that process is immediately resumed with the store `_value`.
+This prevents lost or duplicated notifications.
+
+```python
+def succeed(self, value=None):
+    if self._triggered or self._cancelled:
+        return
+    self._triggered = True
+    self._value = value
+    for proc in self._waiters:
+        proc._resume(value)
+    self._waiters.clear()
+```
+
+### `_cancelled` and `_on_cancel`
+
+The Boolean `_cancelled` indicates whether the event was aborted before it could succeed.
+It is also initially `False`,
+and is used in both `succeed()` (shown above) and in `cancel()`:
+
+```python
+def cancel(self):
+    if self._triggered or self._cancelled:
+        return
+    self._cancelled = True
+    self._waiters.clear()
+    if self._on_cancel:
+        self._on_cancel()
+```
+
+If a cancellation callback has been registered with the event,
+the callback is executed to do resource cleanup.
+For example,
+suppose a program is using `FirstOf` to wait until an item is available
+on one or the other of two queues.
+If both queues become ready at the same simulated time,
+the program might take one item from both queues
+when it should instead take an item from one or the other queue.
+To clean this up,
+`Queue.get()` registers a callback that puts an item back at the front of the queue
+to prevent incorrect over-consumption of items:
+
+```python
+evt._on_cancel = lambda: self._items.insert(0, item)
+```
+
+### `_value`
+
+When `evt.succeed(value)` is called,
+the value passed in is saved as `evt._value`.
+Any process resuming from `await event` receives this value:
+
+```python
+class Event:
+    def __await__(self):
+        value = yield self
+        return value
+```
+
+This is how the framework passes results between processes:
+for example,
+the value of a `Queue.get()` event is the item retrieved from the queue.
+
+### `_waiters`
+
+`_waiters` is a list of processes waiting for the event to complete.
+When a process `await`s an event,
+it is added to the list by the internal method `_add_waiter()`.
+If the event has already been triggered,
+`_add_waiter` immediately resumes the process:
+
+```python
+def _add_waiter(self, proc):
+    if self._triggered:
+        proc._resume(self._value)
+    elif not self._cancelled:
+        self._waiters.append(proc)
+```
+
+When `succeed()` is called,
+every process in `_waiters` is resumed and `_waiters` is cleared.
+When `cancel()` is called, `_waiters` is cleared without resuming any process.
+
+## Processes
+
+The `Process` class wraps an `async def run()` coroutine.
+When a `Process` is created,
+its constructor called `self.run()` to create a coroutine
+and then gives the `self._loop` callback to the `Enviroment`,
+which schedules it to run.
+
+`self._loop` drives the coroutine by executing:
+
+```python
+yielded = self._coro.send(value)
+yielded._add_waiter(self)
+```
+
+1.  The coroutine runs until it hits `await`.
+1.  The `await` yields an `Event`.
+1.  The process registers itself as waiting on that event.
+1.  Control returns to the environment.
+
+When the event fires, it calls:
+
+```python
+proc._resume(value)
+```
+
+which schedules `_loop(value)` again.
+
+## Example: `Timeout`
+
+The entire `Timeout` class is:
+
+```python
+class Timeout(Event):
+    def __init__(self, env, delay):
+        super().__init__(env)
+        env.schedule(env.now + delay, lambda: self.succeed())
+```
+
+which simply asks the `Environment` to schedule `Event.succeed()` in the simulated future.
+
+## Example: `FirstOf`
+
+Suppose the queue `q1` contains `"A"` and the `q2` contains `"B"`,
+and a process then waits for a value from either queue with:
+
+```python
+item = await FirstOf(env, a=q1.get(), b=q2.get())
+```
+
+The sequence of events is:
+
+| Action / Event                            | Queue State        | Event State                             | Process / Waiters                                | Notes                                                     |
+| ----------------------------------------- | ------------------ | --------------------------------------- | ------------------------------------------------ | --------------------------------------------------------- |
+| `Tester` starts                           | q1=["A"], q2=["B"] | evt_a & evt_b created                   | `_waiters` in evt_a and evt_b = [Tester]         | `FirstOf` yields to environment                           |
+| `q1.get()` removes "A"                    | q1=[], q2=["B"]    | evt_a._value=None, _triggered=False     | evt_a._waiters=[FirstOfWatcher]                  | _on_cancel set to re-insert "A" if cancelled              |
+| `q2.get()` removes "B"                    | q1=[], q2=[]       | evt_b._value=None, _triggered=False     | evt_b._waiters=[FirstOfWatcher]                  | _on_cancel set to re-insert "B" if cancelled              |
+| Environment immediately triggers evt_a    | q1=[], q2=[]       | evt_a._value="A", _triggered=True       | _waiters processed: FirstOf._child_done() called | This is the winner                                        |
+| FirstOf `_child_done()` sets `_done=True` | q1=[], q2=[]       | _done=True                              | _events = {a: evt_a, b: evt_b}                   | Notifies all losing events to cancel                      |
+| evt_b.cancel() called (loser)             | q1=[], q2=[]       | evt_b._cancelled=True                   | _waiters cleared                                 | _on_cancel triggers: inserts "B" back at front of q2      |
+| `_on_cancel` restores item                | q1=[], q2=["B"]    | evt_b._triggered=False, _cancelled=True | _waiters cleared                                 | Queue order preserved                                     |
+| FirstOf succeeds with winner              | q1=[], q2=["B"]    | _value=("a","A"), _triggered=True       | Processes waiting on FirstOf resumed             | `Tester` receives ("a","A")                               |
+| `Tester` continues execution              | q1=[], q2=["B"]    | -                                       | -                                                | Remaining queue items untouched; correct order guaranteed |
+
+[docs]: https://gvwilson.github.io/asimpy
+[examples]: https://gvwilson.github.io/asimpy/examples/
+[package]: https://pypi.org/project/asimpy/
+[repo]: https://github.com/gvwilson/asimpy
+[simpy]: https://simpy.readthedocs.io/

asimpy-0.3.0.dist-info/RECORD

@@ -0,0 +1,16 @@
+asimpy/__init__.py,sha256=zJx5CIZDInFYyjXT99QpYQvp1x5aQluob9amrnmPJkU,487
+asimpy/_adapt.py,sha256=GHiDp8wmMrr3XWfGRDM1rrFJ2KR7_7F8L0xB4g6pe5U,521
+asimpy/allof.py,sha256=8UpFe_-hmtm2brt-SHk1RgBv55agcef5AathH11Ax2E,1216
+asimpy/barrier.py,sha256=evubm6H_93qi9vBogqrNLg1dZosY7YdnCnJc1jNGYW4,770
+asimpy/environment.py,sha256=ndjPR7W-j7FPwV7ze5Icen-xRgHKYGLNl5M2m26d4Fw,1205
+asimpy/event.py,sha256=ACYPPRGyaRgsSNB7KADgMu3PnQYLFLs7OOh70lHsEb4,1358
+asimpy/firstof.py,sha256=htwskm_5lwBVD6yb7hD8jmAypeaJJk5iUqB7cKPYWyk,1356
+asimpy/interrupt.py,sha256=tybPzsCeX7cpVL6psOUQf6egcAujV0vnJe1zDwkZWxo,406
+asimpy/process.py,sha256=IQldzjqF5CuBUccdkM3ZV5mEtEIivZx8whGeNEr2jIc,2349
+asimpy/queue.py,sha256=BFGDIle1olAbOSGc2umtl6DxVCl59twb4s658_RTChc,1514
+asimpy/resource.py,sha256=ENDY37S2vQ_3iIISq9rPCdnVP-bLW7qCX9jJZ8RlX5Q,1679
+asimpy/timeout.py,sha256=yRKJvKPITB75u25ZnE3-bk3yMC39w4bPnh9yZ_pNSes,549
+asimpy-0.3.0.dist-info/METADATA,sha256=DB3RniluV4SAMgykUwUNh7TDeZRqSXLGpcdJBr3KZAs,9315
+asimpy-0.3.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+asimpy-0.3.0.dist-info/licenses/LICENSE.md,sha256=IjTDUvBk8xdl_n50CG1Vtk4FYdrS-C3uEYrRWAoOQqQ,1066
+asimpy-0.3.0.dist-info/RECORD,,

asimpy/actions.py

@@ -1,26 +0,0 @@
-"""Awaitable actions."""
-
-from typing import Any, TYPE_CHECKING
-
-if TYPE_CHECKING:
-    from .environment import Environment
-
-
-class BaseAction:
-    """
-    Base of all internal awaitable actions. Simulation authors should not use this directly.
-    """
-
-    def __init__(self, env: "Environment"):
-        """
-        Construct a new awaitable action.
-
-        Args:
-            env: simulation environment.
-        """
-        self._env = env
-
-    def __await__(self) -> Any:
-        """Handle `await`."""
-        yield self
-        return None

asimpy/gate.py

@@ -1,57 +0,0 @@
-"""Gate that holds multiple processes until flagged."""
-
-from typing import TYPE_CHECKING
-from .actions import BaseAction
-from .process import Process
-
-if TYPE_CHECKING:
-    from .environment import Environment
-
-
-class Gate:
-    """Gate that multiple processes can wait on for simultaneous release."""
-
-    def __init__(self, env: "Environment"):
-        """
-        Construct a new gate.
-
-        Args:
-            env: simulation environment.
-        """
-        self._env = env
-        self._waiting = []
-
-    async def wait(self):
-        """Wait until gate is next opened."""
-        await _Wait(self)
-
-    async def release(self):
-        """Release all waiting processes."""
-        await _Release(self)
-
-
-# ----------------------------------------------------------------------
-
-
-class _Wait(BaseAction):
-    """Wait at the gate."""
-
-    def __init__(self, gate: Gate):
-        super().__init__(gate._env)
-        self._gate = gate
-
-    def act(self, proc: Process):
-        self._gate._waiting.append(proc)
-
-
-class _Release(BaseAction):
-    """Release processes waiting at gate."""
-
-    def __init__(self, gate: Gate):
-        super().__init__(gate._env)
-        self._gate = gate
-
-    def act(self, proc: Process):
-        while self._gate._waiting:
-            self._env.schedule(self._env.now, self._gate._waiting.pop())
-        self._env.schedule(self._env.now, proc)

asimpy-0.2.0.dist-info/METADATA

@@ -1,41 +0,0 @@
-Metadata-Version: 2.4
-Name: asimpy
-Version: 0.2.0
-Summary: A simple discrete event simulator using async/await
-Author-email: Greg Wilson <gvwilson@third-bit.com>
-Maintainer-email: Greg Wilson <gvwilson@third-bit.com>
-License-File: LICENSE.md
-Keywords: discrete event simulation,open source
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Operating System :: OS Independent
-Classifier: Programming Language :: Python :: 3
-Requires-Python: >=3.13
-Provides-Extra: dev
-Requires-Dist: build>=1.4.0; extra == 'dev'
-Requires-Dist: markdown-include>=0.8.1; extra == 'dev'
-Requires-Dist: mkdocs-awesome-pages-plugin>=2.10.1; extra == 'dev'
-Requires-Dist: mkdocs-material>=9.7.1; extra == 'dev'
-Requires-Dist: mkdocs>=1.6.1; extra == 'dev'
-Requires-Dist: mkdocstrings[python]>=1.0.0; extra == 'dev'
-Requires-Dist: ruff>=0.14.10; extra == 'dev'
-Requires-Dist: taskipy>=1.14.1; extra == 'dev'
-Requires-Dist: twine>=6.2.0; extra == 'dev'
-Requires-Dist: ty>=0.0.11; extra == 'dev'
-Description-Content-Type: text/markdown
-
-# asimpy
-
-A simple discrete event simulation framework in Python using `async`/`await`.
-
--   [Documentation][docs]
--   [Package][package]
--   [Repository][repo]
--   [Examples][examples]
-
-*Thanks to the creators of [SimPy][simpy] for inspiration.*
-
-[docs]: https://gvwilson.github.io/asimpy
-[examples]: https://gvwilson.github.io/asimpy/examples/
-[package]: https://pypi.org/project/asimpy/
-[repo]: https://github.com/gvwilson/asimpy
-[simpy]: https://simpy.readthedocs.io/

asimpy-0.2.0.dist-info/RECORD

@@ -1,12 +0,0 @@
-asimpy/__init__.py,sha256=i_T5R48aoPnE3zhHaDIWmCOmvjOb32OfmSnhhUWL37g,330
-asimpy/actions.py,sha256=G9f4Zt3Mgt1dvwOgXKbdZwmoy8Z-7pxVvre2C1J-WD0,546
-asimpy/environment.py,sha256=9KooPy0v4gERqyX7H1O7cJQyYmTA04wWT8WExrqHAGI,3098
-asimpy/gate.py,sha256=MFepFLcb8TNhzbaRAF5jJFFbprbRB-Q5phf1uMdl3LA,1381
-asimpy/interrupt.py,sha256=G925y6jHB6b6y30sbq4e3jjutZDIW7Dwg9YY0mgf24Y,572
-asimpy/process.py,sha256=6LRQRHzHI8PVt_AtckSQgsAPqv65BlUNJ8xOOVx9bXs,1550
-asimpy/queue.py,sha256=MVCEsDU5a2774Y5xKD0HlTZAnZwpBDeThbjFEXpkd8s,3287
-asimpy/resource.py,sha256=O18VJARLIZHbvntOxtTfYefGO5Zibz3EcsKWretIlxE,2107
-asimpy-0.2.0.dist-info/METADATA,sha256=XxrAW1lY1xpFpn5xPF00--rFEe8pZQGcOC8WjjVaTWU,1495
-asimpy-0.2.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-asimpy-0.2.0.dist-info/licenses/LICENSE.md,sha256=IjTDUvBk8xdl_n50CG1Vtk4FYdrS-C3uEYrRWAoOQqQ,1066
-asimpy-0.2.0.dist-info/RECORD,,