asimpy 0.5.0__py3-none-any.whl → 0.5.1__py3-none-any.whl

asimpy/allof.py

@@ -45,5 +45,5 @@ class _AllOfWatcher:
         self.parent = parent
         self.key = key
 
-    def _resume(self, value):
+    def resume(self, value):
         self.parent._child_done(self.key, value)

asimpy/environment.py

@@ -12,15 +12,17 @@ from .timeout import Timeout
 class Environment:
     """Simulation environment."""
 
-    def __init__(self, logging=False):
+    def __init__(self):
         self._now = 0
-        self._logging = logging
         self._pending = []
 
     @property
     def now(self):
         return self._now
 
+    def immediate(self, callback):
+        self.schedule(self._now, callback)
+
     def schedule(self, time, callback):
         heapq.heappush(self._pending, _Pending(time, callback))
 
@@ -36,9 +38,6 @@ class Environment:
             if (result is not NO_TIME) and (pending.time > self._now):
                 self._now = pending.time
 
-    def _immediate(self, callback):
-        self.schedule(self._now, callback)
-
     def __str__(self):
         return f"Env(t={self._now})"
 

asimpy/event.py

@@ -39,7 +39,7 @@ class Event:
         self._triggered = True
         self._value = value
         for proc in self._waiters:
-            proc._resume(value)
+            proc.resume(value)
         self._waiters.clear()
 
     def cancel(self):
@@ -53,7 +53,7 @@ class Event:
 
     def _add_waiter(self, proc):
         if self._triggered:
-            proc._resume(self._value)
+            proc.resume(self._value)
         elif not self._cancelled:
             self._waiters.append(proc)
 

asimpy/firstof.py

@@ -37,6 +37,7 @@ class FirstOf(Event):
     def _child_done(self, key, value, winner):
         if self._done:
             return
+
         self._done = True
 
         for evt in self._events.values():
@@ -52,5 +53,5 @@ class _FirstOfWatcher:
         self.key = key
         self.evt = evt
 
-    def _resume(self, value):
+    def resume(self, value):
         self.parent._child_done(self.key, value, self.evt)

asimpy/interrupt.py

@@ -17,4 +17,5 @@ class Interrupt(Exception):
         self.cause = cause
 
     def __str__(self):
+        """Represent interrupt as string."""
         return f"Interrupt({self.cause})"

asimpy/process.py

@@ -23,9 +23,11 @@ class Process(ABC):
         self._env = env
         self._done = False
         self._interrupt = None
+
         self.init(*args, **kwargs)
+
         self._coro = self.run()
-        self._env._immediate(self._loop)
+        self._env.immediate(self._loop)
 
     def init(self, *args: Any, **kwargs: Any):
         """
@@ -65,7 +67,7 @@ class Process(ABC):
         """
         if not self._done:
             self._interrupt = Interrupt(cause)
-            self._env._immediate(self._loop)
+            self._env.immediate(self._loop)
 
     def _loop(self, value=None):
         if self._done:
@@ -78,6 +80,7 @@ class Process(ABC):
                 exc = self._interrupt
                 self._interrupt = None
                 yielded = self._coro.throw(exc)
+
             yielded._add_waiter(self)
 
         except StopIteration:
@@ -87,6 +90,6 @@ class Process(ABC):
             self._done = True
             raise exc
 
-    def _resume(self, value=None):
+    def resume(self, value=None):
         if not self._done:
-            self._env._immediate(lambda: self._loop(value))
+            self._env.immediate(lambda: self._loop(value))

asimpy/resource.py

@@ -39,27 +39,25 @@ class Resource:
             evt.succeed()
 
     async def _acquire_available(self):
-        self._count += 1
-        evt = Event(self._env)
-
         def cancel():
             self._count -= 1
 
+        self._count += 1
+        evt = Event(self._env)
         evt._on_cancel = cancel
-        self._env._immediate(evt.succeed)
+        self._env.immediate(evt.succeed)
         await evt
 
     async def _acquire_unavailable(self):
         evt = Event(self._env)
-        self._waiters.append(evt)
 
         def cancel():
             if evt in self._waiters:
                 self._waiters.remove(evt)
 
