A basic ArrayCache implementation.

This caches exact array sizes, that is, getByteArray will return an array whose size is exactly the requested size. A limited number of different array sizes are cached at the same time; least recently used sizes will be dropped from the cache if needed (can happen if several different (de)compression options are used with the same cache).

The current implementation uses LinkedHashMap to map different array sizes to separate array-based data structures which hold SoftReferences to the cached arrays. In the common case this should give good performance and fairly low memory usage overhead.

A statically allocated global BasicArrayCache instance is available via getInstance() which is a good choice in most situations where caching is wanted.

Nested and Inner Type Summary

Modifier and Type	Class and Description
private static class	BasicArrayCache.CacheMap<T> Maps Integer (array size) to stacks of references to arrays.
private static class	BasicArrayCache.CyclicStack<T> A thread-safe stack-like data structure whose `push` method overwrites the oldest element in the stack if the stack is full.
private static class	BasicArrayCache.LazyHolder Helper class for the singleton instance.

Field Summary

Modifier and Type	Field and Description
private final BasicArrayCache.CacheMap<byte[]>	byteArrayCache Stacks for cached byte arrays.
private static final int	CACHEABLE_SIZE_MIN Arrays smaller than this many elements will not be cached.
private static final int	ELEMENTS_PER_STACK Number of arrays of the same type and size to keep in the cache.
private final BasicArrayCache.CacheMap<int[]>	intArrayCache Stacks for cached int arrays.
private static final int	STACKS_MAX Number of stacks i.e. how many different array sizes to cache.

Access	Constructor and Description
public	BasicArrayCache()

Method Summary

Modifier and Type	Method and Description
private static <T> T	getArray(BasicArrayCache.CacheMap<T> cache, int size) Gets `T[size]` from the given `cache`.
public byte[]	getByteArray(int size of the array to allocate size, boolean if true, all the elements of the returned array will be zero; if false, the contents of the returned array is undefined fillWithZeros) Overrides org.tukaani.xz.ArrayCache.getByteArray. Allocates a new byte array, hopefully reusing an existing array from the cache.
public static BasicArrayCache	getInstance() Returns a statically-allocated `BasicArrayCache` instance.
public int[]	getIntArray(int the minimum size of the array to allocate; an implementation may return an array that is larger than the given `size` size, boolean if true, the caller expects that the first `size` elements in the array are zero; if false, the array contents can be anything, which speeds things up when reusing a cached array fillWithZeros) Overrides org.tukaani.xz.ArrayCache.getIntArray. This is like getByteArray but for int arrays.
private static <T> void	putArray(BasicArrayCache.CacheMap<T> cache, T array, int size) Puts the `array` of `size` elements long into the `cache`.
public void	putArray(byte[] array) Overrides org.tukaani.xz.ArrayCache.putArray. Puts the given byte array to the cache.
public void	putArray(int[] array) Overrides org.tukaani.xz.ArrayCache.putArray. Puts the given int array to the cache.

Inherited from org.tukaani.xz.ArrayCache:: getDefaultCache getDummyCache setDefaultCache

Field Detail

byteArrayCache	back to summary
private final BasicArrayCache.CacheMap<byte[]> byteArrayCache Stacks for cached byte arrays.

CACHEABLE_SIZE_MIN	back to summary
private static final int CACHEABLE_SIZE_MIN Arrays smaller than this many elements will not be cached.

ELEMENTS_PER_STACK	back to summary
private static final int ELEMENTS_PER_STACK Number of arrays of the same type and size to keep in the cache. (ELEMENTS_PER_STACK - 1) is used as a bit mask so ELEMENTS_PER_STACK must be a power of two!

intArrayCache	back to summary
private final BasicArrayCache.CacheMap<int[]> intArrayCache Stacks for cached int arrays.

STACKS_MAX	back to summary
private static final int STACKS_MAX Number of stacks i.e. how many different array sizes to cache.

BasicArrayCache	back to summary
public BasicArrayCache()

Method Detail

getArray	back to summary
private static <T> T getArray(BasicArrayCache.CacheMap<T> cache, int size) Gets `T[size]` from the given `cache`. If no such array is found, `null` is returned.

getByteArray	back to summary
public byte[] getByteArray(int size, boolean fillWithZeros) Overrides org.tukaani.xz.ArrayCache.getByteArray. Allocates a new byte array, hopefully reusing an existing array from the cache. Parameters size:int size of the array to allocate fillWithZeros:boolean if true, all the elements of the returned array will be zero; if false, the contents of the returned array is undefined

getByteArray

back to summary

public byte[] getByteArray(int size, boolean fillWithZeros)

Overrides org.tukaani.xz.ArrayCache.getByteArray.

Allocates a new byte array, hopefully reusing an existing array from the cache.

