saturnin.component.controller¶

Saturnin service controllers.

This module provides classes for managing the lifecycle of Saturnin services. Controllers are responsible for starting, stopping, and configuring services, as well as handling communication with them using the Internal Component Control Protocol (ICCP). It offers different controller implementations, such as DirectController (for in-process execution) and ThreadController (for execution in a separate thread).

Constants and variables¶

saturnin.component.controller.SVC_CTRL: Final[str] = 'iccp'¶: Service control channel name

Functions¶

saturnin.component.controller.service_thread(service: ServiceInfo, config: Config, ctrl_addr: ZMQAddress, peer_uid: UUID | None = None)[source]¶

Target function for running a service within a separate thread.

This function handles the instantiation, initialization, warm-up, and execution of a service. It also manages basic ICCP communication for reporting startup errors back to the controller via a direct ZMQ DEALER socket connection.

Parameters:

service (ServiceInfo) – The ServiceInfo object describing the service to run.
config (Config) – The Config object for the service.
ctrl_addr (ZMQAddress) – The ZMQ address of the controller’s ICCP channel.
peer_uid (UUID | None) – The peer UID to be used by the service instance.

Classes¶

class saturnin.component.controller.ServiceExecConfig(name: str)[source]¶

Bases: Config

Service executor configuration.

Parameters:: name (str) – Default conf. section name

agent: UUIDOption¶: Agent (service) identification

class saturnin.component.controller.ServiceController(*args, **kwargs)[source]¶

Bases: TracedMixin

Base class for service controllers.

This class provides common functionality for managing a service’s lifecycle, including configuration loading and basic state tracking. It’s intended to be subclassed by controllers that implement specific execution strategies (e.g., in-process, separate thread, separate process).

Parameters:

service – The ServiceInfo object for the service to be controlled.
name – Optional name for this controller instance (defaults to the service name).
peer_uid – Peer ID, None means that newly generated UUID type 1 should be used.
manager – Optional ChannelManager to use for ICCP communication. If None, a new one is created when needed.

configure(config: ConfigParser, section: str | None = None) → None[source]¶

Loads and validates service configuration, and ensures that Saturnin facilities required by service are available and properly configured.

Parameters:

config (ConfigParser) – ConfigParser instance with service configuration.
section (str | None) – Name of section with service configuration. If not present, uses ServiceContainer.name value.

Return type:

None

config: Config¶

ctrl_addr: ZMQAddress¶

details: list[str]¶

endpoints: dict[str, list[ZMQAddress]]¶

mngr: ChannelManager¶

name: str¶

outcome: Outcome¶

peer: PeerDescriptor¶

peer_uid: UUID¶

service: ServiceInfo¶

class saturnin.component.controller.DirectController(*args, **kwargs)[source]¶

Bases: ServiceController

Service controller that starts and runs the service in the current thread.

This controller is suitable for scenarios where the service is expected to run directly within the calling process. The start method will block until the service terminates. It includes a SIGINT handler to allow graceful shutdown of the service when run interactively. ICCP communication is primarily used for the initial handshake and final status reporting, as ongoing interaction is limited by the single-threaded execution.

Important

The service could be stopped only via automatically installed SIGINT handler.

handle_stop_controller(exc: Exception) → None[source]¶

Called when controller should stop its operation due to error condition.

Parameters:: exc (Exception) – Exception that describes the reason why component should stop.
Return type:: None

start(*, timeout: int = 10000) → None[source]¶

Start the service.

Parameters:: timeout (int) – Timeout in milliseconds to wait for the initial READY message from the service. Defaults to 1000ms.
Return type:: None

Important

Will not return until service is stopped via SIGINT, or exception is raised.

Raises:

ServiceError – If there’s an ICCP protocol error, an invalid response from the service, or the service reports an error during startup.
TimeoutError – If the service does not send a READY message within the specified timeout.

Parameters:

timeout (int)

Return type:

None

stop_signal_handler(signum: int, param) → None[source]¶

The signal.signal SIGINT handler that sends ICCP STOP message to the service.

Parameters:: signum (int)
Return type:: None

class saturnin.component.controller.ThreadController(*args, **kwargs)[source]¶

Bases: ServiceController

Service controller that starts and runs the service in a separate thread.

This controller allows the main application to continue execution while the service runs in the background. It uses ICCP for the full lifecycle management of the service, including starting, stopping, and receiving status updates.

Parameters:

service – The ServiceInfo object for the service to be controlled.
name – Container name.
peer_uid – Peer ID, None means that newly generated UUID type 1 should be used.

handle_stop_controller(exc: Exception) → None[source]¶

Called when controller should stop its operation due to error condition.

Parameters:: exc (Exception) – Exception that describes the reason why component should stop.
Return type:: None

is_running() → bool[source]¶

Returns True if service is running.

Return type:: bool

join(timeout=None) → None[source]¶

Wait until service stops.

Parameters:: timeout – Floating point number specifying a timeout for the operation in seconds (or fractions thereof).
Return type:: None

start(*, timeout: int = 10000) → None[source]¶

Start the service.

Parameters:

timeout (int) – Timeout (in milliseconds) to wait for service to report it’s ready.

Raises:

ServiceError – If there’s an ICCP protocol error, an invalid response from the service, the service reports an error during startup, or the service thread fails to start.
TimeoutError – If the service does not send a READY message within the specified timeout.

Return type:

None

stop(*, timeout: int = 10000) → None[source]¶

Stop the service. Does nothing if service is not running.

Parameters:

timeout (int) – None (infinity), or timeout (in milliseconds) for the operation.

Raises:

ServiceError – On error in communication with service.
TimeoutError – When service does not stop in time.

Return type:

None

terminate() → None[source]¶

Terminate the service.

Terminate should be called ONLY when call to stop() (with sensible timeout) fails. Does nothing when service is not running.

Raises:: Error – When service termination fails.
Return type:: None

runtime: Thread¶