microscope.device_server Namespace Reference

Classes
class	DeviceServer
class	DeviceServerOptions
class	Filter

Functions
def	device (typing.Callable cls, str host, int port, typing.Mapping[str, typing.Any] conf={}, typing.Optional[str] uid=None)
def	serve_devices (devices, DeviceServerOptions options, exit_event=None)
def	validate_devices (configfile)
int	main (typing.Sequence[str] argv)
None	__main__ ()

Variables
	multiprocessing = multiprocessing.get_context("spawn")
	SERIALIZER
	REQUIRE_EXPOSE

Function Documentation

__main__()

None microscope.device_server.__main__

(

)

Definition at line 624 of file device_server.py.

def __main__() -> None:
    # Kept for backwards compatibility.  It keeps the setuptools
    # scripts from older editable mode installations.  Will be safe to
    # remove soon.
    _setuptools_entry_point()
 
 

device()

def microscope.device_server.device	(	typing.Callable	cls,
		str	host,
		int	port,
		typing.Mapping[str, typing.Any]	conf = {},
		typing.Optional[str]	uid = None
	)

Define devices and where to serve them.

A device definition for use in deviceserver config files.

Args:
    cls: :class:`Device` class of device to serve or function that
        returns a map of `Device` instances to wanted Pyro ID.
        The device class will be constructed, or the function will
        be called, with the arguments in ``conf``.
    host: hostname or ip address serving the devices.
    port: port number used to serve the devices.
    conf: keyword arguments for ``cls``.  The device or function
        are effectively constructed or called with `cls(**conf)`.
    uid: used to identify "floating" devices (see documentation
        for :class:`FloatingDeviceMixin`).  This must be specified
        if ``cls`` is a floating device.

Example

.. code-block:: python

    def construct_devices() -> typing.Dict[str, Device]:
        camera = Camera(some, arguments)
        # ... any other configuration that might be wanted
        return {'RedCamera': camera}

    DEVICES = [
        # passing a function that returns devices
        device(construct_devices, '127.0.0.1', 8000),
        # passing a Device class
        device(Camera, '127.0.0.1', 8001,
               conf={'kwarg1': some, 'kwarg2': arguments})
    ]

Definition at line 81 of file device_server.py.

):
    """Define devices and where to serve them.
 
    A device definition for use in deviceserver config files.
 
    Args:
        cls: :class:`Device` class of device to serve or function that
            returns a map of `Device` instances to wanted Pyro ID.
            The device class will be constructed, or the function will
            be called, with the arguments in ``conf``.
        host: hostname or ip address serving the devices.
        port: port number used to serve the devices.
        conf: keyword arguments for ``cls``.  The device or function
            are effectively constructed or called with `cls(**conf)`.
        uid: used to identify "floating" devices (see documentation
            for :class:`FloatingDeviceMixin`).  This must be specified
            if ``cls`` is a floating device.
 
    Example
 
    .. code-block:: python
 
        def construct_devices() -> typing.Dict[str, Device]:
            camera = Camera(some, arguments)
            # ... any other configuration that might be wanted
            return {'RedCamera': camera}
 
        DEVICES = [
            # passing a function that returns devices
            device(construct_devices, '127.0.0.1', 8000),
            # passing a Device class
            device(Camera, '127.0.0.1', 8001,
                   conf={'kwarg1': some, 'kwarg2': arguments})
        ]
 
    """
    if not callable(cls):
        raise TypeError("cls must be a callable")
    elif isinstance(cls, type):
        if issubclass(cls, FloatingDeviceMixin) and uid is None:
            raise TypeError("uid must be specified for floating devices")
        elif not issubclass(cls, FloatingDeviceMixin) and uid is not None:
            raise TypeError("uid must not be given for non floating devices")
    return dict(cls=cls, host=host, port=int(port), uid=uid, conf=conf)
 
 

main()

int microscope.device_server.main

(

typing.Sequence[str]

argv

)

Definition at line 594 of file device_server.py.

def main(argv: typing.Sequence[str]) -> int:
    options = _parse_cmd_line_args(argv[1:])
 
    root_logger = logging.getLogger()
    root_logger.setLevel(options.logging_level)
 
    stderr_handler = StreamHandler(sys.stderr)
    stderr_handler.setFormatter(_create_log_formatter("device-server"))
    root_logger.addHandler(stderr_handler)
 
    root_logger.addFilter(Filter())
 
    devices = validate_devices(options.config_fpath)
 
    serve_devices(devices, options)
 
    return 0
 
 

serve_devices()

def microscope.device_server.serve_devices	(		devices,
		DeviceServerOptions	options,
			exit_event = None
	)

Definition at line 393 of file device_server.py.

