asimpy 0.1.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
+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,87 +1,64 @@
-"""Queues."""
+"""FIFO and priority queues."""
 
-from abc import ABC, abstractmethod
-from .actions import BaseAction
+import heapq
+from typing import TYPE_CHECKING, Any
+from .event import Event
 
+if TYPE_CHECKING:
+    from .environment import Environment
 
-class BaseQueue(ABC):
-    def __init__(self, env):
-        self._env = env
-        self._gets = []
-
-    async def get(self):
-        return await _Get(self)
-
-    async def put(self, obj):
-        await _Put(self, obj)
-
-    @abstractmethod
-    def _dequeue(self):
-        pass
+class Queue:
+    """FIFO queue."""
 
-    @abstractmethod
-    def _empty(self):
-        pass
+    def __init__(self, env: "Environment"):
+        """
+        Construct queue.
 
-    @abstractmethod
-    def _enqueue(self, obj):
-        pass
-
-
-class Queue(BaseQueue):
-    def __init__(self, env):
-        super().__init__(env)
+        Args:
+            env: simulation environment.
+        """
+        self._env = env
         self._items = []
+        self._getters = []
 
-    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)})"
-
-
-# ----------------------------------------------------------------------
-
-
-class _Get(BaseAction):
-    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)
+    async def get(self):
+        """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):
+        """
+        Add one item to the queue.
+
+        Args:
+            item: to add to the queue.
+        """
+        if self._getters:
+            evt = self._getters.pop(0)
+            evt.succeed(item)
         else:
-            self._item = self._queue._dequeue()
-            self._env.schedule(self._env.now, proc)
-
-    def __await__(self):
-        yield self
-        return self._item
-
+            self._items.append(item)
 
-class _Put(BaseAction):
-    def __init__(self, queue, obj):
-        super().__init__(queue._env)
-        self._queue = queue
-        self.obj = obj
 
-    def act(self, proc):
-        self._queue._enqueue(self.obj)
+class PriorityQueue(Queue):
+    """Ordered queue."""
 
-        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)
+    async def put(self, item: Any):
+        """
+        Add one item to the queue.
 
-        self._env.schedule(self._env.now, proc)
+        Args:
+            item: comparable item to add to queue.
+        """
+        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.1.0.dist-info/METADATA

@@ -1,27 +0,0 @@
-Metadata-Version: 2.4
-Name: asimpy
-Version: 0.1.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-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`.

asimpy-0.1.0.dist-info/RECORD

@@ -1,12 +0,0 @@
-asimpy/__init__.py,sha256=BJoqSPhuG6zSHkEqYh8OBZPrqbAn52EYg9Hjf236xRk,298
-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=qQOmQfuZ_MBS5aRax7pEuWrR6swlRmI-MU0iiWD6s-0,1938
-asimpy/resource.py,sha256=O18VJARLIZHbvntOxtTfYefGO5Zibz3EcsKWretIlxE,2107
-asimpy-0.1.0.dist-info/METADATA,sha256=oArpUAofvClqpvODhBOE_DyY2vyPWPZikHOTSQrA8MY,1044
-asimpy-0.1.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-asimpy-0.1.0.dist-info/licenses/LICENSE.md,sha256=IjTDUvBk8xdl_n50CG1Vtk4FYdrS-C3uEYrRWAoOQqQ,1066
-asimpy-0.1.0.dist-info/RECORD,,