eventdispatch 0.2.29__tar.gz → 0.2.30__tar.gz

{eventdispatch-0.2.29/eventdispatch.egg-info → eventdispatch-0.2.30}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: eventdispatch
-Version: 0.2.29
+Version: 0.2.30
 Summary: Event Dispatch: discrete time synchronization
 Home-page: http://github.com/cyan-at/python-eventdispatch
 Author: Charlie Yan

{eventdispatch-0.2.29 → eventdispatch-0.2.30}/eventdispatch/common1.py

@@ -31,6 +31,7 @@ if sys.version_info.major == 2:
     makedirs_wrapper = python2_makedirs_wrapper
 
 class bcolors:
+    '''ANSI color constants, for colored logs'''
     # https://godoc.org/github.com/whitedevops/colors
     DEFAULT = "\033[39m"
     BLACK = "\033[30m"
@@ -80,6 +81,7 @@ def nonempty_queue_exists(
     blackboard,
     admissible_nonempty_keys,
     verbose = False):
+    '''True if any *_queue on the blackboard, outside the admissible set, is nonempty'''
     for k in blackboard.keys():
         if k[-6:] == "_queue":
             mutex_k = k[:-6] + "_mutex"
@@ -109,6 +111,7 @@ def wrap_with_prints(pre_msg, post_msg):
     return decorator
 
 def replace_with_func(other_func):
+    '''decorator: swap the wrapped function for other_func'''
     def decorator(func):
         def wrapper(*args, **kwargs):
             other_func(*args, **kwargs)
@@ -116,6 +119,12 @@ def replace_with_func(other_func):
     return decorator
 
 class CommonEvent(Event):
+    '''
+    an Event with the conventions BlackboardQueueCVED expects:
+    the constructor's first arg after event_id is the blackboard,
+    and deserialize() (below) is how a queue item becomes one.
+    log / internal_log print in debug_color.
+    '''
     debug_color = bcolors.LIGHTCYAN
 
     def __init__(self, event_id, *args, **kwargs):
@@ -139,6 +148,7 @@ class CommonEvent(Event):
 
     @staticmethod
     def deserialize(ed, blackboard, *args, **kwargs):
+        '''[class name, *tokens] -> ((event_id, blackboard), tokens)'''
         tokens = args[0]
         # ed.log("TOKENS! {}".format(tokens))
         if len(tokens) < 1:
@@ -150,6 +160,12 @@ TIMERWAIT_TIMEOUT = -1
 TIMERWAIT_BAILED = 1
 
 class TimerWait(CommonEvent):
+    '''
+    sleeps args[0] seconds on its own thread; on timeout, finish
+    enqueues the pending events (a timed CSRelease). An actor can
+    set the blackboard status to TIMERWAIT_BAILED to make the
+    finish a noop instead.
+    '''
     debug_color = bcolors.CYAN
 
     def get_pending(self, args):
@@ -177,7 +193,7 @@ class TimerWait(CommonEvent):
         self.log("TimerWait sleeping for {} to CSRelease {}".format(
             args[0], args[1]))
 
-        self.blackboard[self.k]['timer'] .wait(args[0])
+        self.blackboard[self.k]['timer'].wait(args[0])
 
     def finish(self, event_dispatch, *args, **kwargs):
         if self.blackboard[self.k]['status'] == TIMERWAIT_TIMEOUT:
@@ -193,11 +209,23 @@ class TimerWait(CommonEvent):
             self.blackboard[event_dispatch.cv_name].notify(1)
             self.blackboard[event_dispatch.cv_name].release()
 
-            self.blackboard.pop(self.k)
         elif self.blackboard[self.k]['status'] == TIMERWAIT_BAILED:
             self.log("TimerWait bailed! noop")
 
+        self.blackboard.pop(self.k)
+
 class BlackboardQueueCVED(EventDispatch):
+    '''
+    a buffer-and-drain dispatch: producers append serialized
+    [class name, *args] items to <name>_queue on the blackboard
+    and notify <name>_cv; run() (a thread target) drains the
+    queue completely each wake, deserializing and dispatching
+    every item.
+
+    subclass hooks: prior_cb / post_cb around each drain.
+    do_dispatch is the funnel from the queue to dispatch().
+    event ids cycle % 30000; release_event_id is a no-op here.
+    '''
     def __init__(self, blackboard, name):
         super(BlackboardQueueCVED, self).__init__(
             blackboard, name + "_dispatch")
