Interfaces

Classes

Annotations

BitmapPoolType

Exceptions

Packages | Classes

public abstract class

BasePool

extends Object
implements Pool<V>

| Known Direct Subclasses

BucketsBitmapPool, GenericByteArrayPool, MemoryChunkPool

| Known Indirect Subclasses

AshmemMemoryChunkPool, BufferMemoryChunkPool, NativeMemoryChunkPool

Class Overview

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(int) - 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(V) - 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(int) - returns the bucketized size for the given request size
getBucketedSizeForValue(Object) - returns the bucketized size for a given value
getSizeInBytes(int) - gets the size in bytes for a given bucketized size
alloc(int) - allocates a value of given size
free(Object) - frees the value V Subclasses may optionally implement
onParamsChanged() - called whenever this class determines to re-read the pool params
isReusable(Object) - 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 release(Object) 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(int) requests will not fail because the max size has been exceeded (unless the underlying alloc(int) 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(Object) 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(int) call will fail with a BasePool.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.

Summary

Nested Classes
class
class
class
class

Public Constructors

Creates a new instance of the pool.

Public Methods
V
Gets a new 'value' from the pool, if available.

synchronized Map<String, Integer>
Export memory stats regarding buckets used, memory caps, reused values.

void
Releases the given value to the pool.

void
Trims the pool in response to low-memory states (invoked from MemoryManager) For now, we'll do the simplest thing, and simply clear out the entire pool.

Protected Methods
abstract V
Allocates a new 'value' with the given size

abstract void
Frees the 'value'

abstract int
Gets the bucketed size (typically something the same or larger than the requested size)

abstract int
Gets the bucketed size of the value

abstract int
Gets the size in bytes for the given bucketed size

synchronized V
void
Finish pool initialization.

boolean
Determines if the supplied value is 'reusable'.

void
The pool parameters may have changed.

| [Expand] Inherited Methods | | --- | | From class java.lang.Object

| | From interface com.facebook.common.memory.MemoryTrimmable

| abstract void | trim(MemoryTrimType trimType) Trim memory. |

| | From interface com.facebook.common.memory.Pool

| | From interface com.facebook.common.references.ResourceReleaser

| abstract void | release(T value) Release the given value. |

Public Constructors

public BasePool(MemoryTrimmableRegistry memoryTrimmableRegistry, PoolParams poolParams, PoolStatsTracker poolStatsTracker)

Creates a new instance of the pool.

Parameters

| poolParams | pool parameters |

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

Public Methods

public V get(int size)

Gets a new 'value' from the pool, if available. Allocates a new value if necessary. If we need to perform an allocation, - If the pool size exceeds the max-size soft cap, then we attempt to trim the free portion of the pool. - If the pool size exceeds the max-size hard-cap (after trimming), then we throw an BasePool.PoolSizeViolationException Bucket length constraints are not considered in this function

Parameters

| size | the logical size to allocate |

Returns

a new value

Throws

| BasePool.InvalidSizeException | |

public synchronized Map<String, Integer> getStats()

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

public void release(V value)

Releases the given value to the pool. In a few cases, the value is 'freed' instead of being released to the pool. If - the pool currently exceeds its max size OR - if the value does not map to a bucket that's currently maintained by the pool, OR - if the bucket for the value exceeds 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 |

public void trim(MemoryTrimType memoryTrimType)

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

Parameters

| memoryTrimType | the kind of trimming we want to perform |

Protected Methods

protected abstract V alloc(int bucketedSize)

Allocates a new 'value' with the given size

Parameters

| bucketedSize | the logical size to allocate |

Returns

a new value

protected abstract void free(V value)

Frees the 'value'

Parameters

| value | the value to free |

protected abstract int getBucketedSize(int requestSize)

Gets the bucketed size (typically something the same or larger than the requested size)

Parameters

| requestSize | the logical request size |

Returns

the 'bucketed' size

Throws

| | if the size of the value doesn't match the pool's constraints |

protected abstract int getBucketedSizeForValue(V value)

Gets the bucketed size of the value

Parameters

| value | the value |

Returns

bucketed size of the value

Throws

| | if the size of the value doesn't match the pool's constraints | | | if the value is invalid |

protected abstract int getSizeInBytes(int bucketedSize)

Gets the size in bytes for the given bucketed size

Parameters

| bucketedSize | the bucketed size |

Returns

size in bytes

protected synchronized V getValue(Bucket<V> bucket)

protected void initialize()

Finish pool initialization.

protected boolean isReusable(V value)

Determines if the supplied value is 'reusable'. This is called during release(Object), and determines if the value can be added to the freelists of the pool (for future reuse), or must be released right away. Subclasses can override this to provide custom implementations

Parameters

| value | the value to test for reusability |

Returns

true if the value is reusable

protected void onParamsChanged()

The pool parameters may have changed. Subclasses can override this to update any state they were maintaining

+Generated by Doclava. +