def serve_devices(devices, options: DeviceServerOptions, exit_event=None):
    # We make changes to `devices` (would be great if we didn't had
    # to) so make a a copy of it because we don't want to make those
    # changes on the caller.  See original issue on #211 and PRs #212
    # and #217 (most discussion happens on #212).
    devices = copy.deepcopy(devices)
 
    root_logger = logging.getLogger()
 
    log_handler = RotatingFileHandler("__MAIN__.log")
    log_handler.setFormatter(_create_log_formatter("device-server"))
    root_logger.addHandler(log_handler)
 
    # An event to trigger clean termination of subprocesses. This is the
    # only way to ensure devices are shut down properly when processes
    # exit, as __del__ is not necessarily called when the interpreter exits.
    if exit_event is None:
        exit_event = multiprocessing.Event()
 
    servers = (
        []
    )  # DeviceServers instances that we need to wait for when exiting
 
    # Child processes inherit signal handling from the parent so we
    # need to make sure that only the parent process sets the exit
    # event and waits for the DeviceServers to exit.  See issue #9.
    # This won't work behind a Windows service wrapper, so we deal with
    # clean shutdown on win32 elsewhere.
    parent = multiprocessing.current_process()
 
    def term_func(sig, frame):
        """Terminate subprocesses cleanly."""
        if parent == multiprocessing.current_process():
            _logger.debug("Shutting down all servers.")
            exit_event.set()
            # Join keep_alive_thread so that it can't modify the list
            # of servers.
            keep_alive_thread.join()
            for this_server in servers:
                this_server.join()
            sys.exit()
 
    if sys.platform != "win32":
        signal.signal(signal.SIGTERM, term_func)
        signal.signal(signal.SIGINT, term_func)
 
    # Group devices by class.
    by_class = {}
    for dev in devices:
        by_class[dev["cls"]] = by_class.get(dev["cls"], []) + [dev]
 
    if not by_class:
        _logger.warning("No valid devices specified. Maybe an empty list?")
 
    for cls, devs in by_class.items():
        # Floating devices are devices that can only be identified
        # after having been initialized, so the constructor will
        # return any device that it supports.  To work around this we
        # map all device uid to host/port first.  After the
        # DeviceServer constructs the device, it can check on the map
        # where to serve it.  For non floating devices that
        # information is part of the device definition, no map is
        # needed.
        uid_to_host = {}
        uid_to_port = {}
        if isinstance(cls, type) and issubclass(cls, FloatingDeviceMixin):
            # In addition to the maps of uid to host/port, floating
            # devices SDKs need the number of devices to index them.
            count = 0
            for dev in devs:
                uid = dev["uid"]
                uid_to_host[uid] = dev["host"]
                uid_to_port[uid] = dev["port"]
 
                dev["conf"]["index"] = count
                count += 1
 
        for dev in devs:
            servers.append(
                DeviceServer(
                    dev,
                    options,
                    uid_to_host,
                    uid_to_port,
                    exit_event=exit_event,
                )
            )
            servers[-1].start()
 
    # Main thread must be idle to process signals correctly, so use another
    # thread to check DeviceServers, restarting them where necessary. Define
    # the thread target here so that it can access variables in __main__ scope.
    def keep_alive():
        """Keep DeviceServers alive."""
        while not exit_event.is_set():
            for s in servers:
                if s.is_alive():
                    continue
                else:
                    _logger.info(
                        "DeviceServer Failure. Process %s is dead with"
                        " exitcode %s. Restarting...",
                        s.pid,
                        s.exitcode,
                    )
                    servers.remove(s)
                    servers.append(s.clone())
 
                    try:
                        s.join(30)
                    except:
                        _logger.error("... could not join PID %s.", s.pid)
                    else:
                        old_pid = s.pid
                        del s
                        servers[-1].start()
                        _logger.info(
                            "... DeviceServer with PID %s restarted"
                            " as PID %s.",
                            old_pid,
                            servers[-1].pid,
                        )
            if not servers:
                # Log and exit if no servers running. May want to change this
                # if we add some interface to interactively restart servers.
                _logger.info("No servers running. Exiting.")
                exit_event.set()
            else:
                try:
                    time.sleep(5)
                except (KeyboardInterrupt, IOError):
                    pass
 
    keep_alive_thread = Thread(target=keep_alive)
    keep_alive_thread.start()
 
    _logger.info("Device Server started. Press Ctrl+C to exit.")
    while not exit_event.is_set():
        try:
            time.sleep(5)
        except (KeyboardInterrupt, IOError):
            _logger.debug("KeyboardInterrupt or IOError")
            exit_event.set()
 
    _logger.debug("Shutting down servers ...")
    while servers:
        for s in servers:
            if not s.is_alive():
                servers.remove(s)
                del s
        time.sleep(1)
    _logger.info(" ... No more servers running.")
    _logger.debug("Joining threads ...")
    keep_alive_thread.join()
    _logger.debug("... Threads joined. Exiting.")
    return
 
 

validate_devices()

def microscope.device_server.validate_devices

(

configfile

)

Definition at line 583 of file device_server.py.

def validate_devices(configfile):
    config = _load_source(configfile)
    try:
        devices = getattr(config, "DEVICES")
    except AttributeError:
        raise Exception("No 'DEVICES=...' in config file.")
    if not isinstance(devices, Iterable):
        raise Exception("Error in config: DEVICES should be an iterable.")
    return devices
 
 

Variable Documentation

multiprocessing

microscope.device_server.multiprocessing = multiprocessing.get_context("spawn")

Definition at line 66 of file device_server.py.

REQUIRE_EXPOSE

microscope.device_server.REQUIRE_EXPOSE

Definition at line 78 of file device_server.py.

SERIALIZER

microscope.device_server.SERIALIZER

Definition at line 71 of file device_server.py.