@@ -221,6 +249,7 @@ class BlackboardQueueCVED(EventDispatch):
             len(blackboard[self.queue_name])))
 
     def register_blackboard_assets(self, blackboard, name):
+        '''create (if absent) <name>_hb / _mutex / _cv / _queue on the blackboard'''
         self.name = name
 
         self.hb_key = name + "_hb"
@@ -269,6 +298,9 @@ class BlackboardQueueCVED(EventDispatch):
         stubbed out to support CSBQCVED
 
         avoid overriding this
+
+        deserialize one queue item and dispatch it;
+        True on success, False (logged) on any failure
         '''
 
         # s (serialized_event) expected to be
@@ -300,6 +332,12 @@ class BlackboardQueueCVED(EventDispatch):
         prefix, # expected, str
         empty_cv_name = None, # expected, str
         debug_color = None):
+        '''
+        thread target: wait on the cv, drain the queue
+        (prior_cb, do_dispatch each item, post_cb), notify
+        empty_cv_name when drained. Exits when <name>_hb goes
+        False and the cv is notified.
+        '''
         assert(blackboard is not None)
 
         if (debug_color is not None):

{eventdispatch-0.2.29 → eventdispatch-0.2.30}/eventdispatch/composite_semaphore.py

@@ -9,26 +9,19 @@ from .common1 import *
 # from core import *
 # from common1 import *
 
-'''
-a thread-safe data structure
-
-on the left ('releasing/left')
-    a set that you 'tick' down
-    but resetting it takes O(1) complexity
-
-    the set is also dynamic:
-        when the set is completely full
-        you can change its values / keys
+class CompositeSemaphore(object):
+    '''
+    a thread-safe semaphore with named lefts and many rights
 
-        once it is partially tick'd
-        this is forbidden
+    left: a dynamic set of keys. release(k) ticks one key down;
+    when every key has been ticked in the current round, all
+    waiting rights are released and the round resets (O(1)).
+    Keys can be added / cleared between rounds, not mid-round.
 
-on the right ('acquiring/right')
-    a dynamics set of callbacks to fire
-    it is free-form here
-    per free-form thing, release underlying(s) semaphore
-'''
-class CompositeSemaphore(object):
+    right: any number of acquirers, each with its own semaphore;
+    before releasing it, the releaser writes the outcome into
+    the acquirer's mutable_shared (the status).
+    '''
     # not really colloidal
     def __init__(self, initial_keys):
         self.left_lock = threading.Lock()
@@ -56,6 +49,7 @@ class CompositeSemaphore(object):
         }
 
     def add_left(self, k):
+        '''add a key to the left set (between rounds)'''
         with self.semaphore_lock:
             if not self.mutable_hb["hb"]:
                 # print("cs killed")
@@ -67,6 +61,7 @@ class CompositeSemaphore(object):
                 self.key_count += 1
 
     def clear_left(self, k):
+        '''remove a key from the left set (between rounds)'''
         with self.semaphore_lock:
             if not self.mutable_hb["hb"]:
                 # print("cs killed")
@@ -77,6 +72,7 @@ class CompositeSemaphore(object):
 
     def wraparound_idempotent_increment(
         self, k, identifier=None):
+        '''advance k's counter to this round's tick; False if already ticked'''
         if self.tick > self.counters[k][0]:
             self.counters[k][0] += 1
             self.counters[k][1] = identifier
@@ -94,6 +90,11 @@ class CompositeSemaphore(object):
             return False
 
     def release(self, k, identifier=None):
+        '''
+        tick key k down (once per round). When the last key
+        ticks, write the status into every right's mutable_shared,
+        release them all, and reset the round.
+        '''
         go = True
         with self.mutable_hb["hb_lock"]:
             if not self.mutable_hb["hb"]:
@@ -137,6 +138,11 @@ class CompositeSemaphore(object):
             #     print("not found", k)
 
     def acquire(self, identifier, mutable_shared):
+        '''
+        register (identifier, mutable_shared) and block until a
+        full round of lefts releases it.
+        An identifier may acquire only once at a time.
+        '''
         # decorator?
         go = True
         with self.mutable_hb["hb_lock"]:
@@ -225,6 +231,7 @@ def consume_target(sem, x, delay, c, e):
 
 
 class Collector(object):
+    '''shared bookkeeping for main()'s producer / consumer demo'''
     def __init__(self, l):
         self.heartbeat = True
 
