asimpy 0.2.0__tar.gz → 0.4.0__tar.gz

asimpy-0.4.0/PKG-INFO

@@ -0,0 +1,241 @@
+Metadata-Version: 2.4
+Name: asimpy
+Version: 0.4.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.4.0/README.md

@@ -0,0 +1,216 @@
+# 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/