Class SoftRecycler<T>

java.lang.Object
io.deephaven.util.SoftRecycler<T>

public class SoftRecycler<T> extends Object
This class makes a little "recycle bin" for your objects of type T. When you want an object, call borrowItem(). When you do so, either a fresh T will be constructed for you, or a reused T will be pulled from the recycle bin. When you are done with the object and want to recycle it, call returnItem(Object). The items you return are held by SoftReferences, so the garbage collector may reclaim them if it feels like it. Otherwise, previously-returned items are re-borrowed in LIFO order, which hopefully is somewhat cache-friendly.

The caller has no special obligation to return a borrowed item nor to return borrowed items in any particular order. If your code has a need to keep a borrowed item forever, there is no problem with that. But if you want your objects to be reused, you have to return them. This is true even for registered recyclers which adapt their capacity to their traffic; an item kept forever simply never counts toward it.

The recycle bin holds at most its current capacity, which a CapacityAdaptor adapts to its traffic between the capacity the recycler was created with and its maximum. The capacity grows on its own, but shrinks only when the recycler's window ends, and windows end only for recyclers registered through SoftRecyclerWindow.register(SoftRecycler), which ends them from the update graphs' cycles. An unregistered recycler grows to its maximum and stays there. The shrink fraction is the "SoftRecycler.shrinkFraction"<T> property, 0.1 by default.

  • Field Details

    • WINDOW_MILLIS_PROPERTY

      public static final String WINDOW_MILLIS_PROPERTY
      The property for the fewest milliseconds of traffic each shrink of the capacity is judged on.
      See Also:
    • SHRINK_FRACTION_PROPERTY

      public static final String SHRINK_FRACTION_PROPERTY
      The property for the fraction, from 0 to 1, of the items a window never needed that the capacity discards; the rest of them, and every item the window did need, are kept. 0 never shrinks, 0.9 discards 90% of the unneeded items and keeps 10%, and 1 shrinks to what the window needed.
      See Also:
  • Constructor Details

    • SoftRecycler

      public SoftRecycler(int capacity, int maximumCapacity, Supplier<T> constructItem, Consumer<T> sanitizeItem)
      Parameters:
      capacity - The capacity the recycler starts with, and the least it shrinks to; it grows with its traffic up to maximumCapacity
      maximumCapacity - The most items the recycler may grow to hold, at least capacity. Use Integer.MAX_VALUE for no maximum: the items are soft references, which the garbage collector reclaims under memory pressure, so an unlimited recycler is not a leak.
      constructItem - A callback that creates a new item
      sanitizeItem - Optional. A callback that sanitizes the item before reuse. Pass null if no sanitization is needed.
  • Method Details

    • borrowItem

      public T borrowItem()
    • returnItem

      public void returnItem(T item)