+        self._waiters.append(evt)
         evt._on_cancel = cancel
         await evt
-
         self._count += 1
 
     async def __aenter__(self):

asimpy/simqueue.py

@@ -25,15 +25,15 @@ class Queue:
     async def get(self):
         """Get one item from the queue."""
         if self._items:
-            item = self._items.pop(0)
+            item = self._get_item()
             evt = Event(self._env)
-            self._env._immediate(lambda: evt.succeed(item))
             evt._on_cancel = lambda: self._items.insert(0, item)
+            self._env.immediate(lambda: evt.succeed(item))
+            return await evt
+        else:
+            evt = Event(self._env)
+            self._getters.append(evt)
             return await evt
-
-        evt = Event(self._env)
-        self._getters.append(evt)
-        return await evt
 
     async def put(self, item: Any):
         """
@@ -46,33 +46,20 @@ class Queue:
             evt = self._getters.pop(0)
             evt.succeed(item)
         else:
-            self._items.append(item)
+            self._put_item(item)
 
+    def _get_item(self):
+        return self._items.pop(0)
 
-class PriorityQueue(Queue):
-    """Ordered queue."""
+    def _put_item(self, item):
+        self._items.append(item)
 
-    async def get(self):
-        """Get highest priority item from the queue."""
-        if self._items:
-            item = heapq.heappop(self._items)
-            evt = Event(self._env)
-            self._env._immediate(lambda: evt.succeed(item))
-            evt._on_cancel = lambda: heapq.heappush(self._items, item)
-            return await evt
 
-        evt = Event(self._env)
-        self._getters.append(evt)
-        return await evt
+class PriorityQueue(Queue):
+    """Ordered queue."""
 
-    async def put(self, item: Any):
-        """
-        Add one item to the queue.
+    def _get_item(self):
+        return heapq.heappop(self._items)
 
