spectre-core 0.0.22__py3-none-any.whl → 0.0.23__py3-none-any.whl

spectre_core/jobs/_jobs.py

@@ -3,109 +3,138 @@
 # SPDX-License-Identifier: GPL-3.0-or-later
 
 from logging import getLogger
+
 _LOGGER = getLogger(__name__)
 
 import time
 
 from ._workers import Worker
+from ._duration import Duration
+
 
 class Job:
-    """Represents a collection of workers that run long-running tasks as 
+    """Represents a collection of workers that run long-running tasks as
     multiprocessing processes.
 
-    A `Job` manages the lifecycle of its workers, including starting, 
-    monitoring, and terminating them.
+    A `Job` manages the lifecycle of its workers, including starting,
+    monitoring, and killing them.
     """
-    def __init__(
-        self,
-        workers: list[Worker]
-    ) -> None:
+
+    def __init__(self, workers: list[Worker]) -> None:
         """Initialise a `Job` with a list of workers.
 
         :param workers: A list of `Worker` instances to manage as part of the job.
         """
         self._workers = workers
 
+    @property
+    def workers_are_alive(self) -> bool:
+        """Returns True if all managed workers are alive, and False otherwise."""
+        return all([worker.is_alive for worker in self._workers])
 
     def start(
         self,
     ) -> None:
         """Tell each worker to call their functions in the background as multiprocessing processes."""
+        if self.workers_are_alive:
+            raise RuntimeError("A job cannot be started twice.")
         for worker in self._workers:
             worker.start()
-            
-            
-    def terminate(
+
+    def kill(
         self,
     ) -> None:
-        """Tell each worker to terminate their processes, if the processes are still running."""
-        _LOGGER.info("Terminating workers...")
+        """Tell each worker to kill their processes, if the processes are still running."""
+        _LOGGER.info("Killing workers...")
         for worker in self._workers:
-            if worker.process.is_alive():
-                worker.process.terminate()
-                worker.process.join()
-        _LOGGER.info("All workers successfully terminated")
-        
-        
-    def monitor(
+            if worker.is_alive:
+                worker.kill()
+
+        _LOGGER.info("All workers successfully killed")
+
+    def restart(
         self,
-        total_runtime: float, 
-        force_restart: bool = False
+    ) -> None:
+        """Tell each worker to restart it's process."""
+        for worker in self._workers:
+            worker.restart()
+
+    def monitor(
+        self, total_runtime: float, force_restart: bool = False, max_restarts: int = 5
     ) -> None:
         """
         Monitor the workers during execution and handle unexpected exits.
 
-        Periodically checks worker processes within the specified runtime duration. 
+        Periodically checks worker processes within the specified runtime duration.
         If a worker exits unexpectedly:
         - Restarts all workers if `force_restart` is True.
-        - Terminates all workers and raises an exception if `force_restart` is False.
+        - Kills all workers and raises an exception if `force_restart` is False.
 
         :param total_runtime: Total time to monitor the workers, in seconds.
-        :param force_restart: Whether to restart all workers if one exits unexpectedly.
+        :param force_restart: Whether to restart all workers if one dies unexpectedly.
+        :param max_restarts: Maximum number of times workers can be restarted before giving up and killing all workers.
+        Only applies when force_restart is True. Defaults to 5.
         :raises RuntimeError: If a worker exits and `force_restart` is False.
         """
         _LOGGER.info("Monitoring workers...")
         start_time = time.time()
 
+        restarts_remaining = max_restarts
         try:
+            # Check that the elapsed time since the job started is within the total runtime configured by the user.
             while time.time() - start_time < total_runtime:
                 for worker in self._workers:
-                    if not worker.process.is_alive():
-                        error_message = f"Worker with name `{worker.name}` unexpectedly exited."
+                    if not worker.is_alive:
+                        error_message = (
+                            f"Worker with name `{worker.name}` unexpectedly exited."
+                        )
                         _LOGGER.error(error_message)
                         if force_restart:
-                            # Restart all workers
-                            for worker in self._workers:
-                                worker.restart()
+                            if restarts_remaining > 0:
+                                _LOGGER.info(
+                                    f"Attempting restart ({restarts_remaining} restarts remaining)..."
+                                )
+                                restarts_remaining -= 1
+                                self.restart()
+
+                            else:
+                                error_message = (
+                                    f"Maximum number of restarts has been reached: {max_restarts}. "
+                                    f"Killing all workers."
+                                )
+                                self.kill()
+                                raise RuntimeError(error_message)
                         else:
