pylucene 3.5.0-3

[pylucene.git] / lucene-java-3.5.0 / lucene / contrib / facet / src / java / org / apache / lucene / facet / search / TemporaryObjectAllocator.java

diff --git a/lucene-java-3.5.0/lucene/contrib/facet/src/java/org/apache/lucene/facet/search/TemporaryObjectAllocator.java b/lucene-java-3.5.0/lucene/contrib/facet/src/java/org/apache/lucene/facet/search/TemporaryObjectAllocator.java
new file mode 100644 (file)
index 0000000..5b219e4
--- /dev/null
+++ b/lucene-java-3.5.0/lucene/contrib/facet/src/java/org/apache/lucene/facet/search/TemporaryObjectAllocator.java
@@ -0,0 +1,114 @@
+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);
+    }
+  }
+
+}