CreativePython 1.1.2__py3-none-any.whl → 1.1.4__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,36 +66,49 @@ def _createEvent(eventType, target, args=None):
 # Child process entry point
 #######################################################################################
 
-def _launchRenderer(childConn, shutdownReadConn, shutdownWriteConn):
+def _launchRenderer(childCommandConnection, childPriorityConnection, parentPriorityConnection):
    """
    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).
 
-   shutdownReadConn is the read end of the dedicated shutdown pipe; the child
-   watches it with QSocketNotifier and shuts down when it becomes readable (EOF).
-   shutdownWriteConn is the write end inherited from the parent (fork) or passed
-   via pickling (forkserver/spawn); it is closed immediately so that only the
-   parent's copy of the write end remains open — ensuring the child sees EOF when
-   the parent closes its copy.
+   childPriorityConnection 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 (parentPriorityConnection), the child
+   receives EOF and initiates shutdown.
+
+   parentPriorityConnection 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
-
-   shutdownWriteConn.close()   # child must not hold the write end open
-
-   # Suppress macOS system noise (stale XPC connections inherited via fork)
-   # 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)
-   os.close(_devnull)
-   sys.stderr = open(os.devnull, 'w')
-
-   from CreativePython.GuiRenderer import GuiRenderer
-   renderer = GuiRenderer(childConn, shutdownReadConn)
-   renderer.run()
+   import sys, os, traceback
+
+   parentPriorityConnection.close()   # child must not hold the parent end open
+
+   # Redirect stderr (fd 2) to a log file so both Python tracebacks and C-level
+   # output from Qt/Cocoa/XPC are captured for diagnostics.
+   # The log is removed on clean exit if nothing was written to it.
+   _logPath = os.path.join(os.getcwd(), "PENCIL_debug.log")
+   _logFile = open(_logPath, "w")
+   os.dup2(_logFile.fileno(), 2)
+   sys.stderr = _logFile
+
+   try:
+      from CreativePython.GuiRenderer import GuiRenderer
+      renderer = GuiRenderer(childCommandConnection, childPriorityConnection)
+      renderer.run()
+   except Exception:
+      traceback.print_exc()
+      raise
+   finally:
+      _logFile.flush()
+      if os.path.getsize(_logPath) == 0:
+         try:
+            _logFile.close()
+            os.unlink(_logPath)
+         except OSError:
+            pass
 
 
 #######################################################################################
@@ -113,8 +131,8 @@ class GuiHandler:
       Registers an atexit handler so the child is always cleaned up when
       the parent process exits — no cleanup code required in gui.py.
       """
-      parentConn, childConn = multiprocessing.Pipe(duplex=True)
-      self.connection = parentConn
+      parentCommandConnection, childCommandConnection = multiprocessing.Pipe(duplex=True)
+      self.connection = parentCommandConnection
 
       # Choose the spawn context based on the runtime environment:
       #
@@ -132,31 +150,32 @@ 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 one-directional shutdown pipe.  The parent holds the write
-      # end; the child holds the read end.  Closing the write end in the parent
-      # sends EOF to the child's read end, which Qt detects immediately via
-      # QSocketNotifier — independent of the command queue and independent of
-      # whether atexit runs (the OS closes the fd automatically on process death).
-      shutdownReadConn, shutdownWriteConn = multiprocessing.Pipe(duplex=False)
-      self._shutdownPipe = shutdownWriteConn
+      # Dedicated duplex admin pipe.  The parent holds parentPriorityConnection; the child
+      # holds childPriorityConnection.  Admin commands (setRate, getRate) travel here,
+      # bypassing the command buffer entirely.  Closing parentPriorityConnection 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.
+      childPriorityConnection, parentPriorityConnection = multiprocessing.Pipe(duplex=True)
+      self._adminConn = parentPriorityConnection
 
       # With 'spawn' on POSIX (fork+exec), the forked helper calls
       # get_preparation_data() which reads sys.modules['__main__'].__file__.
@@ -177,7 +196,7 @@ class GuiHandler:
       try:
          self.childProcess = ctx.Process(
             target = _launchRenderer,
-            args   = (childConn, shutdownReadConn, shutdownWriteConn),
+            args   = (childCommandConnection, childPriorityConnection, parentPriorityConnection),
             daemon = True   # child is killed automatically if parent dies unexpectedly
          )
          self.childProcess.start()
@@ -187,8 +206,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 command pipe
-      shutdownReadConn.close() # parent no longer needs the read end of the shutdown pipe
+      childCommandConnection.close()      # parent no longer needs the child end of the command pipe
+      childPriorityConnection.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
@@ -209,14 +228,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 ───────────────────────────────────────────────────────────
@@ -234,9 +290,10 @@ class GuiHandler:
    def _listenForMessages(self):
       """
       Background thread.  Reads incoming messages from GuiRenderer and routes
-      each one: responses unblock waiting sendQuery() callers; events invoke
-      registered callbacks.  Exits when the child closes the pipe (EOFError)
-      and releases any sendQuery() callers still waiting for a response.
+      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:
@@ -244,13 +301,14 @@ class GuiHandler:
             if 'responseId' in message:
                self._handleResponse(message)
             elif 'type' in message:
-               self._dispatchEvent(message)
+               self._eventQueue.put(message)
          except EOFError:
             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):
       """
@@ -267,22 +325,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}
@@ -292,8 +419,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
 
@@ -302,25 +437,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):
@@ -336,10 +452,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')
@@ -357,12 +533,16 @@ class GuiHandler:
    def _shutdown(self):
       """
       Signals the child to shut down and waits for it to exit.
-      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.
+      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.
       """
-      self._shutdownPipe.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)
 
 
@@ -383,8 +563,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():