plesty.lib.service.resource_manager
===================================

.. py:module:: plesty.lib.service.resource_manager

.. autoapi-nested-parse::

   Resource manager for tracking and allocating lockable device resources.



Classes
-------

.. autoapisummary::

   plesty.lib.service.resource_manager.ResourceManager


Module Contents
---------------

.. py:class:: ResourceManager

   Manage exclusive access to resources.

   Registered resources may be a flat collection or a nested tree::

       ["Dev1/port0/line0", "Dev1/port0/line1"]
       {"Dev1/port0/line0", "Dev1/port0/line1"}

       {
           "Dev1": {
               "port0": ["line0", "line1"],
               "port1": ["line0", "line1"],
           }
       }

   Client requests may be a string (``"Dev1/port0"`` — every leaf under
   that subtree; ``"Dev1/port0/line0"`` — one exact leaf), a flat
   collection (``["Dev1/port0", "Dev1/port1/line0"]``), or a nested
   dictionary tree (``{"Dev1": {"port0": ["line0"]}}``).

   Initialize with empty resource and client tracking sets.


   .. py:attribute:: _resources
      :type:  set[str]


   .. py:attribute:: _locked_resources
      :type:  set[str]


   .. py:attribute:: _clients
      :type:  dict[str, list[str]]


   .. py:method:: register_resources(resources: Any) -> None

      Register known resources.

      If resources is a tree dict, all leaf paths are registered.
      If resources is a flat list/set, items are registered as canonical strings.



   .. py:method:: normalize_resources(resources: Any) -> list[str]

      Convert any supported resource request format into canonical leaf paths.

      If known resources are registered, subtree paths are expanded to matching leaves.
      If no known resources are registered, paths are preserved as given.



   .. py:method:: client_resources(client_id: str) -> list[str]

      Return the resources currently allocated to a client.



   .. py:method:: resource_available(resources: Any) -> bool

      Check if the requested resources are available for allocation.



   .. py:method:: allocate_resource(resources: Any, client_id: str) -> bool

      Attempt to allocate resources to a client.

      :param resources: Resource request in str/list/set/dict tree format.
      :param client_id: Identifier used to track the allocation.



   .. py:method:: release_resource(client_id: str) -> None

      Release a previously allocated resource set.

      :param client_id: The identifier for the resource allocation to release.



   .. py:method:: attach_resource(payload: dict, client_id: str) -> dict

      Attach already allocated resources to an incoming payload.

      :param payload: The incoming request payload that may contain resource requirements.
      :param client_id: Client identifier used for resource tracking.



   .. py:method:: _unknown_resources(resources: list[str]) -> list[str]

      Return requested resources that are not registered.

      If no known resources were registered, all requests are accepted. This keeps
      backward compatibility with the original behavior.



   .. py:method:: _flatten_resource_spec(spec: Any, prefix: str = '', *, expand_known: bool) -> list[str]

      Flatten str/list/set/dict tree resource specs into canonical string paths.

      When expand_known=True, a path that is not an exact leaf but is a known
      subtree prefix expands to all registered leaf resources below it.



   .. py:method:: _expand_path(path: str) -> list[str]

      Expand a path to registered leaf resources.

      Examples with registered leaves:
          Dev1/port0          -> Dev1/port0/line0, Dev1/port0/line1
          Dev1/port0/line0    -> Dev1/port0/line0



   .. py:method:: _is_iterable_collection(value: Any) -> bool
      :staticmethod:



   .. py:method:: _join_path(prefix: str, value: str) -> str
      :staticmethod:



   .. py:method:: _canonical_path(path: str, prefix: str = '') -> str
      :staticmethod: