svn commit: r1305816 - in /lucene/dev/branches/branch_3x/lucene: CHANGES.txt core/src/java/org/apache/lucene/store/RAMDirectory.java

[us...@apache.org]

Author: uschindler
Date: Tue Mar 27 11:47:24 2012
New Revision: 1305816

URL: http://svn.apache.org/viewvc?rev=1305816&view=rev
Log:
LUCENE-3926: Improve documentation of RAMDirectory

Modified:
    lucene/dev/branches/branch_3x/lucene/CHANGES.txt
    lucene/dev/branches/branch_3x/lucene/core/src/java/org/apache/lucene/store/RAMDirectory.java

Modified: lucene/dev/branches/branch_3x/lucene/CHANGES.txt
URL: http://svn.apache.org/viewvc/lucene/dev/branches/branch_3x/lucene/CHANGES.txt?rev=1305816&r1=1305815&r2=1305816&view=diff
==============================================================================
--- lucene/dev/branches/branch_3x/lucene/CHANGES.txt (original)
+++ lucene/dev/branches/branch_3x/lucene/CHANGES.txt Tue Mar 27 11:47:24 2012
@@ -293,7 +293,20 @@ Optimizations
 
 Documentation
 
-* LUCENE-3597: Fixed incorrect grouping documentation. (Martijn van Groningen, Robert Muir)
+* LUCENE-3597: Fixed incorrect grouping documentation. (Martijn van Groningen,
+  Robert Muir)
+
+* LUCENE-3926: Improve documentation of RAMDirectory, because this
+  class is not intended to work with huge indexes. Everything beyond
+  several hundred megabytes will waste resources (GC cycles), because
+  it uses an internal buffer size of 1024 bytes, producing millions of 
+  byte[1024] arrays. This class is optimized for small memory-resident
+  indexes. It also has bad concurrency on multithreaded environments.
+  It is recommended to materialize large indexes on disk and use
+  MMapDirectory, which is a high-performance directory implementation
+  working directly on the file system cache of the operating system,
+  so copying data to Java heap space is not useful.  (Uwe Schindler,
+  Mike McCandless, Robert Muir)
 
 Build
 

Modified: lucene/dev/branches/branch_3x/lucene/core/src/java/org/apache/lucene/store/RAMDirectory.java
URL: http://svn.apache.org/viewvc/lucene/dev/branches/branch_3x/lucene/core/src/java/org/apache/lucene/store/RAMDirectory.java?rev=1305816&r1=1305815&r2=1305816&view=diff
==============================================================================
--- lucene/dev/branches/branch_3x/lucene/core/src/java/org/apache/lucene/store/RAMDirectory.java (original)
+++ lucene/dev/branches/branch_3x/lucene/core/src/java/org/apache/lucene/store/RAMDirectory.java Tue Mar 27 11:47:24 2012
@@ -34,6 +34,18 @@ import org.apache.lucene.util.ThreadInte
  * A memory-resident {@link Directory} implementation.  Locking
  * implementation is by default the {@link SingleInstanceLockFactory}
  * but can be changed with {@link #setLockFactory}.
+ * 
+ * <p><b>Warning:</b> This class is not intended to work with huge
+ * indexes. Everything beyond several hundred megabytes will waste
+ * resources (GC cycles), because it uses an internal buffer size
+ * of 1024 bytes, producing millions of {@code byte[1024]} arrays.
+ * This class is optimized for small memory-resident indexes.
+ * It also has bad concurrency on multithreaded environments.
+ * 
+ * <p>It is recommended to materialize large indexes on disk and use
+ * {@link MMapDirectory}, which is a high-performance directory
+ * implementation working directly on the file system cache of the
+ * operating system, so copying data to Java heap space is not useful.
  */
 public class RAMDirectory extends Directory implements Serializable {
 
@@ -59,10 +71,20 @@ public class RAMDirectory extends Direct
    * Creates a new <code>RAMDirectory</code> instance from a different
    * <code>Directory</code> implementation.  This can be used to load
    * a disk-based index into memory.
-   * <P>
-   * This should be used only with indices that can fit into memory.
-   * <P>
-   * Note that the resulting <code>RAMDirectory</code> instance is fully
+   * 
+   * <p><b>Warning:</b> This class is not intended to work with huge
+   * indexes. Everything beyond several hundred megabytes will waste
+   * resources (GC cycles), because it uses an internal buffer size
+   * of 1024 bytes, producing millions of {@code byte[1024]} arrays.
+   * This class is optimized for small memory-resident indexes.
+   * It also has bad concurrency on multithreaded environments.
+   * 
+   * <p>For disk-based indexes it is recommended to use
+   * {@link MMapDirectory}, which is a high-performance directory
+   * implementation working directly on the file system cache of the
+   * operating system, so copying data to Java heap space is not useful.
+   * 
+   * <p>Note that the resulting <code>RAMDirectory</code> instance is fully
    * independent from the original <code>Directory</code> (it is a
    * complete copy).  Any subsequent changes to the
    * original <code>Directory</code> will not be visible in the