Observation Supervisor

class ska_csp_lmc_common.supervision.generic_supervisor.ObservationSupervisor(*, policy: 'ScanConsistencyPolicy' | None, update_attribute: Callable[[str, Any], None], logger: logging.Logger, debounce_s: float = 0, max_latency_s: float = 0.2, reconcile_timeout_s: float = 0.5)

Bases: object

Base class implementing debounce/max-latency supervision timing.

This class manages a background worker thread that waits for observation updates and triggers state evaluation according to debounce and maximum latency constraints.

It also supports a reconciliation phase, during which evaluation is temporarily driven by incoming events or by a reconciliation timeout, instead of normal debounce/max-latency timing.

stop() → None

Stop the background supervision thread and wait for completion.

This method signals the internal worker thread to terminate, wakes it if it is waiting on the condition variable, and blocks until the thread exits cleanly.

on_observation_update(immediate: bool = False) → None

Notify the supervisor that a new observation update is available.

The update is marked as pending and will be evaluated according to the timing rules of the supervisor. When immediate is True, the debounce delay is bypassed and the next evaluation is forced as soon as possible.

Parameters:

immediate – If True, force the next evaluation without waiting for the debounce delay.

clear_consistency_fault() → None

Clear any consistency fault currently exposed by the supervisor.

Subclasses must implement this method to reset fault-related attributes or status messages published externally.

Raises:

NotImplementedError – Always, unless overridden by a subclass.

_start_reconciliation_window_locked(timeout_s: float) → None

Start a reconciliation window. During reconciliation, normal debounce and max-latency timing are bypassed. Any new event may trigger an immediate evaluation, and if no event arrives before the deadline, a forced evaluation is performed when the timeout expires.

This internal helper assumes the caller already owns the condition-variable lock and therefore does not acquire it.

Parameters:

timeout_s – Duration of the reconciliation window, in seconds.

_stop_reconciliation_window_locked() → None

Stop the active reconciliation window.

This method must be called while holding the condition lock.

_tick_loop() → None

Run the background supervision loop.

The loop waits for updates or reconciliation activity and then decides when to invoke _evaluate_and_publish().

Normal mode: - evaluation is driven by debounce and max-latency timers

Reconciliation mode: - any new event triggers immediate evaluation - if no event arrives, one forced evaluation happens at the

reconciliation deadline

  • debounce and max-latency are temporarily bypassed

_evaluate_and_publish(*, force: bool = False, reconcile_timeout: bool = False) → EvaluationOutcome

Evaluate the current candidate state and publish any result.

Subclasses must implement the domain-specific evaluation logic.

Parameters:

  • force – If true, force immediate evaluation regardless of normal debounce timing.

  • reconcile_timeout – If true, the current evaluation is being performed because the reconciliation window expired.

Returns:

The outcome of the evaluation cycle.

Raises:

NotImplementedError – If not overridden by a subclass.

_wait_until_evaluation_needed_locked() → tuple[bool, bool, int] | None

Wait until a new evaluation cycle should start.

This method must be called while holding the condition lock.

Returns:

None if the supervisor is stopping; otherwise a tuple (force_evaluate, reconcile_timeout, evaluation_version) describing the next evaluation cycle.

_handle_evaluation_outcome_locked(*, outcome: EvaluationOutcome, evaluation_version: int, reconcile_timeout: bool) → None

Update internal state after an evaluation completes.

This method must be called while holding the condition lock.

Parameters:

  • outcome – Outcome returned by the evaluation step.

  • evaluation_version – Pending-update version captured before the evaluation started.

  • reconcile_timeout – Whether the evaluation was triggered by expiration of the reconciliation window.

_clear_pending_locked() → None

Clear bookkeeping for pending updates.

This method must be called while holding the condition lock.