Lifecycle Management

Overview

The LifecycleManager is the central orchestrator responsible for managing the startup and shutdown sequences of all registered BaseService instances in the application.

How It Works

1. Registration: Services are registered with the LifecycleManager, optionally declaring dependencies on other services.
2. Startup: When manager.start_all() is called, it builds a dependency graph and starts the services in the correct topological order. It uses asyncio.gather to start independent services concurrently, optimizing startup time.
3. Readiness: The manager waits for all services to become "ready" by calling their wait_ready() method. The application is only considered fully started after all essential services are ready.
4. Shutdown: When manager.stop_all() is called, it shuts down all services in the reverse order of their startup, ensuring a graceful teardown.

This system guarantees that a service that depends on a database connection will only start after the database connection manager is ready, preventing race conditions and startup errors.

API Reference

nala.athomic.lifecycle.manager.LifecycleManager

Orchestrates the application lifecycle for all Athomic and Domain services.

This class is the central coordinator for service startup and shutdown. It ensures that dependencies are respected by starting and stopping services based on a priority system. It first registers all framework-level infrastructure services and then allows the application to register its own domain-specific services before managing their execution order.

Attributes:

Name	Type	Description
settings	AppSettings	The application's configuration settings.

__init__(domain_initializers_register=None, settings=None)

Initializes the LifecycleManager.

This constructor registers all of Athomic's internal infrastructure services and then executes the provided domain initializer callback to allow the application to register its own services into the lifecycle registry.

Parameters:

Name	Type	Description	Default
domain_initializers_register	Optional[Callable[[], None]]	An optional function that, when called, registers all domain-specific initializers and services.	None
settings	Optional[AppSettings]	The application settings instance. If not provided, global settings will be used.	None

shutdown() async

Executes the graceful shutdown sequence for all registered services.

It retrieves services and stops them in reverse priority order to correctly handle dependencies during shutdown. A timeout is applied to each stop operation, and any errors are logged without halting the shutdown of other services.

startup() async

Executes the startup sequence for all registered services.

It retrieves all services from the registry, sorted by their priority, and starts each one sequentially. A timeout is applied to each service's startup to prevent the application from hanging.

nala.athomic.lifecycle.registry.LifecycleRegistry

Bases: BaseInstanceRegistry[BaseServiceProtocol]

A specialized registry for services with a manageable lifecycle.

This class extends BaseInstanceRegistry by adding a priority system to control the startup and shutdown order of services. Services with a lower priority number are started first and stopped last, which is essential for managing dependencies (e.g., ensuring a database service is available before a repository service that uses it).

Attributes:

Name	Type	Description
_registry_with_priority	List[Tuple[int, str, BaseServiceProtocol]]	An internal list that stores services along with their priority, sorted on insertion.

__init__(protocol)

Initializes the LifecycleRegistry.

Parameters:

Name	Type	Description	Default
protocol	BaseServiceProtocol	The protocol that all registered items must conform to.	required

clear() async

Stops all services and completely clears the registry.

This method overrides the parent clear to also purge the internal priority list, ensuring a complete reset for testing or re-initialization.

get_services_by_priority()

Returns all registered services, sorted by startup priority.

Returns:

Type	Description
List[BaseServiceProtocol]	List[BaseServiceProtocol]: A list of service instances ordered from
List[BaseServiceProtocol]	lowest to highest priority, ready for startup.

register(name, item_instance, priority=100)

Registers a service instance with a specific priority.

Parameters:

Name	Type	Description	Default
name	str	The unique string name for the service instance.	required
item_instance	BaseServiceProtocol	The service object to register.	required
priority	Optional[int]	The startup priority. Lower numbers are started earlier and stopped later. Defaults to 100.	100