org.apache.lucene.facet.search

Class TemporaryObjectAllocator<T>

java.lang.Object

org.apache.lucene.facet.search.TemporaryObjectAllocator<T>

Direct Known Subclasses:

FloatArrayAllocator, IntArrayAllocator

public abstract class TemporaryObjectAllocator<T>
extends Object

An TemporaryObjectAllocator is an object which manages large, reusable, temporary objects needed during multiple concurrent computations. The idea is to remember some of the previously allocated temporary objects, and reuse them if possible to avoid constant allocation and garbage-collection of these objects.

This technique is useful for temporary counter arrays in faceted search (see FacetsAccumulator), which can be reused across searches instead of being allocated afresh on every search.

A TemporaryObjectAllocator is thread-safe.

WARNING: This API is experimental and might change in incompatible ways in the next release.

Constructor Summary

Constructors

Constructor and Description
TemporaryObjectAllocator(int maxObjects) Construct an allocator for objects of a certain type, keeping around a pool of up to maxObjects old objects.

Method Summary

Methods

Modifier and Type	Method and Description
T	allocate() Allocate a new object.
protected abstract void	clear(T object) Subclasses must override this method to clear an existing object of the desired type, to prepare it for reuse.
protected abstract T	create() Subclasses must override this method to actually create a new object of the desired type.
void	free(T object) Return a no-longer-needed object back to the pool.

Methods inherited from class java.lang.Object

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

Constructor Detail

TemporaryObjectAllocator

public TemporaryObjectAllocator(int maxObjects)

Construct an allocator for objects of a certain type, keeping around a pool of up to maxObjects old objects.

Note that the pool size only restricts the number of objects that hang around when not needed, but not the maximum number of objects that are allocated when actually is use: If a number of concurrent threads ask for an allocation, all of them will get an object, even if their number is greater than maxObjects. If an application wants to limit the number of concurrent threads making allocations, it needs to do so on its own - for example by blocking new threads until the existing ones have finished. If more than maxObjects are freed, only maxObjects of them will be kept in the pool - the rest will not and will eventually be garbage-collected by Java.

In particular, when maxObjects=0, this object behaves as a trivial allocator, always allocating a new array and never reusing an old one.

Method Detail

create

protected abstract T create()

Subclasses must override this method to actually create a new object of the desired type.

clear

protected abstract void clear(T object)

Subclasses must override this method to clear an existing object of the desired type, to prepare it for reuse. Note that objects will be cleared just before reuse (on allocation), not when freed.

allocate

public final T allocate()

Allocate a new object. If there's a previously allocated object in our pool, we return it immediately. Otherwise, a new object is allocated.

Don't forget to call free(Object) when you're done with the object, to return it to the pool. If you don't, memory is not leaked, but the pool will remain empty and a new object will be allocated each time (just like the maxArrays=0 case).

free

public final void free(T object)

Return a no-longer-needed object back to the pool. If we already have enough objects in the pool (maxObjects as specified in the constructor), the array will not be saved, and Java will eventually garbage collect it.

In particular, when maxArrays=0, the given array is never saved and free does nothing.