CreativePython 1.1.1__py3-none-any.whl → 1.1.3__py3-none-any.whl

CreativePython/GuiHandler.py

@@ -15,8 +15,13 @@
 
 import multiprocessing
 import threading
+import queue
 import atexit
 
+# Sender thread tick rate.  High enough that the final partial batch after a
+# burst (e.g. a tight for loop) reaches Qt within a few milliseconds.
+_FLUSH_RATE      = 200
+_MAX_BUFFER_SIZE = 512   # flush inline when buffer reaches this size
 
 #######################################################################################
 # Message Protocol Helpers
@@ -61,18 +66,28 @@ def _createEvent(eventType, target, args=None):
 # Child process entry point
 #######################################################################################
 
-def _launchRenderer(childConn):
+def _launchRenderer(childConn, adminChildConn, adminParentConn):
    """
    Entry point for the GuiRenderer child process.
    Defined here so GuiHandler can reference it without importing from GuiRenderer
    globally (which would also import Qt/PySide6 in the parent process).
 
+   adminChildConn is the child end of the duplex admin pipe; the child watches it
+   with QSocketNotifier.  Admin commands (setRate, getRate) arrive here, bypassing
+   the command buffer.  When the parent closes its end (adminParentConn), the child
+   receives EOF and initiates shutdown.
+
+   adminParentConn is the parent's end; the child closes it immediately so that
+   only the parent holds it — ensuring the child sees EOF when the parent closes.
+
    At runtime this function only executes in the child process.
    """
    import sys, os
 
-   # Suppress macOS system noise (stale XPC connections inherited via fork)
-   # that would confuse students.  Redirect at the OS level (fd 2) so that
+   adminParentConn.close()   # child must not hold the parent end open
+
+   # Suppress macOS system noise that would confuse students.
+   # Redirect at the OS level (fd 2) so that
    # C-level libraries (Cocoa, XPC) are also silenced.
    _devnull = os.open(os.devnull, os.O_WRONLY)
    os.dup2(_devnull, 2)
@@ -80,7 +95,7 @@ def _launchRenderer(childConn):
    sys.stderr = open(os.devnull, 'w')
 
    from CreativePython.GuiRenderer import GuiRenderer
-   renderer = GuiRenderer(childConn)
+   renderer = GuiRenderer(childConn, adminChildConn)
    renderer.run()
 
 
@@ -123,23 +138,33 @@ class GuiHandler:
       #                which would re-run the user's script.  Used on Windows where
       #                fork is unavailable.
       #
-      # Detection: if tkinter has been imported into the current process, Cocoa is
-      # live and we must avoid fork.  Otherwise, fork is safe and avoids the
-      # __main__ re-import problem that spawn/forkserver have.
+      # On macOS, fork() is unsafe whenever the parent has any CoreFoundation /
+      # Cocoa state — not just when tkinter is explicitly imported.  The Python
+      # runtime on macOS initialises parts of CoreFoundation at startup, so a
+      # forked child that then creates a QApplication reliably triggers the
+      # "You MUST exec()" crash.  forkserver avoids this by forking from a clean
+      # helper process that has never touched Cocoa.
+      # On Windows, spawn is required (no fork).
+      # Inside a PyInstaller frozen binary, forkserver can't work (sys.executable
+      # is the frozen app, not a Python interpreter), so spawn is used instead.
       import sys
       if sys.platform == 'win32':
          ctx = multiprocessing.get_context('spawn')
       elif getattr(sys, 'frozen', False):
-         # Running inside a PyInstaller frozen executable.  forkserver spawns
-         # its helper by calling sys.executable as a Python interpreter, which
-         # doesn't work when sys.executable is the frozen app binary.  spawn
-         # is safe here because freeze_support() in the entry point intercepts
-         # the --multiprocessing-fork flag before any app code runs.
          ctx = multiprocessing.get_context('spawn')
-      elif 'tkinter' in sys.modules:
+      elif sys.platform == 'darwin':
          ctx = multiprocessing.get_context('forkserver')
       else:
          ctx = multiprocessing.get_context('fork')
+
+      # Dedicated duplex admin pipe.  The parent holds adminParentConn; the child
+      # holds adminChildConn.  Admin commands (setRate, getRate) travel here,
+      # bypassing the command buffer entirely.  Closing adminParentConn sends EOF
+      # to the child, which Qt detects via QSocketNotifier and treats as shutdown —
+      # independent of the command queue and independent of whether atexit runs.
+      adminChildConn, adminParentConn = multiprocessing.Pipe(duplex=True)
+      self._adminConn = adminParentConn
+
       # With 'spawn' on POSIX (fork+exec), the forked helper calls
       # get_preparation_data() which reads sys.modules['__main__'].__file__.
       # When a user script is running in PENCIL's subprocess, __main__.__file__
