Package fr.gouv.vitam.storage.offers.tape.cache

Class LRUCache<T>

  • Type Parameters:
    T - the type of entry keys maintained by this cache.
    @ThreadSafe
public class LRUCache<T>
extends java.lang.Object
    Cache implementation with Least Recently Used (LRU) eviction policy, weighed entry capacity management, and eviction filtering for in-use/non-deletable entries. Before adding an entry, a reservation is done to ensure enough capacity is available. Once reservation done, entry can be added (by confirming reservation) ou canceled (by canceling reservation). Eviction handling is done asynchronously when reserving new entries in the cache reaches eviction capacity threshold. Reserved entries are not evicted since they are not yet added. If cache capacity exceeds its max capacity threshold, the entry reservation will fail with an exception. The eviction process ends when target eviction capacity threshold is reached, or no more entries to evict. During eviction process, entry eviction can be controlled using a , which allows filtering of entries that cannot be evicted (currently locked). After an entry is evicted, a listener is invoked for eviction notification. When created, a cache must be initialized with a list of initial list of entries. Background eviction process may be triggered at the end of initialization is required. This class is Thread-Safe (all public methods are synchronized).

    • Constructor Detail

      • LRUCache

        public LRUCache​(long maxCapacity,
                long evictionCapacity,
                long safeCapacity,
                java.util.function.Supplier<LRUCacheEvictionJudge<T>> evictionJudgeFactory,
                java.util.function.Consumer<T> evictionListener,
                java.util.stream.Stream<LRUCacheEntry<T>> initialEntries,
                java.util.concurrent.Executor evictionExecutor,
                AlertService alertService)
         throws java.lang.IllegalArgumentException
        Parameters:
        maxCapacity - Max cache storage capacity. Once reached, adding new entries fails.
        evictionCapacity - Once reached, background eviction process is started to purge cache of old unused entries.
        safeCapacity - Safe capacity level. Cache eviction process stops when cache capacity is bellow safe cache threshold.
        evictionJudgeFactory - factory that instantiates an eviction judge (LRUCacheEvictionJudge) used by background eviction process for entry eviction filtering. A new eviction judge is created before each eviction.
        evictionListener - listener invoked (synchronously) when an expired entry as been evicted from cache.
        initialEntries - stream of cache entries to add to cache. Entries mush have distinct keys.
        evictionExecutor - Executor for running eviction process asynchronously.
        alertService - alert service that is used for reporting cache capacity alerts.
        Throws:
        java.lang.IllegalArgumentException - when provided parameters have illegal values.

    • Method Detail

      • reserveEntry

        public void reserveEntry​(LRUCacheEntry<T> entry)
                  throws java.lang.IllegalArgumentException,
                         java.lang.IllegalStateException
        Reserve cache capacity for a new entry to add the cache. An entry reservation can be confirmed using the confirmReservation() method, or canceled using the cancelReservation() method. If entry already exists in the cache, an IllegalArgumentException is thrown.
        Parameters:
        entry - the entry to reserve in cache
        Throws:
        java.lang.IllegalArgumentException - when provided parameters have illegal values.
        java.lang.IllegalStateException - when cache max capacity is reached.

      • confirmReservation

        public void confirmReservation​(T entryKey)
                        throws java.lang.IllegalArgumentException
        Confirm the reservation of a reserved entry and adds it to the cache.
        Parameters:
        entryKey - the entry key whose reservation is to be confirmed.
        Throws:
        java.lang.IllegalArgumentException - when provided parameters have illegal values, or entry is not reserved in cache.

      • cancelReservation

        public void cancelReservation​(T entryKey)
        Cancels the reservation of a reserved entry and free-up cache capacity accordingly.
        Parameters:
        entryKey - the entry key whose reservation is to be canceled.
        Throws:
        java.lang.IllegalArgumentException - when provided parameters have illegal values, or entry is not reserved in cache.

      • updateEntryAccessTimestamp

        public boolean updateEntryAccessTimestamp​(T entryKey,
                                          java.time.Instant updatedLastAccessInstant)
                                   throws java.lang.IllegalArgumentException
        Try update an existing (reserved or added) entry last access timestamp. If entry does not already exist (anymore?) in cache, no update occurs.
        Parameters:
        entryKey - the key of the entry to update
        Returns:
        true if the entry timestamp has been updated, false if entry does not exist in cache.
        Throws:
        java.lang.IllegalArgumentException - when provided parameters have illegal values.

      • containsEntry

        public boolean containsEntry​(T entryKey)
                      throws java.lang.IllegalArgumentException
        Returns true if this cache contains the specified entry. Reserved entries (not yet confirmed) or non-existing entries in the cache return false
        Parameters:
        entryKey - the entry key whose presence in this cache is to be tested
        Returns:
        true if the entry exists in the cache, false otherwise.
        Throws:
        java.lang.IllegalArgumentException - when provided parameters have illegal values.

      • isReservedEntry

        public boolean isReservedEntry​(T entryKey)
                        throws java.lang.IllegalArgumentException
        Returns true if specified entry key is reserved in the cache.
        Parameters:
        entryKey - the entry key whose reservation status is to be tested
        Returns:
        true if the entry is reserved, otherwise false.
        Throws:
        java.lang.IllegalArgumentException - when provided parameters have illegal values.

      • getReservedEntry

        public LRUCacheEntry<T> getReservedEntry​(T entryKey)
                                  throws java.lang.IllegalArgumentException
        Returns true if specified entry key is reserved in the cache.
        Parameters:
        entryKey - the entry key whose reservation status is to be tested
        Returns:
        true if the entry is reserved, otherwise false.
        Throws:
        java.lang.IllegalArgumentException - when provided parameters have illegal values.

      • getMaxCapacity

        public long getMaxCapacity()
        Returns:
        Max cache storage capacity of the cache. Once reached, adding new entries fails.

      • getEvictionCapacity

        public long getEvictionCapacity()
        Returns:
        eviction capacity threshold. Once reached, background eviction process is started to purge cache of old unused entries.

      • getSafeCapacity

        public long getSafeCapacity()
        Returns:
        Safe capacity level threshold. Cache eviction process stops when cache capacity is bellow safe cache threshold.

      • getCurrentCapacity

        public long getCurrentCapacity()
        Returns:
        Current cache capacity.

      • isCacheEvictionRunning

        public boolean isCacheEvictionRunning()