Parameters

size:int: size of the array to allocate
fillWithZeros:boolean: if true, all the elements of the returned array will be zero; if false, the contents of the returned array is undefined

getInstance	back to summary
public static BasicArrayCache getInstance() Returns a statically-allocated `BasicArrayCache` instance. This is often a good choice when a cache is needed.

getIntArray back to summary

getIntArray	back to summary
public int[] getIntArray(int size, boolean fillWithZeros) Overrides org.tukaani.xz.ArrayCache.getIntArray. This is like getByteArray but for int arrays. Parameters size:int Doc from org.tukaani.xz.ArrayCache.getIntArray. the minimum size of the array to allocate; an implementation may return an array that is larger than the given `size` fillWithZeros:boolean Doc from org.tukaani.xz.ArrayCache.getIntArray. if true, the caller expects that the first `size` elements in the array are zero; if false, the array contents can be anything, which speeds things up when reusing a cached array

public int[] getIntArray(int size, boolean fillWithZeros)

Overrides org.tukaani.xz.ArrayCache.getIntArray.

This is like getByteArray but for int arrays.

Parameters

size:int

Doc from org.tukaani.xz.ArrayCache.getIntArray.

the minimum size of the array to allocate; an implementation may return an array that is larger than the given size

fillWithZeros:boolean

Doc from org.tukaani.xz.ArrayCache.getIntArray.

if true, the caller expects that the first size elements in the array are zero; if false, the array contents can be anything, which speeds things up when reusing a cached array

putArray	back to summary
private static <T> void putArray(BasicArrayCache.CacheMap<T> cache, T array, int size) Puts the `array` of `size` elements long into the `cache`.

putArray	back to summary
public void putArray(byte[] array) Overrides org.tukaani.xz.ArrayCache.putArray. Puts the given byte array to the cache. The caller must no longer use the array. Small arrays aren't cached and will be ignored by this method.

putArray

back to summary

public void putArray(byte[] array)

Overrides org.tukaani.xz.ArrayCache.putArray.

Puts the given byte array to the cache. The caller must no longer use the array.

Small arrays aren't cached and will be ignored by this method.

putArray	back to summary
public void putArray(int[] array) Overrides org.tukaani.xz.ArrayCache.putArray. Puts the given int array to the cache. The caller must no longer use the array. Small arrays aren't cached and will be ignored by this method.

putArray

back to summary

public void putArray(int[] array)

Overrides org.tukaani.xz.ArrayCache.putArray.

Puts the given int array to the cache. The caller must no longer use the array.

Small arrays aren't cached and will be ignored by this method.

org.tukaani.xz back to summary

private Class BasicArrayCache.CacheMap<T>

Class Inheritance

extends LinkedHashMap<Integer, BasicArrayCache.CyclicStack<Reference<T>>>

Maps Integer (array size) to stacks of references to arrays. At most STACKS_MAX number of stacks are kept in the map (LRU cache).

Field Summary

Modifier and Type	Field and Description
private static final long	serialVersionUID Hides java.util.LinkedHashMap.serialVersionUID. This class won't be serialized but this is needed to silence a compiler warning.

Constructor Summary

Access	Constructor and Description
public	CacheMap() Creates a new CacheMap.

Method Summary

Modifier and Type Method and Description

Modifier and Type	Method and Description
protected boolean	removeEldestEntry(Map.Entry<Integer, BasicArrayCache.CyclicStack<Reference<T>>> The least recently inserted entry in the map, or if this is an access-ordered map, the least recently accessed entry. This is the entry that will be removed if this method returns `true`. If the map was empty prior to the `put` or `putAll` invocation resulting in this invocation, this will be the entry that was just inserted; in other words, if the map contains a single entry, the eldest entry is also the newest. eldest) Overrides java.util.LinkedHashMap.removeEldestEntry. Returns true if the map is full and the least recently used stack should be removed.

protected boolean

removeEldestEntry(Map.Entry<Integer, BasicArrayCache.CyclicStack<Reference<T>>>

The least recently inserted entry in the map, or if this is an access-ordered map, the least recently accessed entry. This is the entry that will be removed if this method returns true. If the map was empty prior to the put or putAll invocation resulting in this invocation, this will be the entry that was just inserted; in other words, if the map contains a single entry, the eldest entry is also the newest.

eldest)

Overrides java.util.LinkedHashMap.removeEldestEntry.

Returns true if the map is full and the least recently used stack should be removed.

Inherited from java.util.LinkedHashMap:: clear containsValue entrySet forEach get getOrDefault keySet newLinkedHashMap putFirst putLast replaceAll reversed sequencedEntrySet sequencedKeySet sequencedValues values

Field Detail