@@ -239,6 +246,15 @@ class Collector(object):
 #######################################
 
 class CSWait(CommonEvent):
+    '''
+    wait for a set of left tokens before a pending event may run:
+    dispatch finds / creates the CompositeSemaphore for its lefts
+    and blocks its own thread acquiring it; finish then enqueues
+    the pending event (it never dispatches it directly).
+
+    args: [lefts csv, requester name, <pending event serialization>]
+    lefts must not overlap another live CSWait's.
+    '''
     debug_color = bcolors.BLUE
 
     def prior_cb(self, args):
@@ -263,7 +279,8 @@ class CSWait(CommonEvent):
     @staticmethod
     def parse_lefts(s):
         '''
-        identifier is just a serialization of tokens, not a new thing
+        "b,a,b" -> (["a", "b"], "a,b"): deduped, sorted.
+        The identifier is just the joined serialization, not a new thing.
         '''
         tokens = sorted(list(set(s.split(","))))
 
@@ -361,6 +378,7 @@ class CSWait(CommonEvent):
         )
 
     def cleanup(self):
+        '''remove this wait's semaphore + identifier from the registry'''
         self.internal_log("cleaning up {}".format(self.ls))
         with self.blackboard["volatile"]["cs_registry_l"] and self.blackboard["volatile"]["cs_cv_l"]:
             for l in self.ls:
@@ -386,6 +404,7 @@ class CSWait(CommonEvent):
             )
 
     def finish(self, event_dispatch, *args, **kwargs):
+        '''cleanup, then enqueue the pending event (status -1: noop)'''
         # if self.exception:
         #     self.internal_log("noop")
         #     return
@@ -415,6 +434,9 @@ class CSWait(CommonEvent):
 
 class CSRelease(CommonEvent):
     '''
+    release some tokens, possibly unblocking CSWaits.
+    The release happens entirely in dispatch; finish is a noop.
+
     example:
     ["CSRelease", "0,1,2", 0, 0]
     the last 2 indices don't really matter
@@ -459,6 +481,7 @@ class CSRelease(CommonEvent):
         self.internal_log("CSRelease dispatch done!")
 
     def finish(self, event_dispatch, *args, **kwargs):
+        '''noop: CSRelease is a signal, not a process'''
         pass
 
 #######################################
@@ -470,6 +493,7 @@ class CSBQCVED(BlackboardQueueCVED):
     of its peers
     '''
     def register_blackboard_assets(self, blackboard, name):
+        '''the queue assets, plus the volatile cs registry / set / cv'''
         super(CSBQCVED, self).register_blackboard_assets(
             blackboard, name)
 
@@ -487,38 +511,44 @@ class CSBQCVED(BlackboardQueueCVED):
         blackboard["volatile"]["cs_cv"] = threading.Condition(
             blackboard["volatile"]["cs_cv_l"])
 
