Package io.deephaven.util

Class CapacityAdaptor

java.lang.Object
io.deephaven.util.CapacityAdaptor
public final class CapacityAdaptor extends Object
Sizes a bounded pool of reusable items from the traffic it sees. The pool reports each borrow and return, and reads the capacity it may hold; when the capacity falls below what the pool holds, the pool discards the difference. The pool holds whatever lock it needs: this class is not thread-safe.

Terms: the pool is the bin of reusable items that this adaptor sizes, and its capacity is the most items it may hold at once. A client of the pool borrows an item and may later return it. A borrow from an empty pool is a miss: the client constructs an item instead. A return to a full pool is turned away: the pool discards the item instead. A burst is a run of borrows whose items are returned together. A window is a span of traffic, delimited by the pool's owner, over which one shrink decision is judged, and the shrink fraction, from 0 to 1, is the share of the items a window never needed, the fewest the pool held at any moment in it, that the capacity gives up when the window ends.

The capacity adapts between the capacity the adaptor was created with and a maximum.

It grows by one at each miss that a larger pool would have served. The adaptor keeps a counter of turned-away items: each item the pool turns away for being full adds one, and each miss charged against it, below, subtracts one. The pool turns items away only when it is full, so a pool larger by the counter would hold exactly that many more items now, whatever order the borrows and returns came in. A miss that occurs while the counter is positive is therefore an item the pool could have reused and did not: a regretted turn-away. It grows the capacity by one and decrements the counter. On the other hand, a miss while the counter is zero, as when borrowers keep what they borrow, changes neither the counter nor the capacity. The counter never exceeds the room left to grow, since turned-away items beyond that could never be kept. Items are commonly borrowed in bursts and returned together, as when an update cycle borrows storage for previous values and returns it all when the cycle completes. One cycle that the pool is too small for turns the shortfall away; the next grows the pool by it, during its burst, and from then on reuses everything. No clock is needed, and the capacity never grows past what some burst actually used, since each unit of growth was a miss.

It shrinks at the end of each window, which the pool's owner signals through endWindow(int). When a window sees the pool never empty, the fewest items it held in that window were never needed, and the capacity discards the shrink fraction of them, rounded up, but never goes below the capacity it was created with. The items the window did need are always kept: with a capacity of 100 and a window that never drew the pool below 40 items, a fraction of 0.9 discards 36 of those 40, leaving a capacity of 64, while a fraction of 0 keeps the capacity once grown. A window should span at least one whole cycle of each client that borrows from the pool, since a window that ends partway through a burst sees items that burst was still about to borrow as unneeded. The adaptor reads no clock: the borrows and returns it counts only update counters.

  • Constructor Summary

    Constructors
    Constructor
    Description
    CapacityAdaptor(int capacity, int maximumCapacity, double shrinkFraction)
     

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    borrowed(int held)
    The pool lent out an item it held.
    int
    capacity()
     
    void
    dropped()
    The pool was full, so it turned the returned item away.
    void
    endWindow(int held)
    End the window: discard the shrink fraction of the items the pool never needed in it, and start the next.
    void
    missed()
    The pool was empty, so the borrower constructed an item.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Constructor Details

    • CapacityAdaptor

      public CapacityAdaptor(int capacity, int maximumCapacity, double shrinkFraction)
      Parameters:
      capacity - The capacity to start with, and the least to shrink to
      maximumCapacity - The most the capacity may grow to, at least capacity
      shrinkFraction - The fraction, from 0 to 1, of the items a window never needed that the capacity discards

  • Method Details

    • capacity

      public int capacity()
      Returns:
      the most items the pool may hold now; the pool discards any it holds beyond this

    • borrowed

      public void borrowed(int held)
      The pool lent out an item it held.
      Parameters:
      held - The items the pool holds now

    • missed

      public void missed()
      The pool was empty, so the borrower constructed an item.

    • dropped

      public void dropped()
      The pool was full, so it turned the returned item away.

    • endWindow

      public void endWindow(int held)
      End the window: discard the shrink fraction of the items the pool never needed in it, and start the next.
      Parameters:
      held - The items the pool holds, before it discards any beyond the capacity this leaves