libp2p.tools.async_service package

Submodules

libp2p.tools.async_service.abc module

class libp2p.tools.async_service.abc.InternalManagerAPI

Bases: ManagerAPI

Defines the API that the Service.manager property exposes.

The InternalManagerAPI / ManagerAPI distinction is in place to ensure that external callers to a service do not try to use the task scheduling functionality as it is only designed to be used internally.

abstract run_child_service(service: ServiceAPI, daemon: bool = False, name: str | None = None) → ManagerAPI

Run a service in the background. If the function throws an exception it will trigger the parent service to be cancelled and be propogated.

If daemon == True then the the service is expected to run indefinitely and will trigger cancellation if the service finishes.

abstract run_daemon_child_service(service: ServiceAPI, name: str | None = None) → ManagerAPI

Run a daemon service in the background.

Equivalent to run_child_service(…, daemon=True).

abstract run_daemon_task(async_fn: Callable[[...], Awaitable[Any]], *args: Any, name: str | None = None) → None

Run a daemon task in the background.

Equivalent to run_task(…, daemon=True).

abstract run_task(async_fn: Callable[[...], Awaitable[Any]], *args: Any, daemon: bool = False, name: str | None = None) → None

Run a task in the background. If the function throws an exception it will trigger the service to be cancelled and be propogated.

If daemon == True then the the task is expected to run indefinitely and will trigger cancellation if the task finishes.

class libp2p.tools.async_service.abc.ManagerAPI

Bases: ABC

abstract cancel() → None: Trigger cancellation of the service.

abstract property did_error: bool: Return boolean indicating if the underlying service threw an exception.

abstract property is_cancelled: bool

Return boolean indicating if the underlying service has been cancelled.

This can occure externally via the cancel() method or internally due to a task crash or a crash of the actual ServiceAPI.run() method.

abstract property is_finished: bool

Return boolean indicating if the underlying service is stopped.

A stopped service will have completed all of the background tasks.

abstract property is_running: bool

Return boolean indicating if the underlying service is actively running.

A service is considered running if it has been started and has not yet been stopped.

abstract property is_started: bool: Return boolean indicating if the underlying service has been started.

abstract async run() → None: Run a service

abstract async classmethod run_service(service: ServiceAPI) → None: Run a service

abstract property stats: Stats: Return a stats object with details about the service.

abstract async stop() → None: Trigger cancellation of the service and wait for it to finish.

abstract async wait_finished() → None: Wait until the service is stopped.

abstract async wait_started() → None: Wait until the service is started.

class libp2p.tools.async_service.abc.ServiceAPI

Bases: ABC

abstract get_manager() → ManagerAPI

External retrieval of the manager for this service.

Will raise a LifecycleError if the service does not yet have a manager assigned to it.

abstract async run() → None

Primary entry point for all service logic.

Note

This method should not be directly invoked by user code.

Services may be run using the following approaches.

class libp2p.tools.async_service.abc.TaskAPI

Bases: Hashable

abstract async cancel() → None

daemon: bool

abstract property is_done: bool

name: str

parent: TaskWithChildrenAPI | None

abstract async run() → None

abstract async wait_done() → None

class libp2p.tools.async_service.abc.TaskWithChildrenAPI

Bases: TaskAPI

abstract add_child(child: TaskAPI) → None

children: set[TaskAPI]

abstract discard_child(child: TaskAPI) → None

libp2p.tools.async_service.base module

class libp2p.tools.async_service.base.BaseChildServiceTask(name: str, daemon: bool, parent: TaskWithChildrenAPI | None)

Bases: BaseTask

child_manager: ManagerAPI

property is_done: bool

async run() → None

async wait_done() → None

class libp2p.tools.async_service.base.BaseFunctionTask(name: str, daemon: bool, parent: TaskWithChildrenAPI | None, async_fn: Callable[[...], Awaitable[Any]], async_fn_args: Sequence[Any])

Bases: BaseTaskWithChildren

classmethod iterate_tasks(*tasks: TaskAPI) → Iterable[BaseFunctionTask]: Iterate over all tasks of this class type and their children recursively.

class libp2p.tools.async_service.base.BaseManager(service: ServiceAPI)

Bases: InternalManagerAPI

property did_error: bool: Return boolean indicating if the underlying service threw an exception.

property is_running: bool

Return boolean indicating if the underlying service is actively running.

A service is considered running if it has been started and has not yet been stopped.

run_daemon_child_service(service: ServiceAPI, name: str | None = None) → ManagerAPI

Run a daemon service in the background.

Equivalent to run_child_service(…, daemon=True).

run_daemon_task(async_fn: Callable[[...], Awaitable[Any]], *args: Any, name: str | None = None) → None

Run a daemon task in the background.

Equivalent to run_task(…, daemon=True).

property stats: Stats: Return a stats object with details about the service.

async stop() → None: Trigger cancellation of the service and wait for it to finish.

