3.0.ipv8.requestcache ===================== .. py:module:: 3.0.ipv8.requestcache Attributes ---------- .. autoapisummary:: 3.0.ipv8.requestcache.CacheTypeVar 3.0.ipv8.requestcache.ACT Classes ------- .. autoapisummary:: 3.0.ipv8.requestcache.NumberCache 3.0.ipv8.requestcache.RandomNumberCache 3.0.ipv8.requestcache.CacheWithName 3.0.ipv8.requestcache.NumberCacheWithName 3.0.ipv8.requestcache.RandomNumberCacheWithName 3.0.ipv8.requestcache.RequestCache Module Contents --------------- .. py:class:: NumberCache(request_cache: RequestCache, prefix: str, number: int) A cache for state information that is uniquely identified by a prefix and a number. .. py:attribute:: _logger .. py:attribute:: _prefix .. py:attribute:: _number .. py:attribute:: _managed_futures :type: list[tuple[asyncio.Future, object | None]] :value: [] .. py:method:: register_future(future: asyncio.Future, on_timeout: object | None = None) -> None Register a future for this Cache that will be canceled when this Cache times out. :param future: the future to register for this instance :param on_timeout: The value to which the future is to be set when a timeout occurs. If the value is an instance of Exception, future.set_exception will be called instead of future.set_result .. py:property:: managed_futures :type: list[tuple[asyncio.Future, object | None]] Get a list of all managed futures. .. py:property:: prefix :type: str Get the prefix of this cache type. .. py:property:: number :type: int Get the unique number of this cache. .. py:property:: timeout_delay :type: float The delay until this cache should be timed out. .. py:method:: on_timeout() -> None :abstractmethod: The logic to call when this cache times out. .. py:method:: __str__() -> str Convert this cache to a printable string. .. py:class:: RandomNumberCache(request_cache: RequestCache, prefix: str) Bases: :py:obj:`NumberCache` A cache with a randomly generated number. .. py:method:: find_unclaimed_identifier(request_cache: RequestCache, prefix: str) -> int :classmethod: Generate a random number for use with this cache. .. py:class:: CacheWithName Bases: :py:obj:`typing_extensions.Protocol` All caches with a ``name`` attribute. .. py:attribute:: name :type: str .. py:data:: CacheTypeVar .. py:data:: ACT .. py:class:: NumberCacheWithName(request_cache: RequestCache, prefix: str, number: int) Bases: :py:obj:`NumberCache`, :py:obj:`CacheWithName`, :py:obj:`abc.ABC` A NumberCache with a ``name`` attribute. .. py:class:: RandomNumberCacheWithName(request_cache: RequestCache, prefix: str) Bases: :py:obj:`RandomNumberCache`, :py:obj:`CacheWithName`, :py:obj:`abc.ABC` A RandomNumberCache with a ``name`` attribute. .. py:class:: RequestCache Bases: :py:obj:`3.0.ipv8.taskmanager.TaskManager` Manager for NumberCache caches. .. py:attribute:: _logger .. py:attribute:: _identifiers :type: dict[str, NumberCache] .. py:attribute:: _waiters :type: dict[tuple[str, int], asyncio.Future] .. py:attribute:: lock .. py:attribute:: _shutdown :value: False .. py:attribute:: _timeout_override :type: float | None :value: None If not None, this specifies the timeout to use instead of the one defined in the ``timeout_delay`` of a ``NumberCache``. This is used internally for ``passthrough()``, don't modify this directly! .. py:attribute:: _timeout_filters :type: collections.abc.Iterable[type[NumberCache]] | None :value: None If not None, this specifies the ``NumberCache`` (sub)classes to apply the timeout override for. This is used internally for ``passthrough()``, don't modify this directly! .. py:method:: add(cache: ACT) -> ACT | None Add CACHE into this RequestCache instance. Returns CACHE when CACHE.identifier was not yet added, otherwise returns None. .. py:method:: has(prefix: str, number: int) -> bool has(prefix: type[CacheTypeVar], number: int) -> bool Returns True when IDENTIFIER is part of this RequestCache. .. py:method:: _watch_future(key: tuple[str, int]) -> None Ensure that a given future is killed after some timeout. .. py:method:: wait_for(prefix: str, number: int, timeout: float | None = None) -> asyncio.Future[NumberCache] wait_for(prefix: type[CacheTypeVar], number: int, timeout: float | None = None) -> asyncio.Future[CacheTypeVar] Returns a future that fires if or when the given cache is registered. .. py:method:: get(prefix: str, number: int) -> NumberCache | None get(prefix: type[CacheTypeVar], number: int) -> CacheTypeVar | None Returns the Cache associated with IDENTIFIER when it exists, otherwise returns None. .. py:method:: pop(prefix: str, number: int) -> NumberCache pop(prefix: type[CacheTypeVar], number: int) -> CacheTypeVar Returns the Cache associated with IDENTIFIER, and removes it from this RequestCache, when it exists, otherwise raises a KeyError exception. .. py:method:: passthrough(cls_filter: type[NumberCache] | None = None, *filters: type[NumberCache], timeout: float = 0.0) -> collections.abc.Generator A contextmanager that overwrites the timeout_delay of added NumberCaches in its scope. This can be used to shorten or eliminate timeouts of external code. --- Example 1: Eliminating timeouts, regardless of ``cache.timeout_delay`` --- .. code-block :: Python with request_cache.passthrough(): request_cache.add(cache) # This will instantly timeout (once the main thread is yielded). with request_cache.passthrough(): # Any internal call to request_cache.add() will also be instantly timed out. await some_function_that_uses_request_cache() --- Example 2: Modifying timeouts, regardless of ``cache.timeout_delay`` --- .. code-block :: Python with request_cache.passthrough(timeout=0.1): request_cache.add(cache) # This will timeout after 0.1 seconds. --- Example 3: Filtering for specific classes --- .. code-block :: Python # Only MyCacheClass, MyOtherCacheClass, YetAnotherCacheClass will have their timeout changed to 4 seconds. with request_cache.passthrough(MyCacheClass, MyOtherCacheClass, YetAnotherCacheClass, timeout=4.0): request_cache.add(cache) :param cls_filter: An optional class filter to specify which classes the timeout override needs to apply to. :param filters: Additional class filters to specify which classes the timeout override needs to apply to. :param timeout: The timeout in seconds to use for the ``NumberCache`` instances this applies to. :returns: A context manager (compatible with ``with``). .. py:method:: _on_timeout(cache: NumberCache) -> None Called CACHE.timeout_delay seconds after CACHE was added to this RequestCache. _on_timeout is called for every Cache, except when it has been popped before the timeout expires. When called _on_timeout will CACHE.on_timeout(). .. py:method:: _create_identifier(number: int, prefix: str) -> str .. py:method:: clear() -> list[asyncio.Future] Clear the cache, canceling all pending tasks. .. py:method:: shutdown() -> None :async: Clear the cache, cancel all pending tasks and disallow new caches being added.