From 6574743bcd3734de5d3330b0b1d5a9e50ae0164d Mon Sep 17 00:00:00 2001 From: Uwe Schindler Date: Thu, 5 Feb 2015 10:31:33 +0000 Subject: [PATCH] Improve documentation a bit. git-svn-id: https://svn.apache.org/repos/asf/lucene/dev/trunk@1657519 13f79535-47bb-0310-9956-ffa450edef68 --- .../org/apache/lucene/store/FSDirectory.java | 27 ++++++++++--------- .../apache/lucene/store/MMapDirectory.java | 13 ++++++--- .../apache/lucene/store/NIOFSDirectory.java | 4 +-- .../lucene/store/SimpleFSDirectory.java | 15 ++++++++++- 4 files changed, 40 insertions(+), 19 deletions(-) diff --git a/lucene/core/src/java/org/apache/lucene/store/FSDirectory.java b/lucene/core/src/java/org/apache/lucene/store/FSDirectory.java index 9b5b23a4607..d412f506dab 100644 --- a/lucene/core/src/java/org/apache/lucene/store/FSDirectory.java +++ b/lucene/core/src/java/org/apache/lucene/store/FSDirectory.java @@ -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; * * * - * Unfortunately, because of system peculiarities, there is + *

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. * + *

NOTE: 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. + * *

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 extends BaseDirectory { * The directory returned uses the {@link NativeFSLockFactory}. * The directory is created at the named location if it does not yet exist. * - *

Currently this returns {@link MMapDirectory} for most Solaris + *

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 diff --git a/lucene/core/src/java/org/apache/lucene/store/MMapDirectory.java b/lucene/core/src/java/org/apache/lucene/store/MMapDirectory.java index 30aa6b0300d..19e2034877b 100644 --- a/lucene/core/src/java/org/apache/lucene/store/MMapDirectory.java +++ b/lucene/core/src/java/org/apache/lucene/store/MMapDirectory.java @@ -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; *

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 true, if the workaround - * can be enabled (with no guarantees). + * an undocumented internal cleanup functionality. If + * {@link #UNMAP_SUPPORTED} is true, the workaround + * will be automatically enabled (with no guarantees; if you discover + * any problems, you can disable it). *

* NOTE: 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}. *

* @see Blog post about MMapDirectory */ diff --git a/lucene/core/src/java/org/apache/lucene/store/NIOFSDirectory.java b/lucene/core/src/java/org/apache/lucene/store/NIOFSDirectory.java index d47f0efab82..95f4477368a 100644 --- a/lucene/core/src/java/org/apache/lucene/store/NIOFSDirectory.java +++ b/lucene/core/src/java/org/apache/lucene/store/NIOFSDirectory.java @@ -47,8 +47,8 @@ import java.util.concurrent.Future; // javadoc * 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}. *

*/ public class NIOFSDirectory extends FSDirectory { diff --git a/lucene/core/src/java/org/apache/lucene/store/SimpleFSDirectory.java b/lucene/core/src/java/org/apache/lucene/store/SimpleFSDirectory.java index 14e6d4c15f1..69e3d31d823 100644 --- a/lucene/core/src/java/org/apache/lucene/store/SimpleFSDirectory.java +++ b/lucene/core/src/java/org/apache/lucene/store/SimpleFSDirectory.java @@ -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. + *

+ * NOTE: 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}. + *

+ */ public class SimpleFSDirectory extends FSDirectory { /** Create a new SimpleFSDirectory for the named location.