-                            self.terminate()
+                            self.kill()
                             raise RuntimeError(error_message)
-                time.sleep(1)  # Poll every second
+                time.sleep(Duration.ONE_DECISECOND)  # Poll every 0.1 seconds
 
-            _LOGGER.info("Session duration reached. Terminating workers...")
-            self.terminate()
+            # If the jobs total runtime has elapsed, kill all the workers
+            _LOGGER.info("Job complete. Killing workers... ")
+            self.kill()
 
         except KeyboardInterrupt:
-            _LOGGER.info("Keyboard interrupt detected. Terminating workers...")
-            self.terminate()
+            _LOGGER.info("Keyboard interrupt detected. Killing workers...")
+            self.kill()
+
 
-    
 def start_job(
     workers: list[Worker],
     total_runtime: float,
-    force_restart: bool = False
+    force_restart: bool = False,
+    max_restarts: int = 5,
 ) -> None:
     """Create and run a job with the specified workers.
 
-    Starts the workers, monitors them for the specified runtime, and handles 
+    Starts the workers, monitors them for the specified runtime, and handles
     unexpected exits according to the `force_restart` policy.
 
     :param workers: A list of `Worker` instances to include in the job.
-    :param total_runtime: Total time to monitor the job, in seconds.
-    :param force_restart: Whether to restart all workers if one exits unexpectedly.
-    Defaults to False.
+    :param total_runtime: Total time to monitor the workers, in seconds.
+    :param force_restart: Whether to restart all workers if one dies unexpectedly.
+    :param max_restarts: Maximum number of times workers can be restarted before giving up and killing all workers.
+    Only applies when force_restart is True. Defaults to 5.
     """
     job = Job(workers)
     job.start()
-    job.monitor(total_runtime, force_restart)
-
+    job.monitor(total_runtime, force_restart, max_restarts)

spectre_core/jobs/_workers.py

@@ -3,22 +3,19 @@
 # SPDX-License-Identifier: GPL-3.0-or-later
 
 from logging import getLogger
+
 _LOGGER = getLogger(__name__)
 
-from functools import wraps
 import time
-from typing import Callable, TypeVar, ParamSpec
+from typing import Callable
 import multiprocessing
 
-from spectre_core.logs import configure_root_logger, log_call, ProcessType
-from spectre_core.capture_configs import CaptureConfig
-from spectre_core.receivers import get_receiver, ReceiverName
-from spectre_core.post_processing import start_post_processor
+from spectre_core.logs import configure_root_logger, ProcessType
+from ._duration import Duration
 
 
 def _make_daemon_process(
-    name: str, 
-    target: Callable[[], None]
+    name: str, target: Callable[[], None]
 ) -> multiprocessing.Process:
     """
     Creates and returns a daemon `multiprocessing.Process` instance.
@@ -27,21 +24,16 @@ def _make_daemon_process(
     :param target: The function to execute in the process.
     :return: A `multiprocessing.Process` instance configured as a daemon.
     """
-    return multiprocessing.Process(target=target,
-                                   name=name,
-                                   daemon=True)
+    return multiprocessing.Process(target=target, name=name, daemon=True)
 
 
 class Worker:
     """A lightweight wrapper for a `multiprocessing.Process` daemon.
-    
+
     Provides a very simple API to start, and restart a multiprocessing process.
     """
-    def __init__(
-        self,
-        name: str,
-        target: Callable[[], None]
-    ) -> None:
+
+    def __init__(self, name: str, target: Callable[[], None]) -> None:
         """Initialise a `Worker` instance.
 
         :param name: The name assigned to the process.
@@ -51,121 +43,79 @@ class Worker:
         self._target = target
         self._process = _make_daemon_process(name, target)
 
-
     @property
-    def name(
-        self
-    ) -> str:
+    def name(self) -> str:
         """Get the name of the worker process.
 
         :return: The name of the multiprocessing process.
         """
         return self._process.name
-    
-    
-    @property
-    def process(
-        self
-    ) -> multiprocessing.Process:
-        """Access the underlying multiprocessing process.
 
