Package io.aether.utils.rcollections

Interface BMap<K,​V>

  • Type Parameters:
    K - The type of the key.
    V - The type of the value to be retrieved asynchronously.
    All Superinterfaces:
    Destroyable, java.util.Map<K,​ARFutureWithFlag<V>>, RFMap<K,​V>, RMap<K,​ARFutureWithFlag<V>>
    All Known Implementing Classes:
    BMapImpl
    public interface BMap<K,​V>
extends RFMap<K,​V>, Destroyable
    Interface for an asynchronous, throttling map designed to manage the lifecycle of external data requests. It extends RFMap<K, V> (which is RMap<K, ARFutureWithFlag<V>>) and adds the necessary methods for throttling and batching external requests, specifically supporting multi-sender request tracking.

    • Nested Class Summary

      • Nested classes/interfaces inherited from interface java.util.Map

        java.util.Map.Entry<K extends java.lang.Object,​V extends java.lang.Object>

      • Nested classes/interfaces inherited from interface io.aether.utils.rcollections.RMap

        RMap.Update<K,​V>

    • Method Summary

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      EventConsumer<RMap.Update<K,​V>> forValueUpdate()
      Returns an EventConsumer that fires when a value in the map is definitively resolved.
      @NotNull ARFutureWithFlag<V> getFuture​(K key)
      Retrieves the ARFutureWithFlag associated with the key.
      @NotNull java.util.Set<K> getPendingRequests()
      Returns a set of keys that currently require fetching from the external service.
      K[] getRequestsFor​(java.lang.Class<K> elementType, java.lang.Object sender)
      Returns an array of keys that are queued for network submission by this specific sender.
      boolean isRequests()
      Checks if there is any work available globally (e.g., items in the new request pool).
      boolean isRequestsFor​(@NotNull java.lang.Object sender)
      Checks if there are any pending requests (newly available or timed-out) for the specified sender.
      void putError​(K key, @NotNull java.lang.Throwable error)
      Marks the future for a key as completed with an error.
      void putResolved​(K key, @NotNull AConsumer<V> updater, V value)  
      void putResolved​(K key, V value)
      Puts a fully resolved value into the map, immediately fulfilling any waiting future.

      • Methods inherited from interface java.util.Map

        compute, computeIfAbsent, computeIfPresent, containsKey, containsValue, equals, forEach, get, getOrDefault, hashCode, isEmpty, merge, put, putIfAbsent, remove, remove, replace, replace, replaceAll, size

    • Method Detail

      • getFuture

        @NotNull
@NotNull ARFutureWithFlag<V> getFuture​(@NotNull
                                       K key)
        Retrieves the ARFutureWithFlag associated with the key. If the value is not present or the previous request has timed out, this method must conditionally add the key to the new request pool for later batching by a separate flush mechanism.
        Parameters:
        key - The key.
        Returns:
        An ARFutureWithFlag that represents the eventual completion of the value retrieval.

      • getPendingRequests

        @NotNull
@NotNull java.util.Set<K> getPendingRequests()
        Returns a set of keys that currently require fetching from the external service. This method is designed for systems needing exclusive control over batching and clears the internal pool of newly requested keys upon return.
        Returns:
        A Set of keys that were queued for network submission.

      • putResolved

        void putResolved​(@NotNull
                 K key,
                 @NotNull
                 V value)
        Puts a fully resolved value into the map, immediately fulfilling any waiting future.
        Parameters:
        key - The key for the resolved value.
        value - The resolved value.

      • putResolved

        void putResolved​(@NotNull
                 K key,
                 @NotNull
                 @NotNull AConsumer<V> updater,
                 V value)

      • putError

        void putError​(@NotNull
              K key,
              @NotNull
              @NotNull java.lang.Throwable error)
        Marks the future for a key as completed with an error.
        Parameters:
        key - The key associated with the error.
        error - The error to complete the future with.

      • forValueUpdate

        EventConsumer<RMap.Update<K,​V>> forValueUpdate()
        Returns an EventConsumer that fires when a value in the map is definitively resolved.
        Returns:
        The EventConsumer for resolved value updates (K, V).

      • getRequestsFor

        K[] getRequestsFor​(java.lang.Class<K> elementType,
                   java.lang.Object sender)
        Returns an array of keys that are queued for network submission by this specific sender. This array includes keys that are newly available and keys for which this sender's previous request has timed out.

        The implementing class is responsible for transferring new requests and updating the sender's flush time during this call.

        Parameters:
        elementType - The Class of the key type for array creation (often K.class).
        sender - The object responsible for sending the network request (e.g., ConnectionWork).
        Returns:
        An array of keys (K[]) that are queued for network submission by this sender.

      • isRequests

        boolean isRequests()
        Checks if there is any work available globally (e.g., items in the new request pool). This method is a fast check intended to avoid unnecessary work.
        Returns:
        True if work might be available globally, false otherwise.

      • isRequestsFor

        boolean isRequestsFor​(@NotNull
                      @NotNull java.lang.Object sender)
        Checks if there are any pending requests (newly available or timed-out) for the specified sender. This method is a fast check intended to avoid unnecessary calls to getRequestsFor.
        Parameters:
        sender - The sender object.
        Returns:
        True if work might be available for this sender, false otherwise.