DeviceController.submit() returns a Future with the action's result

Generality fix: submit() was fire-and-forget, which suits move/turnOn but is
useless for query-style devices (powermeter/oscilloscope reads return data).
It now returns a concurrent.futures.Future that resolves with the action's
return value or its exception, so any PhysicalDevice — not just actuators —
is fully usable:

    reading = controller.submit(lambda d: d.power()).result()

commandFailed is still posted for observers that don't hold the Future.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01K6LVhfM3d9CcJdkuSMMqag

Author: dccote

hardwarelibrary/devicecontroller.py

@@ -37,13 +37,15 @@ def on_status(notification):
     NotificationCenter().addObserver(self, on_status, N.status)
     controller.start()
     controller.connect()
-    controller.submit(lambda device: device.turnOn())
+    controller.submit(lambda device: device.turnOn())       # fire-and-forget
+    reading = controller.submit(lambda device: device.power()).result()  # query
     ...
     controller.stop()
 """
 
 import queue
 import time
+from concurrent.futures import Future
 from enum import Enum
 from threading import Event, RLock, Thread
 
@@ -152,13 +154,18 @@ def disconnect(self):
         self._queue.put(("disconnect", None))
 
     def submit(self, action, name=None):
-        """Run ``action(device)`` on the worker thread.
-
-        Returns immediately. On failure a commandFailed notification is posted
-        with the exception. A status poll is forced right after a successful
-        command so observers see the new state promptly.
+        """Run ``action(device)`` on the worker thread; return a Future.
+
+        The Future resolves with the action's return value (so query-style
+        devices can read a measurement back: ``controller.submit(lambda d:
+        d.power()).result()``) or with its exception. On failure a commandFailed
+        notification is also posted, for observers that don't hold the Future.
+        A status poll is forced after a successful command so observers see the
+        new state promptly. Do not block on ``.result()`` from a UI thread.
         """
-        self._queue.put(("command", (action, name)))
+        future = Future()
+        self._queue.put(("command", (action, name, future)))
+        return future
 
     def stop(self):
         """Stop the worker thread and shut the device down."""
@@ -258,19 +265,24 @@ def _poll(self):
             return
         self._post(DeviceControllerNotification.status, userInfo=info)
 
-    def _do_command(self, action, name):
+    def _do_command(self, action, name, future):
+        if not future.set_running_or_notify_cancel():
+            return  # the caller cancelled the Future before it ran
         if not self.is_connected:
-            self._post(DeviceControllerNotification.commandFailed,
-                       userInfo=RuntimeError(
-                           "Cannot run command {0!r}: not connected".format(name)))
+            error = RuntimeError(
+                "Cannot run command {0!r}: not connected".format(name))
+            self._post(DeviceControllerNotification.commandFailed, userInfo=error)
+            future.set_exception(error)
             return
         try:
-            action(self.device)
+            result = action(self.device)
         except Exception as error:
             # A failed command may mean the link dropped; verify with a poll.
             self._post(DeviceControllerNotification.commandFailed, userInfo=error)
+            future.set_exception(error)
             self._poll()
             return
+        future.set_result(result)
         # Reflect the new state promptly.
         if self._supports_status:
             self._next_poll = time.monotonic()

hardwarelibrary/tests/testDeviceController.py

@@ -131,15 +131,25 @@ def testSubmittedCommandRunsAndStatusReflectsIt(self):
         self.assertTrue(status["isLaserOn"])
         self.assertTrue(status["isShutterOpen"])
 
-    def testFailedCommandPostsCommandFailed(self):
+    def testSubmitReturnsResultViaFuture(self):
+        controller, rec = self.make()
+        controller.connect()
+        rec.wait_for(DeviceControllerNotification.didConnect)
+        controller.submit(lambda device: device.setPower(8.0)).result(timeout=3.0)
+        reading = controller.submit(lambda device: device.power()).result(timeout=3.0)
+        self.assertEqual(reading, 8.0)
+
+    def testFailedCommandPostsCommandFailedAndRaisesInFuture(self):
         controller, rec = self.make()
         controller.connect()
         rec.wait_for(DeviceControllerNotification.didConnect)
 
         def boom(device):
             raise ValueError("nope")
 
-        controller.submit(boom)
+        future = controller.submit(boom)
+        with self.assertRaises(ValueError):
+            future.result(timeout=3.0)
         info = rec.wait_for(DeviceControllerNotification.commandFailed)
         self.assertIsInstance(info, ValueError)