java.lang.Object
net.i2p.util.TryCache<T>
Type Parameters:
T - type of objects cached
Direct Known Subclasses:
ByteCache
public class TryCache<T>extends Object
A thread-safe, lock-free-ish object cache that reuses objects to reduce allocation overhead. Designed to avoid object loss due to lock contention.

  • Field Details

    • DEBUG_DUP

      private static final boolean DEBUG_DUP
      True to log duplicate releases.
      See Also:

    • factory

      private final TryCache.ObjectFactory<T> factory
      The factory making missing objects.

    • capacity

      private volatile int capacity
      Most objects to keep cached.

    • items

      private final ConcurrentLinkedDeque<T> items
      The objects held in the cache.

    • _lastUnderflow

      private volatile long _lastUnderflow
      When the cache last ran empty.

    • _acquireCount

      private volatile long _acquireCount
      Objects taken from the cache.

    • _missCount

      private volatile long _missCount
      Times the cache was empty.

    • _releaseCount

      private volatile long _releaseCount
      Objects returned to the cache.

    • _discardCount

      private volatile long _discardCount
      Objects dropped instead of cached.

  • Constructor Details

    • TryCache

      public TryCache(TryCache.ObjectFactory<T> factory, int capacity)
      Stores the factory and clamps a negative capacity to zero.
      Parameters:
      factory - the source of instances to create when the cache is empty
      capacity - the greatest number of instances to retain; negatives clamp to 0

  • Method Details

    • acquire

      public T acquire()
      Acquire an object from the cache or create a new one.
      Returns:
      a cached or newly created object

    • release

      public void release(T item)
      Try to return the item to the cache. If the cache is full, the item is discarded.
      Parameters:
      item - the value to hand back to the cache for reuse

    • clear

      public void clear()
      Clear all cached items.

    • size

      public int size()
      Number of items currently held.
      Returns:
      the count of cached items, 0 to capacity

    • wasUnderfilled

      public boolean wasUnderfilled(long thresholdMillis)
      Check if the cache has been underfilled longer than the threshold.
      Parameters:
      thresholdMillis - the threshold in milliseconds
      Returns:
      true if the cache has been underfilled longer than the threshold

    • shrink

      public void shrink(int targetSize)
      Shrink the cache to the target size, evicting excess items.
      Parameters:
      targetSize - the desired maximum number of items

    • resize

      public void resize(int newCapacity)
      Resize the cache to a new capacity. If shrinking, excess items are evicted. If growing, the cache simply allows more items to accumulate on future releases.
      Parameters:
      newCapacity - the new maximum number of entries

    • getLastUnderflowTime

      public long getLastUnderflowTime()
      When the cache last fell below its target size.
      Returns:
      the time in milliseconds since the epoch

    • getCapacity

      public int getCapacity()
      Return the current cache capacity.
      Returns:
      the maximum number of cached items

    • getMissCount

      public long getMissCount()
      Return the number of acquire() calls that found an empty cache (misses required allocating a new object).
      Returns:
      the miss count

    • getDiscardCount

      public long getDiscardCount()
      Return the number of release(T) calls that were discarded because the cache was full.
      Returns:
      the discard count

    • getAcquireCount

      public long getAcquireCount()
      Return total acquire() count (hits + misses).
      Returns:
      the acquire count

    • getReleaseCount

      public long getReleaseCount()
      Return total release() count (returned to cache).
      Returns:
      the release count