-        Args:
-            item: comparable item to add to queue.
-        """
+    def _put_item(self, item):
         heapq.heappush(self._items, item)
-        if self._getters:
-            evt = self._getters.pop(0)
-            evt.succeed(heapq.heappop(self._items))

asimpy-0.5.1.dist-info/METADATA

@@ -0,0 +1,484 @@
+Metadata-Version: 2.4
+Name: asimpy
+Version: 0.5.1
+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.12
+Description-Content-Type: text/markdown
+
+# asimpy
+
+A simple discrete event simulation framework in Python using `async`/`await`.
+
+-   [Documentation][asimpy]
+-   [Package][package]
+-   [Repository][repo]
+
+*Thanks to the creators of [SimPy][simpy] for inspiration.*
+
+## Core Concepts
+
+Discrete event simulation (DES) simulates systems in which events occur at discrete points in time.
+The simulation maintains a virtual clock and executes events in chronological order.
+Unlike real-time systems,
+the simulation jumps directly from one event time to the next,
+skipping empty intervals.
+(Time steps are often referred to as "ticks".)
+
+## Async/Await
+
+Python's `async`/`await` syntax enables cooperative multitasking without threads.
+Functions defined as `async def` return coroutine objects when called.
+These coroutines can be paused at `await` points and later resumed.
+More specifically,
+when a coroutine executes `value = await expr`, it:
+
+1.  yields the awaited object `expr` to its caller;
+2.  suspends execution at that point;
+3.  resumes later when `send(value)` is called on it; an thend
+4.  returns the value passed to `send()` as the result of the `await` expression
+    inside the resumed coroutine.
+
+[asimpy][asimpy] uses this mechanism to pause and resume coroutines to simulate simultaneously execution.
+This is similar to the `yield`-based mechanism used in [SimPy][simpy].
+
+## `Environment`: Process and Event Management
+
+The `Environment` class maintains the simulation state:
+
+-  `_now` is the current simulated time.
+-  `_pending` is a priority queue of callbacks waiting to be run in order of increasing time
+    (so that the next one to run is at the front of the queue).
+
+`Environment.schedule(time, callback)` adds a callback to the queue.
+The `_Pending` dataclass used to store it includes a serial number
+to ensure deterministic ordering when multiple events occur at the same time.
+
+`Environment.run()` implements the main simulation loop:
+
+1.  Extract the next pending event from the priority queue.
+2.  If an `until` parameter is specified and the event time exceeds it, stop.
+3.  Execute the callback.
+4.  If the callback doesn't return `NO_TIME` and the event time is greater than the current simulated time,
+    advance the clock.
+
+The `NO_TIME` sentinel prevents time from advancing mistakenly when events are canceled.
+This is explained in detail later.
+
+## `Event`: the Synchronization Primitive
+
+The `Event` class represents an action that will complete in the future.
+It has four members:
+
+-  `_triggered` indicates whether the event has completed.
+-  `_cancelled` indicaets whether the event was cancelled.
+-  `_value` is the event's result value.
+-  `_waiters` is a list of processes waiting for this event to occur.
+
+When `Event.succeed(value)` is called, it:
+
+1.  sets `_triggered` to `True` to show that the event has completed;
+2.  stores the value for later retrieval;
+3.  calls `resume(value)` on all waiting processes; and
+3.  clears the list of waiting processes.
+
+The internal `Event._add_waiter(proc)` method handles three cases:
+
+1.  If the event has already completed (i.e., if `_triggered` is `True`),
+    it immediately calls `proc.resume(value)`.
+2.  If the event has been canceled,
+    it does nothing.
+2.  Otherwise, it adds `proc` to the list of waiting processes.
+
+Finally,
+`Event` implements `__await__()`,
+which Python calls automatically when it executes `await evt`.
+`Event.__await__` yields `self` so that the awaiting process gets the event back.
+
+## `Process`: Active Entities
+
+`Process` is the base class for simulation processes.
+(Unlike [SimPy][simpy], [asimpy][asimpy] uses a class rather than bare coroutines.)
+When a `Process` is constructed, it:
+
+1.  store a reference to the simulation environment;
+2.  calls `init()` for subclass-specific setup
+    (the default implementation of this method does nothing);
+3.  create a coroutine by calling `run()`; and
+4.  schedules immediate execution of `Process._loop()`.
+
+The `_loop()` method drives coroutine execution:
+
+1.  If an interrupt is pending, throw it into the coroutine via `throw()`.
+2.  Otherwise, send the value into the coroutine via `send()`.
+3.  Receive the yielded event.
+4.  Register this process as a waiter on that event
+
+When `StopIteration` is raised by the coroutine,
+the process is marked as done.
+If any other exception occurs,
+the process is marked as done and the exception is re-raised.
+
+**Note:** The word "process" can be confusing.
+These are *not* operating system processes with their own memory and permissions.
+
+### A Note on Scheduling
+
+When an event completes it calls `proc.resume(value)` to schedules another iteration of `_loop()`
+with the provided value.
+This continues the coroutine past its `await` point.
+
+### A Note on Interrupts
+
+The interrupt mechanism sets `_interrupt` and schedules immediate execution of the process.
+The next `_loop()` iteration throws the interrupt into the coroutine,
+where it can be caught with `try`/`except`.
+This is a bit clumsy,
+but is the only way to inject exceptions into running coroutines.
+
+**Note:**
+A process can *only* be interrupted at an `await` point.
+Exceptions *cannot* be raised from the outside at arbitrary points.
+
+## `Timeout`: Waiting Until
+
+A `Timeout` object schedules a callback at a future time.
+`Timeout._fire()` method returns `NO_TIME` if the timeout has ben canceled,
+which prevents canceled timeouts from accidentally advancing the simulation time.
+Otherwise,
+`Timeout._fire()` calls `succeed()` to trigger the event.
+
+## `Queue` and `PriorityQueue`: Exchanging Data
+
+`Queue` enables processes to exchange data.
+It has two members:
+
+-  `_items` is a list of items being passed between processes.
+-  `_getters` is a list of processes waiting for items.
+
+The invariant for `Queue` is that one or the other list must be empty,
+i.e.,
+if there are processes waiting then there aren't any items to take,
+while if there are items waiting to be taken there aren't any waiting processes.
+
+`Queue.put(item)` immediately calls `evt.succeed(item)` if a process is waiting
+to pass that item to the waiting process
+(which is stored in the event).
+Otherwise,
+the item is appended to `queue._items`.
+
+`Queue.get()` is a bit more complicated.
+If the queue has items,
+`queue.get()` creates an event that immediately succeeds with the first item.
+If the queue is empty,
+the call creates an event and adds the caller to the list of processes waiting to get items.
+
+The complication is that if there *is* an item to get,
+`queue.get()` sets the `_on_cancel` callback of the event to handles cancellation
+by returning the item taken to the front of the queue.
+
+`PriorityQueue` uses `heapq` operations to maintain ordering,
+which means items must be comparable (i.e., must implement `__lt__`).
+`get()` pops the minimum element;
+`put()` pushes onto the heap and potentially satisfies a waiting getter.
+
+## `Resource`: Capacity-Limited Sharing
+
+The `Resource` class simulates a shared resource with limited capacity.
+It has three members:
+
+-  `capacity` is the maximum number of concurrent users.
+-  `_count` is the current number of users.
+-  `_waiters` is a list of processes waiting for the resource to be available.
+
+If the resource is below capacity when `res.acquire()` is called,
+it calls increments the internal count and immediately succeeds.
+Otherwise,
+it adds the caller to the list of waiting processes.
+Similarly,
+`res.release()` decrements the count and then checks the list of waiting processes.
+If there are any,
+it calls `evt.succeed()` for the event representing the first waiting process.
+
+`Resource.acquire` depends on internal methods
+`Resource._acquire_available` and `Resource._acquire_unavailable`,
+both of which set the `_on_cancel` callback of the event they create
+to restore the counter to its original state
+or remove the event marking a waiting process.
+
+Finally,
+the context manager protocol methods `__aenter__` and `__aexit__`
+allows processes to use `async with res`
+to acquire and release a resource in a block.
+
+## `Barrier`: Synchronizing Multiple Processes
+
+A `Barrier` holds multiple processes until they are explicitly released,
+i.e.,
+it allows the simulation to synchronize multiple processes.
+
+-  `wait()` creates an event and adds it to the list of waiters.
+-  `release()` calls `succeed()` on all waiting events and clears the list.
+
+## AllOf: Waiting for Multiple Events
+
+`AllOf` and `FirstOf` are the most complicated parts of [asimpy][asimpy],
+and the reason that parts such as cancellation management exist.
+`AllOf` succeeds when all provided events complete.
+It:
+
+1.  converts each input to an event (discussed later);
+2.  registers an `_AllOfWatcher` on each of those events;
+3.  accumulates results in `_results` dictionary; and
+4.  succeeds when all results collected.
+
+Each watcher calls `_child_done(key, value)` when its event completes.
+This stores the result and checks if all events are done.
+
+### A Note on Interface
+
+A process calls `AllOf` like this:
+
+```python
+await AllOf(self._env, a=self.timeout(5), b=self.timeout(10))
+```
+
+The eventual result is a dictionary in which
+the name of the events are keys and the results of the events are values;
+in this case,
+the keys will be `"a"` and `"b"`.
+This gives callers an easy way to keep track of events,
+though it *doesn't* support waiting on all events in a list.
+
+`AllOf`'s interface would be tidier
+if it didn't require the simulation environment as its first argument.
+However,
+removing it made the implementation significantly more complicated.
+
+## FirstOf: Racing Multiple Events
+
+`FirstOf` succeeds as soon as *any* of the provided events succeeds,
+and then cancels all of the other events.
+To do this, it:
+
+1.  converts each input to an event;
+2.  registers a `_FirstOfWatcher` on each;
+3.  on first completion, cancels all other events; and
+4.  succeeds with a `(key, value)` to identify the winning event.
+
+`FirstOf`'s `_done` flag prevents multiple completions.
+When `_child_done()` is called,
+it checks this flag,
+cancels other waiters,
+and succeeds.
+
+## Control Flow Example
+
+Consider a process that waits 5 ticks:
+
+```python
+class Waiter(Process):
+    async def run(self):
+        await self.timeout(5)
+        print("done")
+```
+
+When it executes:
+
+1.  Construction calls `__init__()`,
+    which creates a coroutine by calling `run()`
+    and immediately schedules `_loop()`.
+1.  The first `_loop()` calls `send(None)` to the coroutine,
+    which executes to the `await`
+    and yields a `Timeout` event.
+1.  `_loop()` registers this process as a waiter on the timeout event.
+1.  The timeout schedules a callback to run at time 5.
+1.  The environment takes the event from its `_pending` queue and updates the simulated time to 5.
+1.  The environment runs the callback, which calls `succeed()` on the timeout.
+1.  The timeout calls `resume()` on the process.
+1.  `resume()` schedules an immediate call to `_loop()` with the value `None`.
+1.  `_loop()` calls `send(None)` on the coroutine,
+    causing it to advance past the `await`.
+1.  The process prints `"done"` and raises a `StopIteration` exception.
+1.  The process is marked as done.
+1.  Since there are no other events in the pending queue, the environment ends the simulation.
+
+## A Note on Coroutine Adaptation
+
+The `ensure_event()` function handles both `Event` objects and bare coroutines.
+For coroutines, it creates a `_Runner` process that `await`s the coroutine
+and then calls `succeed()` on an event with the result.
+This allows `AllOf` and `FirstOf` to accept both events and coroutines.
+
+`AllOf` and `FirstOf` must accept coroutines in addition to events
+because of the way Python's `async`/`await` syntax works
+and what users naturally write.
+In the statement:
+
+```python
+await AllOf(env, a=queue.get(), b=resource.acquire())
+```
+
+the expressions `queue.get()` and `resource.acquire()` are calls to `async def` functions.
+In Python,
+calling an async function *does not execute it.
+Instead, it returns a coroutine object.
+If `AllOf` couldn't accept coroutines directly,
+this code would fail because it expects `Event`s.
+
+If `AllOf` only accepted events, users would need to write:
+
+```python
+# Manually create events
+evt_a = Event(env)
+evt_b = Event(env)
+
+# Manually create runners
+_Runner(env, evt_a, queue.get())
+_Runner(env, evt_b, resource.acquire())
+
+# Now use the events
+await AllOf(env, a=evt_a, b=evt_b)
+```
+
+This is verbose and exposes internal implementation details.
+
+## Things I Learned the Hard Way
+
+### Requirements for Correctness
+
+`Event` waiter notification must occur before clearing the list.
+:   If the list were cleared first, waiters couldn't be resumed.
+
+The `_Pending` serial number is necessary.
+:   Heap operations require total ordering.
+    Without this value,
+    events occurring at the same time wouldn't be deterministically ordered,
+    which would make simulations irreproducible.
+
+Cancelled events must not advance time.
+:   The `NO_TIME` sentinel prevents this.
+    Without it,
+    cancelled timeouts create gaps in the simulation timeline.
+
+Process interrupt checking must occur before coroutine sends.
+:   This ensures interrupts are handled immediately
+    rather than being delayed until the next event.
+
+Queue cancellation handlers must remove items or waiters.
+:   Without this,
+    cancelled `get`s leave processes in the waiters list indefinitely,
+    and cancelled items disappear from the queue.
+
+Resource cancellation handlers must adjust state.
+:   Without them,
+    cancelled `acquire`s permanently reduce available capacity or leave ghost waiters.
+
+`AllOf` must track completion.
+:   Without checking if all events are done, it succeeds prematurely.
+
+`FirstOf` must cancel losing events.
+:   Otherwise,
+    those events remain active and can run later.
+
+### Why Not Just Use Coroutines?
+
+[SimPy][simpy] uses bare coroutines.
+[asimpy][asimpy] uses `Event` as the internal primitive for several reasons.
+
+Events can be triggered externally.
+:   A `Timeout` schedules a callback that later calls `succeed()`.
+    A coroutine cannot be "succeeded" from outside: it must run to completion.
+
+Events support multiple waiters.
+:   Multiple processes can `await` the same event.
+    A coroutine can only be awaited once.
+
+Events decouple triggering from waiting.
+:   The thing that creates an event (like `Timeout.__init__()`)
+    is separate from the thing that waits for it.
+    With coroutines, creation and execution are more tightly coupled.
+
+### `Event.__await__`
+
+`Event.__await__` is defined as:
+
+```python
+def __await__(self):
+    value = yield self
+    return value
+```
+
+This appears redundant but each part serves a specific purpose in the coroutine protocol.
+
+When a coroutine executes `await event`,
+Python calls `event.__await__()`,
+which must return an iterator.
+The `yield self` statement:
+
+1.  makes `__await__()` a generator function,
+    so it returns a generator (which is a kind of iterator).
+2.  Yields the `Event` object itself up to the `Process`'s `_loop()` method.
+
+The `Process` needs the `Event` object so it can call `_add_waiter()` on it:
+
+```python
+def _loop(self, value=None):
+    # ...
+    yielded = self._coro.send(value)  # This receives the Event
+    yielded._add_waiter(self)         # Register as waiter
+```
+
+Without `yield self`, the `Process` wouldn't know which event to register on.
+
+The `value = yield self` statement captures what gets sent back into the generator.
+When the event completes:
+
+1.  `Event` calls `proc.resume(value)` .
+2.  `Process` calls `self._loop(value)`.
+3.  `_loop` calls `self._coro.send(value)`.
+4.  This resumes the generator, making `yield self` return `value`.
+
+The assignment therefore captures the event's result value.
+
+### Why Return Value
+
+The `return value` statement makes that result available to the code that wrote `await event`.
+When a generator returns (via `return` or falling off the end)
+Python raises `StopIteration` with the return value as an attribute.
+The `async`/`await` machinery extracts this and provides it as the result of the `await` expression,
+So when a user writes:
+
+```python
+result = await queue.get()
+```
+
+the flow is:
+
+1.  `queue.get()` creates and returns an `Event`.
+1.  `await` calls `Event.__await__()` which yields the `Event` object.
+1.  `Process._loop()` receives the `Event` and registers itself as a waiter.
+1.  Later, the queue calls `event.succeed(item)`.
+1.  `Event` calls `process.resume(item)`.
+1.  `Process` calls `coro.send(item)`.
+1.  The generator resumes, and `yield self` evaluates to `item`.
+1.  The generator executes `return item`.
+1.  `StopIteration(item)` is raised.
+1.  The `async` machinery catches this and makes `await` evaluate to `item`.
+
+None of the simpler alternatives would work:
+
+- `yield self` alone (no return): the await expression would evaluate to `None`.
+- `return self` (no yield): not a generator, so it violates the iterator protocol.
+- `yield value` then `return value`: the first yield wouldn't provide the `Event` object to the `Process`.
+
+[asimpy]: https://asimpy.readthedocs.io/
+[package]: https://pypi.org/project/asimpy/
+[repo]: https://github.com/gvwilson/asimpy
+[simpy]: https://simpy.readthedocs.io/

asimpy-0.5.1.dist-info/RECORD

@@ -0,0 +1,16 @@
+asimpy/__init__.py,sha256=c01u2z29W688jAccd6OKnON132IueBKn31JrcA5wNSk,490
+asimpy/_adapt.py,sha256=-rUIvJMneEDdxdiMImwXYfMChsqdQwWoyHVsDCsxRKI,521
+asimpy/allof.py,sha256=HMn-w1tNM4ej7IO5oj0icOFPxDzWL6qF8gIsxpxUHck,1210
+asimpy/barrier.py,sha256=evubm6H_93qi9vBogqrNLg1dZosY7YdnCnJc1jNGYW4,770
+asimpy/environment.py,sha256=PhzY4OILYSNnm0lMSZPZKaGA8BcQwe3m6y2Wl4Z8egs,1303
+asimpy/event.py,sha256=2itFcYmgxiV2raGhoRf76mbNROTYSAPpUX33ofOPjpU,1435
+asimpy/firstof.py,sha256=H7W1rsWjRLmosFAlabMunkXjqpsEfmlbTbdk5zwRa_Q,1356
+asimpy/interrupt.py,sha256=TmirtrO9jikyQBAO8791kpP4Y8tLd3EpQ5Z9ZDadFzE,451
+asimpy/process.py,sha256=IVxLMTr7EWVWZg8RtAOkW4fAL9f30dIfq7ba20zwO1c,2348
+asimpy/resource.py,sha256=a6Z3pWwGZ-JOIvBaJmpYJvgCNXtMuGce3uIKhEQDnsQ,1677
+asimpy/simqueue.py,sha256=W3AV8YGuK8FrDQBI7EpuH49Be_GseM8A9xVMZFAzYsw,1479
+asimpy/timeout.py,sha256=75OqbpLeepJ5UdSN6F6JZ0ctlr53jpuilaI7Wxi9XP8,686
+asimpy-0.5.1.dist-info/METADATA,sha256=sHuInjnJLTEedEjnrlEbPhKsAIY-aaeBjxX1qYIAbko,17637
+asimpy-0.5.1.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+asimpy-0.5.1.dist-info/licenses/LICENSE.md,sha256=IjTDUvBk8xdl_n50CG1Vtk4FYdrS-C3uEYrRWAoOQqQ,1066
+asimpy-0.5.1.dist-info/RECORD,,

asimpy-0.5.0.dist-info/METADATA

@@ -1,228 +0,0 @@
-Metadata-Version: 2.4
-Name: asimpy
-Version: 0.5.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.12
-Description-Content-Type: text/markdown
-
-# asimpy
-
-A simple discrete event simulation framework in Python using `async`/`await`.
-
--   [Documentation][docs]
--   [Package][package]
--   [Repository][repo]
-
-*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://asimpy.readthedocs.io/
-[package]: https://pypi.org/project/asimpy/
-[repo]: https://github.com/gvwilson/asimpy
-[simpy]: https://simpy.readthedocs.io/

asimpy-0.5.0.dist-info/RECORD

@@ -1,16 +0,0 @@
-asimpy/__init__.py,sha256=c01u2z29W688jAccd6OKnON132IueBKn31JrcA5wNSk,490
-asimpy/_adapt.py,sha256=-rUIvJMneEDdxdiMImwXYfMChsqdQwWoyHVsDCsxRKI,521
-asimpy/allof.py,sha256=artqJqBHUaHh8oOk3a3tpqIlt5sJzGW9VEJ2-YkdECU,1211
-asimpy/barrier.py,sha256=evubm6H_93qi9vBogqrNLg1dZosY7YdnCnJc1jNGYW4,770
-asimpy/environment.py,sha256=EEHkW6vuQJF9koY_DrNVXQ9bUj4GQDKRWkGCqvDx9U0,1351
-asimpy/event.py,sha256=gS4_PHydP6MUNaEG2o0L8QK67Y1R_9dybJq4BEQXsu8,1437
-asimpy/firstof.py,sha256=htwskm_5lwBVD6yb7hD8jmAypeaJJk5iUqB7cKPYWyk,1356
-asimpy/interrupt.py,sha256=tybPzsCeX7cpVL6psOUQf6egcAujV0vnJe1zDwkZWxo,406
-asimpy/process.py,sha256=IQldzjqF5CuBUccdkM3ZV5mEtEIivZx8whGeNEr2jIc,2349
-asimpy/resource.py,sha256=Ml8E71FdJ61Sy6dcoXyQkb0SXLv6xRBkI7Rkriyu438,1680
-asimpy/simqueue.py,sha256=B826YjNKHXkdkRRYPijQETkF9w84hoWNT4an_YQcalw,1953
-asimpy/timeout.py,sha256=75OqbpLeepJ5UdSN6F6JZ0ctlr53jpuilaI7Wxi9XP8,686
-asimpy-0.5.0.dist-info/METADATA,sha256=gsgdx4ouMqpNgHBGLaKfC5ygBWEjNgYlv8IwmCRohKc,8709
-asimpy-0.5.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-asimpy-0.5.0.dist-info/licenses/LICENSE.md,sha256=IjTDUvBk8xdl_n50CG1Vtk4FYdrS-C3uEYrRWAoOQqQ,1066
-asimpy-0.5.0.dist-info/RECORD,,