class libp2p.tools.async_service.base.BaseTask(name: str, daemon: bool, parent: TaskWithChildrenAPI | None): Bases: TaskAPI

class libp2p.tools.async_service.base.BaseTaskWithChildren(name: str, daemon: bool, parent: TaskWithChildrenAPI | None)

Bases: BaseTask, TaskWithChildrenAPI

add_child(child: TaskAPI) → None

discard_child(child: TaskAPI) → None

class libp2p.tools.async_service.base.Service

Bases: ServiceAPI

get_manager() → ManagerAPI

External retrieval of the manager for this service.

Will raise a LifecycleError if the service does not yet have a manager assigned to it.

property manager: InternalManagerAPI: Expose the manager as a property here intead of async_service.abc.ServiceAPI to ensure that anyone using proper type hints will not have access to this property since it isn’t part of that API, while still allowing all subclasses of the async_service.base.Service to access this property directly.

libp2p.tools.async_service.base.as_service(service_fn: Callable[[...], Awaitable[Any]]) → type[ServiceAPI]: Create a service out of a simple function

libp2p.tools.async_service.exceptions module

exception libp2p.tools.async_service.exceptions.DaemonTaskExit

Bases: ServiceException

Raised when an action would violate the service lifecycle rules.

exception libp2p.tools.async_service.exceptions.LifecycleError

Bases: ServiceException

Raised when an action would violate the service lifecycle rules.

exception libp2p.tools.async_service.exceptions.ServiceException

Bases: Exception

Base class for Service exceptions

exception libp2p.tools.async_service.exceptions.TooManyChildrenException

Bases: ServiceException

Raised when a service adds too many children. It is a sign of task leakage that needs to be prevented.

libp2p.tools.async_service.stats module

class libp2p.tools.async_service.stats.Stats(tasks)

Bases: NamedTuple

tasks: TaskStats: Alias for field number 0

class libp2p.tools.async_service.stats.TaskStats(total_count, finished_count)

Bases: NamedTuple

finished_count: int: Alias for field number 1

property pending_count: int

total_count: int: Alias for field number 0

libp2p.tools.async_service.trio_service module

class libp2p.tools.async_service.trio_service.ChildServiceTask(name: str, daemon: bool, parent: TaskWithChildrenAPI | None, child_service: ServiceAPI)

Bases: BaseChildServiceTask

async cancel() → None

class libp2p.tools.async_service.trio_service.FunctionTask(name: str, daemon: bool, parent: TaskWithChildrenAPI | None, async_fn: Callable[[...], Awaitable[Any]], async_fn_args: Sequence[Any])

Bases: BaseFunctionTask

async cancel() → None

property has_trio_task: bool

property is_done: bool

classmethod iterate_tasks(*tasks: TaskAPI) → Iterable[FunctionTask]: Iterate over all FunctionTask instances and their children recursively.

async run() → None

property trio_task: Task

async wait_done() → None

class libp2p.tools.async_service.trio_service.TrioManager(service: ServiceAPI)

Bases: BaseManager

cancel() → None: Trigger cancellation of the service.

property is_cancelled: bool

Return boolean indicating if the underlying service has been cancelled.

This can occure externally via the cancel() method or internally due to a task crash or a crash of the actual ServiceAPI.run() method.

property is_finished: bool

Return boolean indicating if the underlying service is stopped.

A stopped service will have completed all of the background tasks.

property is_started: bool: Return boolean indicating if the underlying service has been started.

async run() → None: Run a service

run_child_service(service: ServiceAPI, daemon: bool = False, name: str | None = None) → ManagerAPI

Run a service in the background. If the function throws an exception it will trigger the parent service to be cancelled and be propogated.

If daemon == True then the the service is expected to run indefinitely and will trigger cancellation if the service finishes.

async classmethod run_service(service: ServiceAPI) → None: Run a service

run_task(async_fn: Callable[[...], Awaitable[Any]], *args: Any, daemon: bool = False, name: str | None = None) → None

Run a task in the background. If the function throws an exception it will trigger the service to be cancelled and be propogated.

If daemon == True then the the task is expected to run indefinitely and will trigger cancellation if the task finishes.

async wait_finished() → None: Wait until the service is stopped.

async wait_started() → None: Wait until the service is started.

libp2p.tools.async_service.trio_service.background_trio_service(service: ServiceAPI) → AsyncIterator[ManagerAPI]

Run a service in the background.

The service is running within the context block and will be properly cleaned up upon exiting the context block.

libp2p.tools.async_service.trio_service.external_api(func: TFunc) → TFunc

libp2p.tools.async_service package

Submodules

libp2p.tools.async_service.abc module

libp2p.tools.async_service.base module

libp2p.tools.async_service.exceptions module

libp2p.tools.async_service.stats module

libp2p.tools.async_service.trio_service module

libp2p.tools.async_service.typing module

Module contents