bec-server 3.151.2__tar.gz → 3.152.0__tar.gz

{bec_server-3.151.2 → bec_server-3.152.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bec-server
-Version: 3.151.2
+Version: 3.152.0
 Summary: BEC server
 Project-URL: Bug Tracker, https://github.com/bec-project/bec/issues
 Project-URL: Homepage, https://github.com/bec-project/bec

{bec_server-3.151.2 → bec_server-3.152.0}/bec_server/device_server/device_server.py

@@ -380,7 +380,7 @@ class DeviceServer(BECService):
     def on_stop_devices(self, msg: MessageObject, **_kwargs) -> None:
         """
         Callback for receiving device stop requests.
-        Handles both stopping all devices (empty list) and stopping specific devices (list of device names).
+        Handles stop-all (`None`), stop-none (`[]`), and stopping specific devices (device-name list).
 
         Args:
             msg: MessageObject containing the stop request.
@@ -397,10 +397,13 @@ class DeviceServer(BECService):
                 for stop_id in mvalue.metadata["stop_id"]:
                     if stop_id is not None:
                         self.requests_handler._stopped_requests.append(stop_id)
-        if not mvalue.value:
+        if mvalue.value is None:
             self.stop_devices()
             logger.info("Received request to stop all devices.")
             return
+        if mvalue.value == []:
+            logger.info("Received request to stop no devices.")
+            return
         logger.info(f"Received request to stop devices: {mvalue.value}")
         self.stop_devices(mvalue.value)
 

{bec_server-3.151.2 → bec_server-3.152.0}/bec_server/device_server/devices/device_serializer.py

@@ -5,11 +5,12 @@ is used to create the device interface for proxy objects on other services.
 
 import functools
 from contextlib import contextmanager
+from enum import Enum
 from typing import Any, Generator
 
 import msgpack
 from ophyd import Device, Kind, PositionerBase, Signal
-from ophyd_devices import BECDeviceBase, ComputedSignal
+from ophyd_devices import BECDeviceBase, ComputedSignal, PSIDeviceBase
 from ophyd_devices.utils.bec_signals import BECMessageSignal
 
 from bec_lib.bec_errors import DeviceConfigError
@@ -21,6 +22,26 @@ from bec_lib.signature_serializer import signature_to_dict
 logger = bec_logger.logger
 
 
+class OwnershipMode(str, Enum):
+    """
+    Ownership policy used in serialized device info.
+
+    FREE: The device is free to be used by any scan or procedure without acquiring a lock.
+        This is typically used for read-only signals.
+    CLAIMABLE: The device can be locked by a scan or procedure. It can be used without a lock,
+        but if a scan or procedure wants to use it, it should acquire a lock first. Typical
+        examples are motors that are normally on readout priority "baseline". When a scan wants
+        to use the motor, it should acquire a lock first. If the motor is already locked by
+        another scan or procedure, the scan will wait until the lock is released.
+    PINNED: When enabled, the device has to be locked by a scan before it can be used. This is
+        typically used for devices that are stateful during a scan, such as detectors or flyers.
+    """
+
+    FREE = "free"
+    CLAIMABLE = "claimable"
+    PINNED = "pinned"
+
+
 @contextmanager
 def disable_lazy_wait_for_connection(
     device: PositionerBase | ComputedSignal | Signal | Device | BECDeviceBase,
@@ -117,6 +138,43 @@ def get_device_base_class(obj: Any) -> str:
     return "unknown"
 
 
+def get_ownership_mode(
+    obj: PositionerBase | ComputedSignal | Signal | Device | BECDeviceBase,
+) -> OwnershipMode:
+    """
+    Resolve ownership policy for a device or signal.
+    The logic is as follows:
+    1. If the class has an explicit ownership_mode attribute, use that.
+    2. If the object is a PSIDeviceBase, it is pinned.
+    3. If the object is a signal and has write_access set to False, it is free.
+    4. Otherwise, it is claimable.
+
+    Args:
+        obj (PositionerBase | ComputedSignal | Signal | Device | BECDeviceBase): object to get the ownership mode from
+
+    Returns:
+        OwnershipMode: ownership mode of the object
+    """
+    explicit_mode = getattr(obj.__class__, "ownership_mode", None)
+    if explicit_mode is not None:
+        try:
+            return OwnershipMode(explicit_mode)
+        except ValueError as exc:
+            raise DeviceConfigError(
+                f"Invalid ownership_mode {explicit_mode!r} configured on "
+                f"{obj.__class__.__name__}. Expected one of: "
+                f"{', '.join(mode.value for mode in OwnershipMode)}."
+            ) from exc
+
+    if isinstance(obj, PSIDeviceBase):
+        return OwnershipMode.PINNED
+
+    if get_device_base_class(obj) == "signal" and getattr(obj, "write_access", None) is False:
+        return OwnershipMode.FREE
+
+    return OwnershipMode.CLAIMABLE
+
+
 def get_device_info(
     obj: PositionerBase | ComputedSignal | Signal | Device | BECDeviceBase, connect=True
 ) -> dict:
@@ -256,6 +314,7 @@ def get_device_info(
             "device_dotted_name": getattr(obj, "dotted_name", ""),
             "device_base_class": get_device_base_class(obj),
             "device_class": obj.__class__.__name__,
+            "ownership_mode": get_ownership_mode(obj).value,
             "read_access": getattr(obj, "read_access", None),
             "write_access": getattr(obj, "write_access", None),
             "signals": signals,

bec_server-3.152.0/bec_server/scan_server/device_lock_registry.py

@@ -0,0 +1,193 @@
+from __future__ import annotations
+
+import threading
+import time
+from collections import defaultdict
+from collections.abc import Callable, Iterable
+
+from bec_lib.logger import bec_logger
+
+logger = bec_logger.logger
+
+
+class DeviceLockRegistry:
+    """Registry that tracks per-request device locks for the scan server."""
+
+    WAIT_INTERVAL_S: float = 0.1
+    WAIT_LOG_INTERVAL_S: float = 5.0
+
+    def __init__(self) -> None:
+        """Initialize the device lock registry."""
+        self._condition: threading.Condition = threading.Condition()
+
+        # Maps device names to the request ID that currently owns the lock.
+        self._device_owners: dict[str, str] = {}
+
+        # Maps request IDs to the set of device names they currently own.
+        self._owner_devices: dict[str, set[str]] = defaultdict(set)
+
+        # Maps request IDs to the set of device names they are currently waiting for.
+        self._pending_device_locks: dict[str, set[str]] = defaultdict(set)
+
+    def acquire_many(
+        self,
+        request_id: str,
+        devices: Iterable[str],
+        interruption_callback: Callable[[], None] | None = None,
+        queue_update_callback: Callable[[], None] | None = None,
+    ) -> list[str]:
+        """
+        Acquire locks for multiple devices on behalf of a request.
+
+        Args:
+            request_id (str): request identifier that will own the device locks.
+            devices (Iterable[str]): device names to lock.
+            interruption_callback (Callable[[], None] | None, optional):
+                callback invoked while waiting for a lock, allowing the caller
+                to react to interruptions. Defaults to None.
+            queue_update_callback (Callable[[], None] | None, optional):
+                callback invoked when queue-visible lock state changes, e.g.
+                owned or waiting devices. Defaults to None.
+
+        Returns:
+            list[str]: sorted device names whose locks were acquired.
+        """
+        device_names = sorted(set(devices))
+        if not device_names:
+            return []
+
+        next_log_time = 0.0
+        while True:
+            should_wait = False
+            should_queue_update = False
+            blocked_owners: dict[str, str] = {}
+            waiting_devices = sorted(self._pending_device_locks.get(request_id, set()))
+
+            with self._condition:
+                acquirable_devices: list[str] = []
+                blocked_devices: list[str] = []
+
+                for device in device_names:
+                    current_owner = self._device_owners.get(device)
+                    if current_owner == request_id:
+                        # we already own this device, so we can skip it
+                        continue
+                    if current_owner is None:
+                        # the device is not owned by anyone, so we can acquire it
+                        acquirable_devices.append(device)
+                        continue
+
+                    # the device is owned by another request, so we need to wait for it
+                    blocked_devices.append(device)
+                    blocked_owners[device] = current_owner
+
+                for device in acquirable_devices:
+                    self._device_owners[device] = request_id
+                    self._owner_devices[request_id].add(device)
+
+                self._pending_device_locks[request_id] = set(blocked_devices)
+                if blocked_devices:
+                    should_wait = True
+                    next_log_time = self._log_waiting_for_device_lock(
+                        request_id=request_id,
+                        blocked_owners=blocked_owners,
+                        next_log_time=next_log_time,
+                    )
+                    self._condition.wait(timeout=self.WAIT_INTERVAL_S)
+
+                next_waiting_devices = sorted(self._pending_device_locks[request_id])
+                should_queue_update = bool(acquirable_devices) or (
+                    next_waiting_devices != waiting_devices
+                )
+
+            if should_queue_update and queue_update_callback is not None:
+                queue_update_callback()
+
+            if not should_wait:
+                return device_names
+
+            if interruption_callback is not None:
+                interruption_callback()
+
+    def acquire(
+        self,
+        request_id: str,
+        device: str,
+        interruption_callback: Callable[[], None] | None = None,
+        queue_update_callback: Callable[[], None] | None = None,
+    ) -> None:
+        """
+        Acquire the lock for a single device on behalf of a request.
+
+        If the device is already owned by another request, this call blocks
+        until the lock becomes available.
+
+        Args:
+            request_id (str): request identifier that will own the device lock.
+            device (str): device name to lock.
+            interruption_callback (Callable[[], None] | None, optional):
+                callback invoked while waiting for the lock. Defaults to None.
+            queue_update_callback (Callable[[], None] | None, optional):
+                callback invoked when queue-visible lock state changes. Defaults to None.
+        """
+        self.acquire_many(
+            request_id=request_id,
+            devices=[device],
+            interruption_callback=interruption_callback,
+            queue_update_callback=queue_update_callback,
+        )
+
+    def release_all(self, request_id: str) -> list[str]:
+        """
+        Release all device locks held by a request.
+
+        Args:
+            request_id (str): request identifier whose locks should be released.
+
+        Returns:
+            list[str]: sorted device names whose locks were released.
+        """
+        with self._condition:
+            devices = sorted(self._owner_devices.pop(request_id, set()))
+            for device in devices:
+                if self._device_owners.get(device) == request_id:
+                    self._device_owners.pop(device, None)
+            self._condition.notify_all()
+            return devices
+
+    def get_owned_devices(self, request_id: str) -> list[str]:
+        """
+        Get the devices currently locked by a request.
+
+        Args:
+            request_id (str): request identifier whose locked devices should be returned.
+
+        Returns:
+            list[str]: sorted device names currently owned by the request.
+        """
+        with self._condition:
+            return sorted(self._owner_devices.get(request_id, set()))
+
+    def get_pending_devices(self, request_id: str) -> list[str]:
+        """
+        Get the devices that a request is currently waiting to acquire.
+
+        Args:
+            request_id (str): request identifier whose pending devices should be returned.
+        """
+        with self._condition:
+            return sorted(self._pending_device_locks.get(request_id, set()))
+
+    def _log_waiting_for_device_lock(
+        self, request_id: str, blocked_owners: dict[str, str], next_log_time: float
+    ) -> float:
+        now = time.monotonic()
+        if now < next_log_time:
+            return next_log_time
+
+        waiting_devices = ", ".join(sorted(blocked_owners))
+        owners = ", ".join(
+            f"{device} held by {owner}" for device, owner in sorted(blocked_owners.items())
+        )
+        logger.info(f"Request {request_id} waiting for device locks on {waiting_devices}; {owners}")
+        return now + self.WAIT_LOG_INTERVAL_S

{bec_server-3.151.2 → bec_server-3.152.0}/bec_server/scan_server/direct_scan_worker.py

@@ -81,6 +81,7 @@ class DirectScanWorker:
         queue = self.worker.current_instruction_queue_item
         try:
             with self.worker.device_manager._rpc_method(scan.actions.rpc_call):
+                scan.actions._initialize_scan()
                 for step in SCAN_SEQUENCE:
                     method = getattr(scan, step, None)
                     if not method:
@@ -95,12 +96,27 @@ class DirectScanWorker:
             if not self._prepare_exception_cleanup(queue, exc):
                 return
             self._handle_exception(exc)
+        finally:
+            self._release_scan_locks(scan)
+
         if queue is None:
             return
+
         queue.status = InstructionQueueStatus.COMPLETED
         self.worker.current_instruction_queue_item = None
         self.reset()
 
+    def _release_scan_locks(self, scan: ScanBase | None) -> None:
+        if scan is None:
+            return
+        request_id = scan.scan_info.metadata.get("RID")
+        if request_id is None:
+            return
+        registry = getattr(self.worker.parent, "device_lock_registry", None)
+        if registry is None:
+            return
+        registry.release_all(request_id)
+
     def _prepare_exception_cleanup(
         self, queue: DirectInstructionQueueItem | None, exc: Exception
     ) -> bool:
@@ -176,6 +192,7 @@ class DirectScanWorker:
         Update the queue info for the current instruction queue item.
         This is used to propagate the queue status to the client during the scan execution.
         """
+        logger.info(f"Updating queue info")
         self.worker.current_instruction_queue_item.parent.queue_manager.send_queue_status()
 
     def _propagate_error(self, content: str, exc: Exception):
@@ -253,6 +270,7 @@ class DirectScanWorker:
             else:
                 self.scan.actions._send_scan_status("halted", reason=reason)
 
+        self._release_scan_locks(self.scan)
         queue.status = InstructionQueueStatus.STOPPED
         queue.append_to_queue_history()
         self.worker.parent.queue_manager.queues[self.worker.queue_name].abort()

{bec_server-3.151.2 → bec_server-3.152.0}/bec_server/scan_server/scan_assembler.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import inspect
+from functools import partial
 from typing import TYPE_CHECKING
 
 from bec_lib import messages
@@ -129,18 +130,28 @@ class ScanAssembler:
             scan_cls, scan_info["signature"], resolved_args, resolved_kwargs
         )
 
