Package 

Class BasePool

  • All Implemented Interfaces:
    com.facebook.common.memory.MemoryTrimmable , com.facebook.common.memory.Pool , com.facebook.common.references.ResourceReleaser 
    
public abstract class BasePool<V>
 implements Pool<V>

    A base pool class that manages a pool of values (of type V).

    The pool is organized as a map. Each entry in the map is a free-list (modeled by a queue) of entries for a given size. Some pools have a fixed set of buckets (aka bucketized sizes), while others don't.

    The pool supports two main operations:

    • get - returns a value of size that's the same or larger than specified, hopefully from the pool; otherwise, this value is allocated (via the alloc function)
    • release - releases a value to the pool
    In addition, the pool subscribes to the MemoryTrimmableRegistry, and responds to low-memory events (calls to trim). Some percent (perhaps all) of the values in the pool are then released (via the underlying free function), and no longer belong to the pool.

    Sizes There are 3 different notions of sizes we consider here (not all of them may be relevant for each use case).

    • Logical size is simply the size of the value in terms appropriate for the value. For example, for byte arrays, the size is simply the length. For a bitmap, the size is just the number of pixels.
    • Bucketed size typically represents one of discrete set of logical sizes - such that each bucketed size can accommodate a range of logical sizes. For example, for byte arrays, using sizes that are powers of 2 for bucketed sizes allows these byte arrays to support a number of logical sizes.
    • Finally, Size-in-bytes is exactly that - the size of the value in bytes.
    Logical Size and BucketedSize are both represented by the type parameter S, while size-in-bytes is represented by an int.

    Each concrete subclass of the pool must implement the following methods

    • getBucketedSize - returns the bucketized size for the given request size
    • getBucketedSizeForValue - returns the bucketized size for a given value
    • getSizeInBytes - gets the size in bytes for a given bucketized size
    • alloc - allocates a value of given size
    • free - frees the value V Subclasses may optionally implement
    • onParamsChanged - called whenever this class determines to re-read the pool params
    • isReusable - used to determine if a value can be reused or must be freed

    InUse values The pool keeps track of values currently in use (in addition to the free values in the buckets). This is maintained in an IdentityHashSet (using reference equality for the values). The in-use set helps with accounting/book-keeping; we also use this during to avoid messing with (freeing/reusing) values that are 'unknown' to the pool.

    PoolParams Pools are "configured" with a set of parameters (the PoolParams) supplied via a provider. This set of parameters includes

    • maxSizeSoftCap The size of a pool includes its used and free space. The maxSize setting for a pool is a soft cap on the overall size of the pool. A key point is that get requests will not fail because the max size has been exceeded (unless the underlying alloc function fails). However, the pool's free portion will be trimmed as much as possible so that the pool's size may fall below the max size. Note that when the free portion has fallen to zero, the pool may still be larger than its maxSizeSoftCap. On a release request, the value will be 'freed' instead of being added to the free portion of the pool, if the pool exceeds its maxSizeSoftCap. The invariant we want to maintain - see ensurePoolSizeInvariant - is that the pool must be below the max size soft cap OR the free lists must be empty.
    • maxSizeHardCap The hard cap is a stronger limit on the pool size. When this limit is reached, we first attempt to trim the pool. If the pool size is still over the hard, the get call will fail with a PoolSizeViolationException
    • bucketSizes The pool can be configured with a set of 'sizes' - a bucket is created for each such size. Additionally, each bucket can have a a max-length specified, which is the sum of the used and free items in that bucket. As with the MaxSize parameter above, the maxLength here is a soft cap, in that it will not cause an exception on get; it simply controls the release path. If the BucketSizes parameter is null, then the pool will dynamically create buckets on demand.

    • Constructor Summary

      Constructors 
      Constructor Description
      BasePool(MemoryTrimmableRegistry memoryTrimmableRegistry, PoolParams poolParams, PoolStatsTracker poolStatsTracker) Creates a new instance of the pool.
      BasePool(MemoryTrimmableRegistry memoryTrimmableRegistry, PoolParams poolParams, PoolStatsTracker poolStatsTracker, boolean ignoreHardCap)

    • Method Summary

      Modifier and Type Method Description
      V get(int size) Gets a new 'value' from the pool, if available.
      void release(V value) Releases the given value to the pool.
      void trim(MemoryTrimType memoryTrimType) Trims the pool in response to low-memory states (invoked from MemoryManager) For now, we'll dothe simplest thing, and simply clear out the entire pool.
      synchronized Map<String, Integer> getStats() Export memory stats regarding buckets used, memory caps, reused values.

      • Methods inherited from class com.facebook.common.memory.Pool

        get, release

      • Methods inherited from class com.facebook.common.memory.MemoryTrimmable

        trim

      • Methods inherited from class java.lang.Object

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

    • Constructor Detail

      • BasePool

        BasePool(MemoryTrimmableRegistry memoryTrimmableRegistry, PoolParams poolParams, PoolStatsTracker poolStatsTracker)
        Creates a new instance of the pool.
        Parameters:
        poolParams - pool parameters

      • BasePool

        BasePool(MemoryTrimmableRegistry memoryTrimmableRegistry, PoolParams poolParams, PoolStatsTracker poolStatsTracker, boolean ignoreHardCap)

    • Method Detail

      • get

         V get(int size)

        Gets a new 'value' from the pool, if available. Allocates a new value if necessary. If we needto perform an allocation, - If the pool size exceeds the max-size soft cap, then we attempt totrim the free portion of the pool. - If the pool size exceeds the max-size hard-cap (aftertrimming), then we throw an PoolSizeViolationException Bucket length constraints arenot considered in this function

        Parameters:
        size - the logical size to allocate

      • release

         void release(V value)

        Releases the given value to the pool. In a few cases, the value is 'freed' instead of beingreleased to the pool. If - the pool currently exceeds its max size OR - if the value does notmap to a bucket that's currently maintained by the pool, OR - if the bucket for the valueexceeds its maxLength, OR - if the value is not recognized by the pool then, the value is'freed'.

        Parameters:
        value - the value to release to the pool

      • trim

         void trim(MemoryTrimType memoryTrimType)

        Trims the pool in response to low-memory states (invoked from MemoryManager) For now, we'll dothe simplest thing, and simply clear out the entire pool. We may consider more sophisticatedapproaches later. In other words, we ignore the memoryTrimType parameter

        Parameters:
        memoryTrimType - the kind of trimming we want to perform

      • getStats

         synchronized Map<String, Integer> getStats()

        Export memory stats regarding buckets used, memory caps, reused values.