@@ -159,7 +184,7 @@ class GuiHandler:
       try:
          self.childProcess = ctx.Process(
             target = _launchRenderer,
-            args   = (childConn,),
+            args   = (childConn, adminChildConn, adminParentConn),
             daemon = True   # child is killed automatically if parent dies unexpectedly
          )
          self.childProcess.start()
@@ -169,7 +194,8 @@ class GuiHandler:
                _main_mod.__file__ = _saved_file
             if _saved_spec is not _UNSET:
                _main_mod.__spec__ = _saved_spec
-      childConn.close()   # parent no longer needs the child end of the Pipe
+      childConn.close()      # parent no longer needs the child end of the command pipe
+      adminChildConn.close() # parent no longer needs the child end of the admin pipe
 
       # responseId counter — each sendQuery() call gets a unique ID so the
       # listener thread can route the response back to the correct caller
@@ -190,14 +216,51 @@ class GuiHandler:
       # must acquire this lock before writing to the pipe
       self._sendLock = threading.Lock()
 
+      # command buffer — fire-and-forget commands are queued here and sent as
+      # a single batch by the sender thread (or flushed early on a query)
+      self._commandBuffer = []
+      self._bufferLock    = threading.Lock()
+
+      # flush rate - how often to flush the buffer
+      self._flushRate     = _FLUSH_RATE
+      self._maxBufferSize = _MAX_BUFFER_SIZE
+
+      # callback active lock — held by the dispatch thread while an event callback
+      # is executing.  The sender thread checks this non-blocking; if it can't
+      # acquire, it skips that flush tick so mid-callback commands don't travel as
+      # a partial batch.  After the callback, the dispatch thread does one explicit
+      # flush to send everything the callback accumulated as a single pipe message.
+      self._callbackActive = threading.Lock()
+
+      # sender thread — wakes every 1/FLUSH_RATE seconds and flushes the buffer
+      self._senderStopEvent = threading.Event()
+      self._senderThread = threading.Thread(
+         target = self._runSenderThread,
+         daemon = True
+      )
+      self._senderThread.start()
+
+      # event queue — listener thread enqueues incoming events here; dispatch
+      # thread drains it and runs callbacks.  Decoupling the two threads means
+      # callbacks can call sendQuery() without deadlocking the listener.
+      self._eventQueue = queue.SimpleQueue()
+
       # single listener thread handles both responses and events, since both
       # arrive on the same connection and reading from it on two threads would race
       self._listenerThread = threading.Thread(
          target = self._listenForMessages,
-         daemon = True   # thread exits automatically when the main process exits
+         daemon = True
       )
       self._listenerThread.start()
 
+      # dispatch thread runs event callbacks sequentially off the event queue,
+      # keeping the listener thread free to receive query responses at all times
+      self._dispatchThread = threading.Thread(
+         target = self._runDispatchThread,
+         daemon = True
+      )
+      self._dispatchThread.start()
+
       atexit.register(self._shutdown)
 
    # ── Response ID ───────────────────────────────────────────────────────────
@@ -214,11 +277,11 @@ class GuiHandler:
 
    def _listenForMessages(self):
       """
-      Background thread.  Reads all incoming messages from GuiRenderer and
-      routes each one based on its type:
-        - 'responseId' key present → response for a waiting sendQuery() call
-        - 'type' key present       → event for a registered callback
-      Exits when the pipe is closed (EOFError).
+      Background thread.  Reads incoming messages from GuiRenderer and routes
+      each one: responses unblock waiting sendQuery() callers; events are
+      pushed onto _eventQueue for the dispatch thread.  Exits when the child
+      closes the pipe (EOFError), releases any waiting sendQuery() callers,
+      and sends a None sentinel to stop the dispatch thread.
       """
       while True:
          try:
@@ -226,9 +289,14 @@ class GuiHandler:
             if 'responseId' in message:
                self._handleResponse(message)
             elif 'type' in message:
-               self._dispatchEvent(message)
+               self._eventQueue.put(message)
          except EOFError:
