You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@lucene.apache.org by us...@apache.org on 2015/02/05 11:33:18 UTC
svn commit: r1657522 - in /lucene/dev/branches/lucene_solr_5_0: ./ lucene/
lucene/core/ lucene/core/src/java/org/apache/lucene/store/
Author: uschindler
Date: Thu Feb 5 10:33:18 2015
New Revision: 1657522
URL: http://svn.apache.org/r1657522
Log:
Merged revision(s) 1657519 from lucene/dev/trunk:
Improve documentation a bit.
Modified:
lucene/dev/branches/lucene_solr_5_0/ (props changed)
lucene/dev/branches/lucene_solr_5_0/lucene/ (props changed)
lucene/dev/branches/lucene_solr_5_0/lucene/core/ (props changed)
lucene/dev/branches/lucene_solr_5_0/lucene/core/src/java/org/apache/lucene/store/FSDirectory.java
lucene/dev/branches/lucene_solr_5_0/lucene/core/src/java/org/apache/lucene/store/MMapDirectory.java
lucene/dev/branches/lucene_solr_5_0/lucene/core/src/java/org/apache/lucene/store/NIOFSDirectory.java
lucene/dev/branches/lucene_solr_5_0/lucene/core/src/java/org/apache/lucene/store/SimpleFSDirectory.java
Modified: lucene/dev/branches/lucene_solr_5_0/lucene/core/src/java/org/apache/lucene/store/FSDirectory.java
URL: http://svn.apache.org/viewvc/lucene/dev/branches/lucene_solr_5_0/lucene/core/src/java/org/apache/lucene/store/FSDirectory.java?rev=1657522&r1=1657521&r2=1657522&view=diff
==============================================================================
--- lucene/dev/branches/lucene_solr_5_0/lucene/core/src/java/org/apache/lucene/store/FSDirectory.java (original)
+++ lucene/dev/branches/lucene_solr_5_0/lucene/core/src/java/org/apache/lucene/store/FSDirectory.java Thu Feb 5 10:33:18 2015
@@ -24,6 +24,7 @@ import java.nio.file.DirectoryStream;
import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.StandardCopyOption;
+import java.nio.channels.ClosedChannelException; // javadoc @link
import java.util.ArrayList;
import java.util.Collection;
import java.util.List;
@@ -41,14 +42,14 @@ import org.apache.lucene.util.IOUtils;
*
* <ul>
*
- * <li> {@link SimpleFSDirectory} is a straightforward
+ * <li>{@link SimpleFSDirectory} is a straightforward
* implementation using Files.newByteChannel.
* However, it has poor concurrent performance
* (multiple threads will bottleneck) as it
* synchronizes when multiple threads read from the
* same file.
*
- * <li> {@link NIOFSDirectory} uses java.nio's
+ * <li>{@link NIOFSDirectory} uses java.nio's
* FileChannel's positional io when reading to avoid
* synchronization when reading from the same file.
* Unfortunately, due to a Windows-only <a
@@ -60,9 +61,7 @@ import org.apache.lucene.util.IOUtils;
* {@code RAFDirectory} instead. See {@link NIOFSDirectory} java doc
* for details.
*
- *
- *
- * <li> {@link MMapDirectory} uses memory-mapped IO when
+ * <li>{@link MMapDirectory} uses memory-mapped IO when
* reading. This is a good choice if you have plenty
* of virtual memory relative to your index size, eg
* if you are running on a 64 bit JRE, or you are
@@ -86,14 +85,9 @@ import org.apache.lucene.util.IOUtils;
* an important limitation to be aware of. This class supplies a
* (possibly dangerous) workaround mentioned in the bug report,
* which may fail on non-Sun JVMs.
- *
- * Applications using {@link Thread#interrupt()} or
- * {@link Future#cancel(boolean)} should use
- * {@code RAFDirectory} instead. See {@link MMapDirectory}
- * java doc for details.
* </ul>
*
- * Unfortunately, because of system peculiarities, there is
+ * <p>Unfortunately, because of system peculiarities, there is
* no single overall best implementation. Therefore, we've
* added the {@link #open} method, to allow Lucene to choose
* the best FSDirectory implementation given your
@@ -103,6 +97,15 @@ import org.apache.lucene.util.IOUtils;
* #open}. For all others, you should instantiate the
* desired implementation directly.
*
+ * <p><b>NOTE:</b> Accessing one of the above subclasses either directly or
+ * indirectly from a thread while it's interrupted can close the
+ * underlying channel immediately if at the same time the thread is
+ * blocked on IO. The channel will remain closed and subsequent access
+ * to the index will throw a {@link ClosedChannelException}.
+ * Applications using {@link Thread#interrupt()} or
+ * {@link Future#cancel(boolean)} should use the slower legacy
+ * {@code RAFDirectory} from the {@code misc} Lucene module instead.
+ *
* <p>The locking implementation is by default {@link
* NativeFSLockFactory}, but can be changed by
* passing in a custom {@link LockFactory} instance.
@@ -131,7 +134,7 @@ public abstract class FSDirectory extend
* The directory returned uses the {@link NativeFSLockFactory}.
* The directory is created at the named location if it does not yet exist.
*
- * <p>Currently this returns {@link MMapDirectory} for most Solaris
+ * <p>Currently this returns {@link MMapDirectory} for Linux, MacOSX, Solaris,
* and Windows 64-bit JREs, {@link NIOFSDirectory} for other
* non-Windows JREs, and {@link SimpleFSDirectory} for other
* JREs on Windows. It is highly recommended that you consult the
Modified: lucene/dev/branches/lucene_solr_5_0/lucene/core/src/java/org/apache/lucene/store/MMapDirectory.java
URL: http://svn.apache.org/viewvc/lucene/dev/branches/lucene_solr_5_0/lucene/core/src/java/org/apache/lucene/store/MMapDirectory.java?rev=1657522&r1=1657521&r2=1657522&view=diff
==============================================================================
--- lucene/dev/branches/lucene_solr_5_0/lucene/core/src/java/org/apache/lucene/store/MMapDirectory.java (original)
+++ lucene/dev/branches/lucene_solr_5_0/lucene/core/src/java/org/apache/lucene/store/MMapDirectory.java Thu Feb 5 10:33:18 2015
@@ -28,6 +28,7 @@ import java.security.AccessController;
import java.security.PrivilegedExceptionAction;
import java.security.PrivilegedActionException;
import java.util.Locale;
+import java.util.concurrent.Future;
import java.lang.reflect.Method;
import org.apache.lucene.store.ByteBufferIndexInput.BufferCleaner;
@@ -66,15 +67,19 @@ import org.apache.lucene.util.Constants;
* <p>This class supplies the workaround mentioned in the bug report
* (see {@link #setUseUnmap}), which may fail on
* non-Sun JVMs. It forcefully unmaps the buffer on close by using
- * an undocumented internal cleanup functionality.
- * {@link #UNMAP_SUPPORTED} is <code>true</code>, if the workaround
- * can be enabled (with no guarantees).
+ * an undocumented internal cleanup functionality. If
+ * {@link #UNMAP_SUPPORTED} is <code>true</code>, the workaround
+ * will be automatically enabled (with no guarantees; if you discover
+ * any problems, you can disable it).
* <p>
* <b>NOTE:</b> Accessing this class either directly or
* indirectly from a thread while it's interrupted can close the
* underlying channel immediately if at the same time the thread is
* blocked on IO. The channel will remain closed and subsequent access
- * to {@link MMapDirectory} will throw a {@link ClosedChannelException}.
+ * to {@link MMapDirectory} will throw a {@link ClosedChannelException}. If
+ * your application uses either {@link Thread#interrupt()} or
+ * {@link Future#cancel(boolean)} you should use the legacy {@code RAFDirectory}
+ * from the Lucene {@code misc} module in favor of {@link MMapDirectory}.
* </p>
* @see <a href="http://blog.thetaphi.de/2012/07/use-lucenes-mmapdirectory-on-64bit.html">Blog post about MMapDirectory</a>
*/
Modified: lucene/dev/branches/lucene_solr_5_0/lucene/core/src/java/org/apache/lucene/store/NIOFSDirectory.java
URL: http://svn.apache.org/viewvc/lucene/dev/branches/lucene_solr_5_0/lucene/core/src/java/org/apache/lucene/store/NIOFSDirectory.java?rev=1657522&r1=1657521&r2=1657522&view=diff
==============================================================================
--- lucene/dev/branches/lucene_solr_5_0/lucene/core/src/java/org/apache/lucene/store/NIOFSDirectory.java (original)
+++ lucene/dev/branches/lucene_solr_5_0/lucene/core/src/java/org/apache/lucene/store/NIOFSDirectory.java Thu Feb 5 10:33:18 2015
@@ -47,8 +47,8 @@ import java.util.concurrent.Future; // j
* blocked on IO. The file descriptor will remain closed and subsequent access
* to {@link NIOFSDirectory} will throw a {@link ClosedChannelException}. If
* your application uses either {@link Thread#interrupt()} or
- * {@link Future#cancel(boolean)} you should use {@code RAFDirectory} in
- * favor of {@link NIOFSDirectory}.
+ * {@link Future#cancel(boolean)} you should use the legacy {@code RAFDirectory}
+ * from the Lucene {@code misc} module in favor of {@link NIOFSDirectory}.
* </p>
*/
public class NIOFSDirectory extends FSDirectory {
Modified: lucene/dev/branches/lucene_solr_5_0/lucene/core/src/java/org/apache/lucene/store/SimpleFSDirectory.java
URL: http://svn.apache.org/viewvc/lucene/dev/branches/lucene_solr_5_0/lucene/core/src/java/org/apache/lucene/store/SimpleFSDirectory.java?rev=1657522&r1=1657521&r2=1657522&view=diff
==============================================================================
--- lucene/dev/branches/lucene_solr_5_0/lucene/core/src/java/org/apache/lucene/store/SimpleFSDirectory.java (original)
+++ lucene/dev/branches/lucene_solr_5_0/lucene/core/src/java/org/apache/lucene/store/SimpleFSDirectory.java Thu Feb 5 10:33:18 2015
@@ -21,9 +21,11 @@ import java.io.EOFException;
import java.io.IOException;
import java.nio.ByteBuffer;
import java.nio.channels.SeekableByteChannel;
+import java.nio.channels.ClosedChannelException; // javadoc @link
import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.StandardOpenOption;
+import java.util.concurrent.Future;
/** A straightforward implementation of {@link FSDirectory}
* using {@link Files#newByteChannel(Path, java.nio.file.OpenOption...)}.
@@ -31,7 +33,18 @@ import java.nio.file.StandardOpenOption;
* poor concurrent performance (multiple threads will
* bottleneck) as it synchronizes when multiple threads
* read from the same file. It's usually better to use
- * {@link NIOFSDirectory} or {@link MMapDirectory} instead. */
+ * {@link NIOFSDirectory} or {@link MMapDirectory} instead.
+ * <p>
+ * <b>NOTE:</b> Accessing this class either directly or
+ * indirectly from a thread while it's interrupted can close the
+ * underlying file descriptor immediately if at the same time the thread is
+ * blocked on IO. The file descriptor will remain closed and subsequent access
+ * to {@link SimpleFSDirectory} will throw a {@link ClosedChannelException}. If
+ * your application uses either {@link Thread#interrupt()} or
+ * {@link Future#cancel(boolean)} you should use the legacy {@code RAFDirectory}
+ * from the Lucene {@code misc} module in favor of {@link SimpleFSDirectory}.
+ * </p>
+ */
public class SimpleFSDirectory extends FSDirectory {
/** Create a new SimpleFSDirectory for the named location.