-        :return: The wrapped `multiprocessing.Process` instance.
-        """
-        return self._process
+    @property
+    def is_alive(self) -> bool:
+        """Return whether the managed process is alive."""
+        return self._process.is_alive()
 
-    
-    def start(
-        self
-    ) -> None:
+    def start(self) -> None:
         """Start the worker process.
 
         This method runs the `target` in the background as a daemon.
         """
+        if self.is_alive:
+            raise RuntimeError("A worker cannot be started twice.")
+
         self._process.start()
 
+    def kill(self) -> None:
+        """Kill the managed process."""
+        if not self.is_alive:
+            raise RuntimeError("Cannot kill a process which is not alive.")
+
+        self._process.kill()
 
-    def restart(
-        self
-    ) -> None:
+    def restart(self) -> None:
         """Restart the worker process.
 
-        Terminates the existing process if it is alive and then starts a new process
-        after a brief pause. 
+        Kills the existing process if it is alive and then starts a new process
+        after a brief pause.
         """
         _LOGGER.info(f"Restarting {self.name} worker")
-        if self._process.is_alive():
+        if self.is_alive:
             # forcibly stop if it is still alive
-            self._process.terminate()
-            self._process.join()
+            self.kill()
+
         # a moment of respite
-        time.sleep(1)
+        time.sleep(0.5 * Duration.ONE_SECOND)
+
         # make a new process, as we can't start the same process again.
         self._process = _make_daemon_process(self._name, self._target)
         self.start()
 
 
-P = ParamSpec("P")
-T = TypeVar("T", bound=Callable[..., None])
+# TODO: Somehow statically type check that `args` match the arguments to `target`
 def make_worker(
-    name: str
-) -> Callable[[Callable[P, None]], Callable[P, Worker]]:
+    name: str,
+    target: Callable[..., None],
+    args: tuple = (),
+    configure_logging: bool = True,
+) -> Worker:
+    """Create a `Worker` instance to manage a target function in a multiprocessing background daemon process.
+
+    This function returns a `Worker` that is configured to run the given target function with the provided arguments
+    in a separate process. The worker is not started automatically; you must call `start()` to call the target.  The target should not return anything,
+    as its return value will be discarded.
+
+    :param name: Human-readable name for the worker process.
+    :param target: The function to be executed by the worker process.
+    :param args: Arguments to pass to the target function.
+    :param configure_root_logger: If True, configure the root logger to write log events to file. Defaults to True.
+    :return: A `Worker` instance managing the background process (not started).
     """
-    Turns a function into a worker.
 
-    This decorator wraps a function, allowing it to run in a separate process
-    managed by a `Worker` object. Use it to easily create long-running or
-    isolated tasks without directly handling multiprocessing.
+    def _worker_target() -> None:
+        if configure_logging:
+            configure_root_logger(ProcessType.WORKER)
+        _LOGGER.info(args)
+        target(*args)
 
-    :param name: A human-readable name for the worker process.
-    :return: A decorator that creates a `Worker` to run the function in its own process.
-    """
-
-    def decorator(
-        func: Callable[P, None]
-    ) -> Callable[P, Worker]:
-        @wraps(func)
-        def wrapper(*args: P.args, **kwargs: P.kwargs) -> Worker:
-            # Worker target funcs must have no arguments
-            def target():
-                configure_root_logger(ProcessType.WORKER)
-                func(*args, **kwargs)
-            return Worker(name, target)
-        return wrapper
-    return decorator
-
-
-@make_worker("capture")
-@log_call
-def do_capture(
-    tag: str,
-) -> None:
-    """Start capturing data from an SDR in real time.
-
-    :param tag: The capture config tag.
-    """
-    _LOGGER.info((f"Reading capture config with tag '{tag}'"))
-
-    # load the receiver and mode from the capture config file
-    capture_config = CaptureConfig(tag)
-
-    _LOGGER.info((f"Starting capture with the receiver '{capture_config.receiver_name}' "
-                  f"operating in mode '{capture_config.receiver_mode}' "
-                  f"with tag '{tag}'"))
-
-    name = ReceiverName( capture_config.receiver_name )
-    receiver = get_receiver(name,
-                            capture_config.receiver_mode)
-    receiver.start_capture(tag)
-
-
-@make_worker("post_processing")
-@log_call
-def do_post_processing(
-    tag: str,
-) -> None:
-    """Start post processing SDR data into spectrograms in real time.
-
-    :param tag: The capture config tag.
-    """
-    _LOGGER.info(f"Starting post processor with tag '{tag}'")
-    start_post_processor(tag)
+    return Worker(name, _worker_target)