-            break   # pipe closed; thread exits cleanly
+            break
+      with self._pendingLock:
+         for slot in self._pendingResponses.values():
+            slot['values'] = ['shutdown']
+            slot['event'].set()
+      self._eventQueue.put(None)   # sentinel: tell dispatch thread to stop
 
    def _handleResponse(self, responseDict):
       """
@@ -245,22 +313,91 @@ class GuiHandler:
          pendingSlot['values'] = values   # store result before signalling
          pendingSlot['event'].set()       # unblock the waiting sendQuery() call
 
+   # ── Sender thread ─────────────────────────────────────────────────────────
+
+   def _runSenderThread(self):
+      """
+      Background thread.  Wakes every 1 / _flushRate seconds and flushes the
+      command buffer.  Skips a tick if a callback is currently executing
+      (_callbackActive is held) so the callback's commands don't get split
+      across multiple pipe messages.  Exits when _senderStopEvent is set.
+      """
+      while not self._senderStopEvent.wait(timeout=1.0 / self._flushRate):
+         if self._callbackActive.acquire(blocking=False):
+            self._callbackActive.release()
+            self._flushBuffer()
+         # else: callback in progress — skip this tick
+      self._flushBuffer()   # final drain on shutdown
+
+   def _flushBuffer(self):
+      """
+      Sends the current command buffer as a single batch message, then resets
+      the buffer.  Thread-safe; concurrent callers are safe — only one will
+      get a non-empty batch, the others are no-ops.
+      """
+      with self._bufferLock:
+         batch = self._commandBuffer
+         if not batch:
+            return
+         self._commandBuffer = []
+      with self._sendLock:
+         try:
+            self.connection.send(batch)
+         except (BrokenPipeError, OSError):
+            self._senderStopEvent.set()   # pipe is gone; stop the sender thread
+
+   def getFlushRate(self):
+      """
+      Returns the current tick rate for flushing the command buffer.
+      """
+      return self._flushRate
+
+   def setFlushRate(self, flushRate):
+      """
+      Sets the current tick rate for flushing the command buffer.
+      """
+      self._flushRate = flushRate
+
+   def getRate(self):
+      """
+      Returns the current render rate (timer ticks per second) of the Qt renderer.
+      Sends directly on the admin pipe, bypassing the command buffer.
+      """
+      self._adminConn.send({'action': 'getRate'})
+      return self._adminConn.recv()
+
+   def setRate(self, rate):
+      """
+      Sets the render rate (timer ticks per second) of the Qt renderer.
+      Sends directly on the admin pipe, bypassing the command buffer.
+      """
+      self._adminConn.send({'action': 'setRate', 'rate': rate})
+
    # ── Sending ───────────────────────────────────────────────────────────────
 
    def sendCommand(self, action, target, args=None):
       """
-      Sends a fire-and-forget command to GuiRenderer (no response expected).
-      Thread-safe.
+      Queues a fire-and-forget command in the command buffer.  The sender thread
+      flushes on each tick.  Thread-safe.
       """
       command = _createCommand(action, target, args)
-      with self._sendLock:
-         self.connection.send(command)
+      with self._bufferLock:
+         self._commandBuffer.append(command)
+         flush_now = len(self._commandBuffer) >= self._maxBufferSize
+      if flush_now and self._callbackActive.acquire(blocking=False):
+         self._callbackActive.release()
+         self._flushBuffer()
 
    def sendQuery(self, action, target, args=None):
       """
       Sends a command to GuiRenderer and blocks until a response is received.
       Returns the response's values list.  Thread-safe; multiple callers may
       block concurrently — each is matched to its response by responseId.
