Return-Path: X-Original-To: apmail-lucene-commits-archive@www.apache.org Delivered-To: apmail-lucene-commits-archive@www.apache.org Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by minotaur.apache.org (Postfix) with SMTP id 2456A174F3 for ; Thu, 5 Feb 2015 10:32:26 +0000 (UTC) Received: (qmail 61783 invoked by uid 500); 5 Feb 2015 10:32:26 -0000 Mailing-List: contact commits-help@lucene.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: dev@lucene.apache.org Delivered-To: mailing list commits@lucene.apache.org Received: (qmail 61769 invoked by uid 99); 5 Feb 2015 10:32:26 -0000 Received: from eris.apache.org (HELO hades.apache.org) (140.211.11.105) by apache.org (qpsmtpd/0.29) with ESMTP; Thu, 05 Feb 2015 10:32:25 +0000 Received: from hades.apache.org (localhost [127.0.0.1]) by hades.apache.org (ASF Mail Server at hades.apache.org) with ESMTP id D4A93AC006D; Thu, 5 Feb 2015 10:32:25 +0000 (UTC) Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Subject: svn commit: r1657521 - in /lucene/dev/branches/branch_5x: ./ lucene/ lucene/core/ lucene/core/src/java/org/apache/lucene/store/ Date: Thu, 05 Feb 2015 10:32:25 -0000 To: commits@lucene.apache.org From: uschindler@apache.org X-Mailer: svnmailer-1.0.9 Message-Id: <20150205103225.D4A93AC006D@hades.apache.org> Author: uschindler Date: Thu Feb 5 10:32:25 2015 New Revision: 1657521 URL: http://svn.apache.org/r1657521 Log: Merged revision(s) 1657519 from lucene/dev/trunk: Improve documentation a bit. Modified: lucene/dev/branches/branch_5x/ (props changed) lucene/dev/branches/branch_5x/lucene/ (props changed) lucene/dev/branches/branch_5x/lucene/core/ (props changed) lucene/dev/branches/branch_5x/lucene/core/src/java/org/apache/lucene/store/FSDirectory.java lucene/dev/branches/branch_5x/lucene/core/src/java/org/apache/lucene/store/MMapDirectory.java lucene/dev/branches/branch_5x/lucene/core/src/java/org/apache/lucene/store/NIOFSDirectory.java lucene/dev/branches/branch_5x/lucene/core/src/java/org/apache/lucene/store/SimpleFSDirectory.java Modified: lucene/dev/branches/branch_5x/lucene/core/src/java/org/apache/lucene/store/FSDirectory.java URL: http://svn.apache.org/viewvc/lucene/dev/branches/branch_5x/lucene/core/src/java/org/apache/lucene/store/FSDirectory.java?rev=1657521&r1=1657520&r2=1657521&view=diff ============================================================================== --- lucene/dev/branches/branch_5x/lucene/core/src/java/org/apache/lucene/store/FSDirectory.java (original) +++ lucene/dev/branches/branch_5x/lucene/core/src/java/org/apache/lucene/store/FSDirectory.java Thu Feb 5 10:32:25 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; * * * - * 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 extend * 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 Modified: lucene/dev/branches/branch_5x/lucene/core/src/java/org/apache/lucene/store/MMapDirectory.java URL: http://svn.apache.org/viewvc/lucene/dev/branches/branch_5x/lucene/core/src/java/org/apache/lucene/store/MMapDirectory.java?rev=1657521&r1=1657520&r2=1657521&view=diff ============================================================================== --- lucene/dev/branches/branch_5x/lucene/core/src/java/org/apache/lucene/store/MMapDirectory.java (original) +++ lucene/dev/branches/branch_5x/lucene/core/src/java/org/apache/lucene/store/MMapDirectory.java Thu Feb 5 10:32:25 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; *

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 */ Modified: lucene/dev/branches/branch_5x/lucene/core/src/java/org/apache/lucene/store/NIOFSDirectory.java URL: http://svn.apache.org/viewvc/lucene/dev/branches/branch_5x/lucene/core/src/java/org/apache/lucene/store/NIOFSDirectory.java?rev=1657521&r1=1657520&r2=1657521&view=diff ============================================================================== --- lucene/dev/branches/branch_5x/lucene/core/src/java/org/apache/lucene/store/NIOFSDirectory.java (original) +++ lucene/dev/branches/branch_5x/lucene/core/src/java/org/apache/lucene/store/NIOFSDirectory.java Thu Feb 5 10:32:25 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}. *

*/ public class NIOFSDirectory extends FSDirectory { Modified: lucene/dev/branches/branch_5x/lucene/core/src/java/org/apache/lucene/store/SimpleFSDirectory.java URL: http://svn.apache.org/viewvc/lucene/dev/branches/branch_5x/lucene/core/src/java/org/apache/lucene/store/SimpleFSDirectory.java?rev=1657521&r1=1657520&r2=1657521&view=diff ============================================================================== --- lucene/dev/branches/branch_5x/lucene/core/src/java/org/apache/lucene/store/SimpleFSDirectory.java (original) +++ lucene/dev/branches/branch_5x/lucene/core/src/java/org/apache/lucene/store/SimpleFSDirectory.java Thu Feb 5 10:32:25 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. + *

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