-    def prior_cb(self, blackboard):
-        '''
-        avoid overriding this
+    def _dispatch_cs_waits(self, blackboard):
+        '''partition the queue and dispatch this batch's CSWaits
+
+        The CS partition, shared by the blocking prior_cb below
+        and by subclasses that gate instead of blocking
+        (SimClockCSBQCVED): a CSWait whose identifier is already
+        registered, or whose lefts do not overlap a live
+        semaphore, is dispatched -- always on the threaded
+        vehicle (BlackboardQueueCVED.do_dispatch), never a
+        subclass's do_dispatch override. A CSWait whose lefts
+        overlap a live semaphore is rejected. The rest of the
+        queue is left in place.
+
+        Returns (cs_instances, accepted_ids, expected_ids):
+        expected includes rejected waits' identifiers (the
+        blocking prior_cb waits on it); accepted excludes them.
         '''
-        self.internal_log("CSBQCVED: prior_cb")
-
         cs_instances = []
+        accepted_ids = set()
         expected_cs_ids = set()
         non_cs_instances = []
         for instance in blackboard[self.queue_name]:
             if instance[0] in ["CSWait"]: # CSRelease, we only demand open-the-mouth on CSWait, CSRelease we don't care
-                # ids = CSWait.parse_lefts(instance[1])
-                # identifier = instance[2]
-
                 ids, identifier = CSWait.parse_lefts(instance[1])
 
-                self.internal_log("instance[1] {}, identifier: {}".format(instance[1], identifier))
-
                 # reject overlap at the dispatch level
                 # instead of in event
                 with blackboard["volatile"]["cs_registry_l"] and blackboard["volatile"]["cs_cv_l"]:
-                    if identifier in self.blackboard["volatile"]["cs_set"]:
+                    if identifier in blackboard["volatile"]["cs_set"]:
                         cs_instances.append(instance)
+                        accepted_ids.add(identifier)
                     elif len(set.intersection(
                         set(blackboard["volatile"]["cs_registry"].keys()),
-                        # ids)) == 0:
                         ids)) > 0:
                         self.internal_log("left overlap caught, rejecting CSWait attempt")
                     else:
                         cs_instances.append(instance)
-
-                # expected_cs_ids.update(ids)
+                        accepted_ids.add(identifier)
 
                 # we use the 'identifier' in cs_set because
                 # for now, CSWaits must be non-overlapping
@@ -528,24 +558,35 @@ class CSBQCVED(BlackboardQueueCVED):
             else:
                 non_cs_instances.append(instance)
 
-        self.internal_log("CS_INSTANCES {}!!!!!".format(cs_instances))
-        self.internal_log("non_cs_instances {}!!!!!".format(non_cs_instances))
-
         blackboard[self.queue_name] = non_cs_instances
 
+        for cs_instance in cs_instances:
+            BlackboardQueueCVED.do_dispatch(self, blackboard, cs_instance)
+
+        return cs_instances, accepted_ids, expected_cs_ids
+
+    def prior_cb(self, blackboard):
+        '''
+        avoid overriding this
+
+        partition the queue: CSWaits dispatch first (CSWaits
+        whose lefts overlap a live semaphore are rejected), and
+        the rest of the queue waits until every expected CSWait
+        has registered its semaphore.
+        '''
+        self.internal_log("CSBQCVED: prior_cb")
+
+        cs_instances, _, expected_cs_ids = self._dispatch_cs_waits(blackboard)
+
         if len(cs_instances) == 0:
             # self.internal_log("prior_cb DONE!!!!")
             return
 
-        for cs_instance in cs_instances:
-            self.do_dispatch(blackboard, cs_instance)
-
         self.internal_log("expected_cs_ids {}!!!!!".format(expected_cs_ids))
         if len(expected_cs_ids) > 0:
             self.blackboard["volatile"]["cs_cv_l"].acquire()
             while len(set.intersection(
                 self.blackboard["volatile"]["cs_set"],
-                # ids)) == 0:
                 expected_cs_ids)) < len(expected_cs_ids):
                 self.blackboard["volatile"]["cs_cv"].wait()
             self.blackboard["volatile"]["cs_cv_l"].release()
@@ -560,6 +601,7 @@ class CSBQCVED(BlackboardQueueCVED):
 
     # convienence function
     def clear_cs_waits(self, blackboard, key=None):
+        '''force-release waiting CSWaits (status -1: aborted); all, or one key'''
         if "volatile" not in blackboard:
             self.internal_log("blackboard missing volatile, noop")
             return
@@ -581,6 +623,7 @@ class CSBQCVED(BlackboardQueueCVED):
                     s[1].release()
 
 def main():
+    '''standalone produce / consume demo of CompositeSemaphore'''
     s = 4
 
     sem1 = CompositeSemaphore([x for x in range(s)])

{eventdispatch-0.2.29 → eventdispatch-0.2.30}/eventdispatch/core.py

@@ -14,10 +14,15 @@ import threading, collections
 from threading import Condition, Lock, Thread
 
 def wrap_instance_method(instance, method_name, wrapper_with_args):
+    '''instance.<method_name> = wrapper_with_args(instance.<method_name>)'''
     wrapped_method = wrapper_with_args(getattr(instance, method_name))
     setattr(instance, method_name, wrapped_method)
 
 def call_when_switch_turned_on(obj, switch, switch_lock):
+    '''
+    decorator factory: the wrapped call raises while obj.<switch>
+    is off; the check and the call happen under obj.<switch_lock>
+    '''
     def decorator(func):  # func should return void
         def wrapper(*args, **kwargs):
             lock_obj = getattr(obj, switch_lock)
@@ -33,6 +38,14 @@ def call_when_switch_turned_on(obj, switch, switch_lock):
     return decorator
 
 class Blackboard(dict):
+    '''
+    a dict with per-key condition variables
+
+    register_payload(key) rents a cv set for a key; setting that
+    key afterwards appends the value to the set's queue and
+    notifies its waiters (open-the-mouth-before-you-feed-it).
+    release_cv(key) returns the set to the pool.
+    '''
     def __init__(self, *args, **kwargs):
         # self.mutex = Lock()
         self.update(dict(*args, **kwargs))  # use the free update to set keys
@@ -65,6 +78,7 @@ class Blackboard(dict):
     #         super().__delitem__(key)
 
     def release_cv(self, key):
+        '''return key's cv set to the pool'''
         print("RELEASING CV", key)
         with self.cv_pool_lock:
             if key not in self.cvs:
@@ -76,6 +90,7 @@ class Blackboard(dict):
                 self.cv_pool.append(cv_set)
 
     def register_payload(self, payload, match_target = None):
+        '''rent a cv set for payload (recycled from the pool, or new)'''
         with self.cv_pool_lock:
             if len(self.cv_pool) > 0:
                 cv_set = self.cv_pool.pop(0)
@@ -149,33 +164,44 @@ class Event(object):
 
     # methods for the child to override
     def get_id(self):
+        '''the id this dispatch instance knows this event by'''
         # return self.__class__.__name__ + "@" + str(self.event_id)
         return self.event_id
 
     @staticmethod
     def deserialize(ed, blackboard, *args, **kwargs):
-        # up to the Event class to define
-        # returns 2 tuples, constructor_args, dispatch_args
-        # unlike dispatch / finish, involves no instance
+        '''
+        MUST override: turn a serialized form into
+        (constructor_args, dispatch_args); involves no instance
+        '''
         raise NotImplementedError
 
     def dispatch(self, event_dispatch, *args, **kwargs):
-        # CAN EITHER PASS IN ARGS OR KWARGS HERE
-        # OR SET THEM IN CONSTRUCTOR
-        # OR SET THEM IN THE BLACKBOARD
-        # unlike deserialize / finish, happens in its own thread
+        '''
+        MUST override: the work itself; runs in its own thread.
+        Do risky / uncertain stuff here.
+        Args can come from dispatch, the constructor, or the blackboard.
+        '''
         raise NotImplementedError
 
     def finish(self, event_dispatch, *args, **kwargs):
-        # unlike deserialize / dispatch, involves other events
-
-        # BEST PRACTICE:
-        # you should deal with OUTCOMES here
-        # do risky / uncertain stuff inside dispatch
-        # and deal with the outcomes here
+        '''
+        MUST override: called when dispatch's thread returns.
+        Deal with the outcomes here; only the event decides
+        what is dispatched next.
+        '''
         raise NotImplementedError
 
 class EventDispatch(object):
+    '''
+    the core mechanism: dispatch(event) spawns an EventThread
+    running event.dispatch; when that thread returns, its callback
+    dispatch_finish calls event.finish and releases the event id.
+
+    dispatch is wrapped at construction with a switch guard: an
+    event can set self.dispatch_switch off to stop all further
+    dispatching until it is cleared -- the safety axis.
+    '''
     def __init__(self, blackboard = None, ed_id = None):
         self.thread_registry = {}
         self.mutex_registry = {}
