public class ArrayCache extends Object
When compressing or decompressing many (very) small files in a row, the time spent in construction of new compressor or decompressor objects can be longer than the time spent in actual compression or decompression. A large part of this initialization overhead comes from allocation and garbage collection of large arrays.
The ArrayCache
API provides a way to cache large array allocations
for reuse. It can give a major performance improvement when compressing or
decompressing many tiny files. If you are only (de)compressing one or two
files or the files a very big, array caching won't improve anything,
although it won't make anything slower either.
Important: The users of ArrayCache don't return the allocated arrays
back to the cache in all situations.
This a reason why it's called a cache instead of a pool.
If it is important to be able to return every array back to a cache,
ResettableArrayCache
can be useful.
In compressors (OutputStreams) the arrays are returned to the cache
when a call to finish()
or close()
returns
successfully (no exceptions are thrown).
In decompressors (InputStreams) the arrays are returned to the cache when
the decompression is successfully finished (read
returns -1
)
or close()
or close(boolean)
is called. This is true even
if closing throws an exception.
Raw decompressors don't support close(boolean)
. With raw
decompressors, if one wants to put the arrays back to the cache without
closing the underlying InputStream
, one can wrap the
InputStream
into CloseIgnoringInputStream
when creating
the decompressor instance. Then one can use close()
.
Different cache implementations can be extended from this base class. All cache implementations must be thread safe.
This class also works as a dummy cache that simply calls new
to allocate new arrays and doesn't try to cache anything. A statically
allocated dummy cache is available via getDummyCache()
.
If no ArrayCache
is specified when constructing a compressor or
decompressor, the default ArrayCache
implementation is used.
See getDefaultCache()
and setDefaultCache(ArrayCache)
.
This is a class instead of an interface because it's possible that in the future we may want to cache other array types too. New methods can be added to this class without breaking existing cache implementations.
BasicArrayCache
Constructor and Description |
---|
ArrayCache()
Creates a new
ArrayCache that does no caching
(a dummy cache). |
Modifier and Type | Method and Description |
---|---|
byte[] |
getByteArray(int size,
boolean fillWithZeros)
Allocates a new byte array.
|
static ArrayCache |
getDefaultCache()
Gets the default
ArrayCache instance. |
static ArrayCache |
getDummyCache()
Returns a statically-allocated
ArrayCache instance. |
int[] |
getIntArray(int size,
boolean fillWithZeros)
Allocates a new int array.
|
void |
putArray(byte[] array)
Puts the given byte array to the cache.
|
void |
putArray(int[] array)
Puts the given int array to the cache.
|
static void |
setDefaultCache(ArrayCache arrayCache)
Sets the default
ArrayCache instance. |
public ArrayCache()
ArrayCache
that does no caching
(a dummy cache). If you need a dummy cache, you may want to call
getDummyCache()
instead.public static ArrayCache getDummyCache()
ArrayCache
instance.
It can be shared by all code that needs a dummy cache.public static ArrayCache getDefaultCache()
ArrayCache
instance.
This is a global cache that is used when the application
specifies nothing else. The default is a dummy cache
(see getDummyCache()
).public static void setDefaultCache(ArrayCache arrayCache)
ArrayCache
instance.
Use with care. Other libraries using this package probably shouldn't
call this function as libraries cannot know if there are other users
of the xz package in the same application.public byte[] getByteArray(int size, boolean fillWithZeros)
This implementation simply returns new byte[size]
.
size
- the minimum size of the array to allocate;
an implementation may return an array that
is larger than the given size
fillWithZeros
- 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
arraypublic void putArray(byte[] array)
This implementation does nothing.
public int[] getIntArray(int size, boolean fillWithZeros)
This implementation simply returns new int[size]
.
size
- the minimum size of the array to allocate;
an implementation may return an array that
is larger than the given size
fillWithZeros
- 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
arraypublic void putArray(int[] array)
This implementation does nothing.