spectre_core/logs/__init__.py

@@ -12,6 +12,11 @@ from ._logs import Log, Logs, parse_log_base_file_name
 
 
 __all__ = [
-    "log_call", "configure_root_logger", "Log", "Logs", "ProcessType",
-    "get_root_logger_state", "parse_log_base_file_name"
+    "log_call",
+    "configure_root_logger",
+    "Log",
+    "Logs",
+    "ProcessType",
+    "get_root_logger_state",
+    "parse_log_base_file_name",
 ]

spectre_core/logs/_configure.py

@@ -12,11 +12,8 @@ from ._logs import Log
 from ._process_types import ProcessType
 
 
-def configure_root_logger(
-    process_type: ProcessType, 
-    level: int = logging.INFO
-) -> str:
-    """Configures the root logger to write logs to a file named based on 
+def configure_root_logger(process_type: ProcessType, level: int = logging.INFO) -> str:
+    """Configures the root logger to write logs to a file named based on
     the process type, process ID, and the current system time.
 
     :param process_type: Indicates the type of process, as defined by `ProcessType`.
@@ -27,36 +24,35 @@ def configure_root_logger(
     # get the star time of the log
     system_datetime = datetime.now()
     start_time = system_datetime.strftime(TimeFormat.DATETIME)
-    
+
     # extract the process identifier, and cast as a string
-    pid = str( os.getpid() )
-    
+    pid = str(os.getpid())
+
     # create a file handler representing the log file
-    log = Log(start_time, 
-              pid, 
-              process_type)
+    log = Log(start_time, pid, process_type)
     log.make_parent_dir_path()
 
     # get the root logger and set its level.
     logger = logging.getLogger()
     logger.setLevel(level)
-    
+
     # remove existing handlers
     for handler in logger.handlers:
         logger.removeHandler(handler)
-        
+
     # Set up a file handler and add it to the root logger
     file_handler = logging.FileHandler(log.file_path)
     file_handler.setLevel(level)
-    formatter = logging.Formatter("[%(asctime)s] [%(levelname)8s] --- %(message)s (%(name)s:%(lineno)s)")
+    formatter = logging.Formatter(
+        "[%(asctime)s] [%(levelname)8s] --- %(message)s (%(name)s:%(lineno)s)"
+    )
     file_handler.setFormatter(formatter)
     logger.addHandler(file_handler)
 
     return log.file_path
 
 
-def get_root_logger_state(
-) -> Tuple[bool, int]:
+def get_root_logger_state() -> Tuple[bool, int]:
     """Get the state of the root logger.
 
     :return: Whether the root logger has any handlers, and the level of the root logger.
@@ -64,4 +60,4 @@ def get_root_logger_state(
     root_logger = logging.getLogger()
     if root_logger.handlers:
         return True, root_logger.level
-    return False, logging.NOTSET
+    return False, logging.NOTSET

spectre_core/logs/_decorators.py

@@ -10,9 +10,9 @@ from functools import wraps
 P = ParamSpec("P")
 # TypeVar for capturing the return type of the function
 RT = TypeVar("RT")
-def log_call(
-    func: Callable[P, RT]
-) -> Callable[P, RT]:
+
+
+def log_call(func: Callable[P, RT]) -> Callable[P, RT]:
     """Decorator to log the execution of a function.
 
     Logs an informational message when the decorated function is called,
@@ -21,6 +21,7 @@ def log_call(
     :param func: The function to be decorated.
     :return: The decorated function with added logging behaviour.
     """
+
     @wraps(func)
     def wrapper(*args: P.args, **kwargs: P.kwargs) -> RT:
         logger = logging.getLogger(func.__module__)
@@ -30,4 +31,5 @@ def log_call(
         except Exception as e:
             logger.error(f"Error in function: {func.__name__}", exc_info=True)
             raise
-    return wrapper
+
+    return wrapper