package org.apache.lucene.facet.search;
import java.util.concurrent.ConcurrentLinkedQueue;
/*
* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* The ASF licenses this file to You under the Apache License, Version 2.0
* (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
/**
* 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.
* <P>
* This technique is useful for temporary counter arrays in faceted search
* (see {@link FacetsAccumulator}), which can be reused across searches instead
* of being allocated afresh on every search.
* <P>
* A TemporaryObjectAllocator is thread-safe.
*
* @lucene.experimental
*/
public abstract class TemporaryObjectAllocator<T> {
// In the "pool" we hold up to "maxObjects" old objects, and if the pool
// is not empty, we return one of its objects rather than allocating a new
// one.
ConcurrentLinkedQueue<T> pool = new ConcurrentLinkedQueue<T>();
int maxObjects;
/**
* Construct an allocator for objects of a certain type, keeping around a
* pool of up to <CODE>maxObjects</CODE> old objects.
* <P>
* Note that the pool size only restricts the number of objects that hang
* around when not needed, but <I>not</I> 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.
* <P>
* In particular, when maxObjects=0, this object behaves as a trivial
* allocator, always allocating a new array and never reusing an old one.
*/
public TemporaryObjectAllocator(int maxObjects) {
this.maxObjects = maxObjects;
}
/**
* Subclasses must override this method to actually create a new object
* of the desired type.
*
*/
protected abstract T create();
/**
* 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.
*/
protected abstract void clear(T object);
/**
* Allocate a new object. If there's a previously allocated object in our
* pool, we return it immediately. Otherwise, a new object is allocated.
* <P>
* Don't forget to call {@link #free(Object)} when you're done with the object,
* to return it to the pool. If you don't, memory is <I>not</I> leaked,
* but the pool will remain empty and a new object will be allocated each
* time (just like the maxArrays=0 case).
*/
public final T allocate() {
T object = pool.poll();
if (object==null) {
return create();
}
clear(object);
return 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.
* <P>
* In particular, when maxArrays=0, the given array is never saved and
* free does nothing.
*/
public final void free(T object) {
if (pool.size() < maxObjects && object != null) {
pool.add(object);
}
}
}