-        scan_instance = scan_cls(
-            *resolved_args,
-            device_manager=self.device_manager,
-            redis_connector=self.connector,
-            scan_modifier=get_scan_modifier(),
-            metadata=msg.metadata,
-            instruction_handler=self.parent.queue_manager.instruction_handler,
-            scan_id=scan_id,
-            request_inputs=request_inputs,
-            **resolved_kwargs,
+        with self.device_manager._rpc_method(partial(self._raise_on_rpc_call, scan_cls)):
+            scan_instance = scan_cls(
+                *resolved_args,
+                device_manager=self.device_manager,
+                redis_connector=self.connector,
+                scan_modifier=get_scan_modifier(),
+                metadata=msg.metadata,
+                instruction_handler=self.parent.queue_manager.instruction_handler,
+                scan_id=scan_id,
+                request_inputs=request_inputs,
+                **resolved_kwargs,
+            )
+            return scan_instance
+
+    def _raise_on_rpc_call(self, scan_cls, device: str, func_call: str, *args, **kwargs):
+        # This function is used to raise an error if a runtime RPC call is made during scan initialization as it
+        # can lead to unpredictable behavior
+        raise RuntimeError(
+            f"The scan {scan_cls.__name__} attempted to make a runtime RPC call to `{func_call}` on device `{device}`. "
+            f"Please ensure that all runtime RPC calls are made within the scan's scan hooks and not during the scan's initialization."
+            f"If you want to set up a device before the scan starts, move the RPC call to the `prepare_scan` hook of the scan class."
         )
-        return scan_instance
 
     def _assemble_request_inputs(self, scan_cls, args, kwargs) -> dict:
         request_inputs = {}

{bec_server-3.151.2 → bec_server-3.152.0}/bec_server/scan_server/scan_queue.py

@@ -264,17 +264,20 @@ class QueueManager:
                 return instruction_queue
         return None
 
-    def stop_all_devices(self, stop_id: str | list[str] | None = None):
+    def stop_all_devices(
+        self, stop_id: str | list[str] | None = None, devices: list[str] | None = None
+    ):
         """
-        Send a message to the device server to stop all devices.
+        Send a message to the device server to stop devices.
         Args:
             stop_id (str | None): An optional identifier for the stop request.
                 If provided, this ID will be added to the list of stopped requests in the device server to
                 prevent any instructions associated with this ID raising alarms after the stop command is issued.
                 The stop_id can be a scan ID, request ID, or queue ID.
+            devices (list[str] | None): Optional list of devices to stop.
+                `None` means stop all devices, while an empty list means stop no devices.
         """
-        # We send an empty list to indicate that all devices should be stopped
-        msg = messages.VariableMessage(value=[], metadata={})
+        msg = messages.VariableMessage(value=devices, metadata={})
         if stop_id is not None:
             msg.metadata["stop_id"] = stop_id
         self.connector.send(MessageEndpoints.stop_devices(), msg)
@@ -417,7 +420,10 @@ class QueueManager:
                 stop_id = instruction_queue.queue_id
             else:
                 stop_id = instruction_queue.scan_id
-            self.stop_all_devices(stop_id=stop_id)
+            self.stop_all_devices(
+                stop_id=stop_id,
+                devices=self._get_owned_devices_for_instruction_queue(instruction_queue),
+            )
 
     def _cancel_queue_item(
         self, target_queue_item: InstructionQueueItem | DirectInstructionQueueItem, queue: str
@@ -622,6 +628,27 @@ class QueueManager:
             return instr_queue.active_scan.scan_info.scan_id
         return instr_queue.active_request_block.scan_id
 
+    def _get_owned_devices_for_instruction_queue(
+        self, instruction_queue: InstructionQueueItem | DirectInstructionQueueItem
+    ) -> list[str] | None:
+        registry = getattr(self.parent, "device_lock_registry", None)
+        if registry is None:
+            return None if isinstance(instruction_queue, InstructionQueueItem) else []
+        if isinstance(instruction_queue, DirectInstructionQueueItem):
+            if instruction_queue.active_scan is None:
+                return []
+            request_id = instruction_queue.active_scan.scan_info.metadata.get("RID")
+        else:
+            if instruction_queue.active_request_block is None:
+                return None
+            request_id = instruction_queue.active_request_block.RID
+        if request_id is None:
+            return None if isinstance(instruction_queue, InstructionQueueItem) else []
+        devices = registry.get_owned_devices(request_id)
+        if isinstance(instruction_queue, InstructionQueueItem) and not devices:
+            return None
+        return devices
+
     def _wait_for_queue_to_appear_in_history(
         self, scan_id, queue, timeout=60
     ) -> InstructionQueueItem:
@@ -1176,6 +1203,8 @@ class RequestBlock:
             scan_number=self.scan_number,
             scan_id=self.scan_id,
             report_instructions=self.scan_report_instructions,
+            owned_device_locks=[],
+            pending_device_locks=[],
         )
 
 
@@ -1672,6 +1701,8 @@ class DirectInstructionQueueItem:
             scan_number=self._get_scan_number(scan),
             scan_id=scan.scan_info.scan_id,
             report_instructions=scan.scan_info.scan_report_instructions,
+            owned_device_locks=scan.actions.get_owned_device_locks(),
+            pending_device_locks=scan.actions.get_pending_device_locks(),
         )
 
     @property