@@ -206,6 +232,7 @@ class EventDispatch(object):
     # something child ED class can override
     # for Event.deserialize to form some event_id
     def reserve_event_id(self):
+        '''an id unique within this dispatch instance; recycled'''
         if len(self.event_id_pool) > 0:
             return self.event_id_pool.pop()
         else:
@@ -214,10 +241,11 @@ class EventDispatch(object):
             return new_id
 
     def release_event_id(self, event_id):
-        # return event_id to pool
+        '''return event_id to the pool'''
         self.event_id_pool.add(event_id)
 
     def dispatch(self, event, *args, **kwargs):
+        '''spawn the event's thread (guarded by the dispatch switch)'''
         with self.dispatch_mutex:
             # print("dispatching %s" % (event.get_id())) # debug
             self.thread_registry[event.get_id()] = EventThread(
@@ -234,6 +262,7 @@ class EventDispatch(object):
             # NOTE: events must deal with exceptions internally
 
     def dispatch_finish(self, event, *args, **kwargs):
+        '''thread callback: unregister, call finish, release the id'''
         with self.dispatch_mutex:
             event_id = event.get_id()
             self.thread_registry.pop(event_id, None)

eventdispatch-0.2.29/eventdispatch/example1.py → eventdispatch-0.2.30/eventdispatch/example_core.py

@@ -6,6 +6,15 @@ Created on 2025-05-23
 
 Copyright (c) 2025, Charlie Yan
 License: Apache-2.0 (see LICENSE for details)
+
+Example core: the core mechanism on a BlackboardQueueCVED.
+WorkItemEvent's finish enqueues UncertainEvent1 / UncertainEvent2,
+which write results to the Blackboard; CheckEvent1 combines them.
+An interactive keyboard actor thread feeds the queue. Events run
+on EventThreads, finishes enqueue what happens next.
+
+Run:  eventdispatch_example_core
+      (or: python -m eventdispatch.example_core)
 '''
 
 from .core import *
@@ -18,7 +27,7 @@ import signal, time, os, sys, random, threading, argparse
 
 # these are examples Event classes
 # together, they define the drift and control in a system
-# defined here, they are registered as key-value paris in the Blackboard instance below
+# defined here, they are registered as key-value pairs in the Blackboard instance below
 
 class WorkItemEvent(CommonEvent):
     debug_color = bcolors.WARNING
@@ -239,7 +248,7 @@ class KeyboardThread(threading.Thread):
                 local_hb = self.mutable_hb['hb']
 
 def main():
-    parser = argparse.ArgumentParser(description='eventdispatch example1')
+    parser = argparse.ArgumentParser(description='eventdispatch example_core')
     parser.add_argument('--verbose',
         help="verbose, default=True",
         action='store_true')

eventdispatch-0.2.29/eventdispatch/example2.py → eventdispatch-0.2.30/eventdispatch/example_cs.py

@@ -6,17 +6,27 @@ Created on 2025-08-02
 
 Copyright (c) 2025, Charlie Yan
 License: Apache-2.0 (see LICENSE for details)
+
+Example cs: the composite-semaphore mechanism on a CSBQCVED.
+CSWait / CSRelease create on-the-fly associations between Events:
+type a command of the form ####aaa or aaa##### (# = digits,
+a = letters) -- if digits come first, that signal combination
+prints the letters; if letters come first, printing the letters
+produces those signals.
+
+Run:  eventdispatch_example_cs
+      (or: python -m eventdispatch.example_cs)
 '''
 
 from .core import *
 from .common1 import *
 from .composite_semaphore import *
-from .example1 import *
+from .example_core import *
 
 # from core import *
 # from common1 import *
 # from composite_semaphore import *
-# from example1 import KeyboardThread
+# from example_core import KeyboardThread
 
 import signal, time, os, sys, random, threading, argparse
 
@@ -197,7 +207,7 @@ class QuietCSRelease(CSRelease):
         pass
 
 def main():
-    parser = argparse.ArgumentParser(description='eventdispatch example2')
+    parser = argparse.ArgumentParser(description='eventdispatch example_cs')
     parser.add_argument('--verbose',
         help="verbose, default=True",
         action='store_true')