serialVersionUID	back to summary
private static final long serialVersionUID Hides java.util.LinkedHashMap.serialVersionUID. This class won't be serialized but this is needed to silence a compiler warning.

serialVersionUID

back to summary

private static final long serialVersionUID

Hides java.util.LinkedHashMap.serialVersionUID.

This class won't be serialized but this is needed to silence a compiler warning.

Constructor Detail

CacheMap	back to summary
public CacheMap() Creates a new CacheMap.

Method Detail

removeEldestEntry back to summary

removeEldestEntry	back to summary
protected boolean removeEldestEntry(Map.Entry<Integer, BasicArrayCache.CyclicStack<Reference<T>>> eldest) Overrides java.util.LinkedHashMap.removeEldestEntry. Returns true if the map is full and the least recently used stack should be removed. Parameters eldest:Map.Entry<Integer, BasicArrayCache.CyclicStack<Reference<T>>> Doc from java.util.LinkedHashMap.removeEldestEntry. The least recently inserted entry in the map, or if this is an access-ordered map, the least recently accessed entry. This is the entry that will be removed if this method returns `true`. If the map was empty prior to the `put` or `putAll` invocation resulting in this invocation, this will be the entry that was just inserted; in other words, if the map contains a single entry, the eldest entry is also the newest. Returns:boolean Doc from java.util.LinkedHashMap.removeEldestEntry. `true` if the eldest entry should be removed from the map; `false` if it should be retained.

protected boolean removeEldestEntry(Map.Entry<Integer, BasicArrayCache.CyclicStack<Reference<T>>> eldest)

Overrides java.util.LinkedHashMap.removeEldestEntry.

Returns true if the map is full and the least recently used stack should be removed.

Parameters

eldest:Map.Entry<Integer, BasicArrayCache.CyclicStack<Reference<T>>>

Doc from java.util.LinkedHashMap.removeEldestEntry.

Returns:boolean

Doc from java.util.LinkedHashMap.removeEldestEntry.

true if the eldest entry should be removed from the map; false if it should be retained.

org.tukaani.xz back to summary

private Class BasicArrayCache.CyclicStack<T>

Class Inheritance

extends Object

java.lang.Object
org.tukaani.xz.BasicArrayCache.CyclicStack

A thread-safe stack-like data structure whose push method overwrites the oldest element in the stack if the stack is full.

Field Summary

Modifier and Type	Field and Description
private final T[]	elements Array that holds the elements in the cyclic stack.
private int	pos Read-write position in the `refs` array.

Constructor Summary

Access	Constructor and Description
private	CyclicStack()

Method Summary

Modifier and Type	Method and Description
public synchronized T	pop() Gets the most recently added element from the stack.
public synchronized void	push(T e) Adds a new element to the stack.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Field Detail

elements	back to summary
private final T[] elements Array that holds the elements in the cyclic stack. Annotations @SuppressWarnings:unchecked

pos back to summary

pos	back to summary
private int pos Read-write position in the `refs` array. The most recently added element is in `refs[pos]`. If it is `null`, then the stack is empty and all elements in `refs` are `null`. Note that `pop()` always modifies `pos`, even if the stack is empty. This means that when the first element is added by `push(T)`, it can get added in any position in `refs` and the stack will start growing from there.

private int pos

Read-write position in the refs array. The most recently added element is in refs[pos]. If it is null, then the stack is empty and all elements in refs are null.

Note that pop() always modifies pos, even if the stack is empty. This means that when the first element is added by push(T), it can get added in any position in refs and the stack will start growing from there.

Constructor Detail

CyclicStack	back to summary
private CyclicStack()

Method Detail

pop	back to summary
public synchronized T pop() Gets the most recently added element from the stack. If the stack is empty, `null` is returned.

push	back to summary
public synchronized void push(T e) Adds a new element to the stack. If the stack is full, the oldest element is overwritten.

org.tukaani.xz back to summary

private final Class BasicArrayCache.LazyHolder

Class Inheritance

extends Object

java.lang.Object
org.tukaani.xz.BasicArrayCache.LazyHolder

Helper class for the singleton instance. This is allocated only if getInstance() is called.

Field Summary

Modifier and Type	Field and Description
pack-priv static final BasicArrayCache	INSTANCE

Constructor Summary

Access	Constructor and Description
private	LazyHolder()

Method Summary

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Field Detail

INSTANCE	back to summary
pack-priv static final BasicArrayCache INSTANCE

Constructor Detail

LazyHolder	back to summary
private LazyHolder()

public Class BasicArrayCache

Nested and Inner Type Summary

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail

private Class BasicArrayCache.CacheMap<T>

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail

private Class BasicArrayCache.CyclicStack<T>

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail

private final Class BasicArrayCache.LazyHolder

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail