src/org/tukaani/xz/ArrayCache.java

/*
 * ArrayCache
 *
 * Author: Lasse Collin <lasse.collin@tukaani.org>
 *
 * This file has been put into the public domain.
 * You can do whatever you want with this file.
 */

package org.tukaani.xz;

/**
 * Caches large arrays for reuse (base class and a dummy cache implementation).
 * <p>
 * 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.
 * <p>
 * The {@code 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.
 * <p>
 * <b>Important: The users of ArrayCache don't return the allocated arrays
 * back to the cache in all situations.</b>
 * 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,
 * {@link ResettableArrayCache} can be useful.
 * <p>
 * In compressors (OutputStreams) the arrays are returned to the cache
 * when a call to {@code finish()} or {@code close()} returns
 * successfully (no exceptions are thrown).
 * <p>
 * In decompressors (InputStreams) the arrays are returned to the cache when
 * the decompression is successfully finished ({@code read} returns {@code -1})
 * or {@code close()} or {@code close(boolean)} is called. This is true even
 * if closing throws an exception.
 * <p>
 * Raw decompressors don't support {@code close(boolean)}. With raw
 * decompressors, if one wants to put the arrays back to the cache without
 * closing the underlying {@code InputStream}, one can wrap the
 * {@code InputStream} into {@link CloseIgnoringInputStream} when creating
 * the decompressor instance. Then one can use {@code close()}.
 * <p>
 * Different cache implementations can be extended from this base class.
 * All cache implementations must be thread safe.
 * <p>
 * This class also works as a dummy cache that simply calls {@code new}
 * to allocate new arrays and doesn't try to cache anything. A statically
 * allocated dummy cache is available via {@link #getDummyCache()}.
 * <p>
 * If no {@code ArrayCache} is specified when constructing a compressor or
 * decompressor, the default {@code ArrayCache} implementation is used.
 * See {@link #getDefaultCache()} and {@link #setDefaultCache(ArrayCache)}.
 * <p>
 * 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.
 *
 * @since 1.7
 *
 * @see BasicArrayCache
 */
public class ArrayCache {
    /**
     * Global dummy cache instance that is returned by {@code getDummyCache()}.
     */
    private static final ArrayCache dummyCache = new ArrayCache();

    /**
     * Global default {@code ArrayCache} that is used when no other cache has
     * been specified.
     */
    private static volatile ArrayCache defaultCache = dummyCache;

    /**
     * Returns a statically-allocated {@code ArrayCache} instance.
     * It can be shared by all code that needs a dummy cache.
     */
    public static ArrayCache getDummyCache() {
        return dummyCache;
    }

    /**
     * Gets the default {@code ArrayCache} instance.
     * This is a global cache that is used when the application
     * specifies nothing else. The default is a dummy cache
     * (see {@link #getDummyCache()}).
     */
    public static ArrayCache getDefaultCache() {
        // It's volatile so no need for synchronization.
        return defaultCache;
    }

    /**
     * Sets the default {@code 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 static void setDefaultCache(ArrayCache arrayCache) {
        if (arrayCache == null)
            throw new NullPointerException();

        // It's volatile so no need for synchronization.
        defaultCache = arrayCache;
    }

    /**
     * Creates a new {@code ArrayCache} that does no caching
     * (a dummy cache). If you need a dummy cache, you may want to call
     * {@link #getDummyCache()} instead.
     */
    public ArrayCache() {}

    /**
     * Allocates a new byte array.
     * <p>
     * This implementation simply returns {@code new byte[size]}.
     *
     * @param   size            the minimum size of the array to allocate;
     *                          an implementation may return an array that
     *                          is larger than the given {@code size}
     *
     * @param   fillWithZeros   if true, the caller expects that the first
     *                          {@code 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 byte[] getByteArray(int size, boolean fillWithZeros) {
        return new byte[size];
    }

    /**
     * Puts the given byte array to the cache. The caller must no longer
     * use the array.
     * <p>
     * This implementation does nothing.
     */
    public void putArray(byte[] array) {}

    /**
     * Allocates a new int array.
     * <p>
     * This implementation simply returns {@code new int[size]}.
     *
     * @param   size            the minimum size of the array to allocate;
     *                          an implementation may return an array that
     *                          is larger than the given {@code size}
     *
     * @param   fillWithZeros   if true, the caller expects that the first
     *                          {@code 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) {
        return new int[size];
    }

    /**
     * Puts the given int array to the cache. The caller must no longer
     * use the array.
     * <p>
     * This implementation does nothing.
     */
    public void putArray(int[] array) {}
}