+
+      Flushes any buffered fire-and-forget commands before sending the query
+      so that GuiRenderer processes them first and the query reflects up-to-date
+      state.  The flush and query send are both performed under _sendLock so
+      no other thread can interleave a send between them.
       """
       responseId  = self._nextResponseId()
       pendingSlot = {'event': threading.Event(), 'values': None}
@@ -270,8 +407,16 @@ class GuiHandler:
          self._pendingResponses[responseId] = pendingSlot
 
       command = _createCommand(action, target, args, responseId=responseId)
+
+      # grab any buffered commands, then send them + the query atomically as one list
+      with self._bufferLock:
+         batch = self._commandBuffer
+         self._commandBuffer = []
       with self._sendLock:
-         self.connection.send(command)
+         try:
+            self.connection.send(batch + [command])
+         except (BrokenPipeError, OSError):
+            pass   # pipe is gone; listener thread will release the pending slot via EOFError
 
       pendingSlot['event'].wait()   # block until the listener signals a response
 
@@ -280,25 +425,6 @@ class GuiHandler:
 
       return pendingSlot['values']
 
-   # ── Developer utilities ───────────────────────────────────────────────────
-
-   def getBatchSize(self):
-      """
-      Returns the current _BATCH_SIZE used by GuiRenderer's pipe-polling loop.
-      Not part of the public API — intended for developer tuning only.
-      """
-      result = self.sendQuery('getBatchSize', None)
-      return result[0]
-
-   def setBatchSize(self, batchSize):
-      """
-      Sets GuiRenderer's _BATCH_SIZE on the fly.
-      Higher values process more commands between Qt repaints (better throughput,
-      less responsive feel); lower values yield more frequent repaints.
-      Not part of the public API — intended for developer tuning only.
-      """
-      self.sendCommand('setBatchSize', None, {'batchSize': batchSize})
-
    # ── Events ────────────────────────────────────────────────────────────────
 
    def registerEvent(self, objectId, eventType, callback):
@@ -314,10 +440,70 @@ class GuiHandler:
       registrationArgs = {'objectId': objectId, 'eventType': eventType}
       self.sendCommand('registerEvent', None, registrationArgs)
 
+   def _runDispatchThread(self):
+      """
+      Background thread.  Drains _eventQueue and runs event callbacks
+      sequentially.  Decoupled from the listener thread so callbacks can call
+      sendQuery() without deadlocking the listener.
+
+      Coalesces consecutive position events (mouseMove, mouseDrag) for the same
+      target: when multiple are queued back-to-back, only the last one is
+      dispatched.  This prevents lag when a callback involves a query round-trip
+      (e.g. intersects()) that causes events to accumulate faster than they are
+      consumed.  All other event types (clicks, keys, enter/exit) are always
+      dispatched in full order.
+
+      Exits when it receives the None sentinel pushed by _listenForMessages.
+      """
+      _COALESCE = frozenset({'mouseMove', 'mouseDrag'})
+
+      while True:
+         # block until at least one event is available
+         batch = [self._eventQueue.get()]
+         if batch[0] is None:
+            break
+
+         # drain any additional immediately-available events into the batch
+         try:
+            while True:
+               msg = self._eventQueue.get(block=False)
+               batch.append(msg)
+               if msg is None:
+                  break   # sentinel — process batch then exit
+         except queue.Empty:
+            pass
+
+         # process the batch in order, coalescing consecutive position events
+         i = 0
+         while i < len(batch):
+            msg = batch[i]
+            if msg is None:
+               return   # sentinel reached mid-batch
+
+            eventType = msg.get('type')
+            if eventType in _COALESCE:
+               target = msg.get('target')
+               # find the last consecutive event of the same type+target
+               j = i + 1
+               while (j < len(batch)
+                      and batch[j] is not None
+                      and batch[j].get('type')   == eventType
+                      and batch[j].get('target') == target):
+                  j += 1
+               with self._callbackActive:
+                  self._dispatchEvent(batch[j - 1])   # skip stale positions
+               self._flushBuffer()
+               i = j
+            else:
+               with self._callbackActive:
+                  self._dispatchEvent(msg)
+               self._flushBuffer()
+               i += 1
+
    def _dispatchEvent(self, eventDict):
       """
       Looks up and calls the callback registered for the incoming event.
-      Called from the listener thread; the callback runs on that thread.
+      Called from the dispatch thread.
       """
       eventType = eventDict.get('type')
       objectId  = eventDict.get('target')
@@ -334,23 +520,18 @@ class GuiHandler:
 
    def _shutdown(self):
       """
-      Kills the child process immediately and closes the pipe.
+      Signals the child to shut down and waits for it to exit.
+      Stops the sender thread first so any remaining buffered commands are
+      flushed before the pipe closes.  Closing the shutdown pipe delivers EOF
+      to the child's QSocketNotifier, which fires _onShutdownSignal on Qt's
+      main thread immediately — even if atexit does not run, since the OS
+      closes the pipe fd on process death.
       Called automatically via atexit when the parent process exits.
-      The child is killed with SIGKILL so it does not drain its event queue —
-      exit() in the parent should return promptly.
-      """
-      if self.childProcess.is_alive():
-         # SIGTERM is overridden in the child to call os._exit(0) immediately,
-         # bypassing Qt's graceful shutdown (which drains the event queue).
-         # Python delivers SIGTERM between bytecodes, so it fires within one
-         # iteration of the child's _pollPipe loop — far faster than SIGKILL,
-         # which macOS may defer while a Metal/GPU operation is in flight.
-         self.childProcess.terminate()
-         self.childProcess.join(timeout=0.5)   # should die in < 1 ms
-      if self.childProcess.is_alive():
-         self.childProcess.kill()              # backup: SIGKILL
-         self.childProcess.join(timeout=2.0)
-      self.connection.close()
+      """
+      self._senderStopEvent.set()
+      self._senderThread.join(timeout=1.0)
+      self._adminConn.close()   # EOF on child's admin pipe triggers shutdown
+      self.childProcess.join(timeout=1.0)
 
 
 #######################################################################################
@@ -370,8 +551,10 @@ class _NullHandler:
    def sendCommand(self, action, target, args=None): pass
    def sendQuery(self,   action, target, args=None): return [0, 0, 0, 0]
    def registerEvent(self, objectId, eventType, callback): pass
-   def getBatchSize(self): return 0
-   def setBatchSize(self, batchSize): pass
+   def getFlushRate(self): return _FLUSH_RATE
+   def setFlushRate(self, flushRate): pass
+   def getRate(self): return _FLUSH_RATE
+   def setRate(self, _rate): pass
 
 
 def _createHandler():