{bec_server-3.151.2 → bec_server-3.152.0}/bec_server/scan_server/scan_server.py

@@ -18,6 +18,7 @@ from bec_server.procedures.manager import ProcedureManager
 from bec_server.procedures.subprocess_worker import SubProcessWorker
 
 from .beamline_state_manager import BeamlineStateManager
+from .device_lock_registry import DeviceLockRegistry
 from .scan_assembler import ScanAssembler
 from .scan_guard import ScanGuard
 from .scan_manager import ScanManager
@@ -32,6 +33,7 @@ logger = bec_logger.logger
 class ScanServer(BECService):
     def __init__(self, config: ServiceConfig, connector_cls: type[RedisConnector]):
         super().__init__(config, connector_cls, unique_service=True)
+        self.device_lock_registry = DeviceLockRegistry()
         self._start_scan_manager()
         self._start_device_manager()
         self._start_queue_manager()

{bec_server-3.151.2 → bec_server-3.152.0}/bec_server/scan_server/scans/legacy_scans.py

@@ -256,6 +256,7 @@ class RequestBase(ABC):
         *args,
         device_manager: DeviceManagerBase = None,
         monitored: list = None,
+        on_request: list = None,
         parameter: dict = None,
         metadata: dict = None,
         instruction_handler: InstructionHandler = None,
@@ -283,7 +284,7 @@ class RequestBase(ABC):
         self.readout_priority = {
             "monitored": monitored if monitored is not None else [],
             "baseline": [],
-            "on_request": [],
+            "on_request": on_request if on_request is not None else [],
             "async": [],
         }
         self.update_readout_priority()

{bec_server-3.151.2 → bec_server-3.152.0}/bec_server/scan_server/scans/move.py

@@ -71,6 +71,8 @@ class MoveScan(ScanBase):
         self.motors = list(self.motor_args_bundles.keys())
         self.relative = relative
 
+        self.actions.acquire_device_lock(self.motors)
+
         # Update the default scan info with provided parameters.
         self.update_scan_info(relative=relative, scan_report_devices=self.motors)