This is an automated email from the ASF dual-hosted git repository. nightowl888 pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/lucenenet.git
commit 32299570a2d9920cbfe688f324d5f917938a6ba4 Author: Shad Storhaug <[email protected]> AuthorDate: Tue Jan 25 22:27:24 2022 +0700 Lucene.Net.Store: Changed documentation on FSDirectory implementations to pertain to .NET and removed the irrelevant Java-centric information. --- src/Lucene.Net/Store/FSDirectory.cs | 32 ++++++++++++++++--------------- src/Lucene.Net/Store/MMapDirectory.cs | 15 ++++++++------- src/Lucene.Net/Store/NIOFSDirectory.cs | 32 +++++++++++++++---------------- src/Lucene.Net/Store/SimpleFSDirectory.cs | 20 +++++++++++++++---- 4 files changed, 56 insertions(+), 43 deletions(-) diff --git a/src/Lucene.Net/Store/FSDirectory.cs b/src/Lucene.Net/Store/FSDirectory.cs index 2acf2e9..debc9db 100644 --- a/src/Lucene.Net/Store/FSDirectory.cs +++ b/src/Lucene.Net/Store/FSDirectory.cs @@ -42,30 +42,23 @@ namespace Lucene.Net.Store /// <list type="bullet"> /// /// <item><description> <see cref="SimpleFSDirectory"/> is a straightforward - /// implementation using <see cref="FileStream"/>. - /// However, it has poor concurrent performance + /// implementation using <see cref="FileStream"/>, which is ideal for writing + /// without using much RAM. However, it has poor concurrent performance /// (multiple threads will bottleneck) as it /// synchronizes when multiple threads read from the /// same file.</description></item> /// /// <item><description> <see cref="NIOFSDirectory"/> - /// uses <see cref="FileStream"/>'s positional read, - /// which allows multiple threads to read from the same - /// file without synchronizing. Applications using - /// <see cref="Task{TResult}"/> should use - /// <see cref="SimpleFSDirectory"/> instead. See <see cref="NIOFSDirectory"/> documentation - /// for details.</description></item> + /// uses <see cref="FileStream"/>'s positional seeking, + /// which makes it slightly less efficient than using <see cref="SimpleFSDirectory"/> + /// during reading, with similar write performance.</description></item> /// /// <item><description> <see cref="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 runtime, or you are /// running on a 32 bit runtime but your index sizes are - /// small enough to fit into the virtual memory space. - /// <para/> - /// Applications using <see cref="Task{TResult}"/> should use - /// <see cref="SimpleFSDirectory"/> instead. See <see cref="MMapDirectory"/> - /// doc for details.</description></item> + /// small enough to fit into the virtual memory space.</description></item> /// </list> /// /// Unfortunately, because of system peculiarities, there is @@ -73,14 +66,23 @@ namespace Lucene.Net.Store /// added the <see cref="Open(string)"/> method (or one of its overloads), to allow Lucene to choose /// the best <see cref="FSDirectory"/> implementation given your /// environment, and the known limitations of each - /// implementation. For users who have no reason to prefer a + /// implementation. For users who have no reason to prefer a /// specific implementation, it's best to simply use - /// <see cref="Open(string)"/> (or one of its overloads). For all others, you should instantiate the + /// <see cref="Open(string)"/> (or one of its overloads). For all others, you should instantiate the /// desired implementation directly. /// /// <para/>The locking implementation is by default /// <see cref="NativeFSLockFactory"/>, but can be changed by /// passing in a custom <see cref="LockFactory"/> instance. + /// + /// <para/> + /// <font color="red"><b>NOTE:</b> Unlike in Java, it is not recommended to use + /// <see cref="Thread.Interrupt()"/> in .NET + /// in conjunction with an open <see cref="FSDirectory"/> because it is not guaranteed to exit atomically. + /// Any <c>lock</c> statement or <see cref="Monitor.Enter(object)"/> call can throw a + /// <see cref="ThreadInterruptedException"/>, which makes shutting down unpredictable. + /// To exit parallel tasks safely, we recommend using <see cref="Task"/>s + /// and "interrupt" them with <see cref="CancellationToken"/>s.</font> /// </summary> /// <seealso cref="Directory"/> public abstract class FSDirectory : BaseDirectory diff --git a/src/Lucene.Net/Store/MMapDirectory.cs b/src/Lucene.Net/Store/MMapDirectory.cs index 7c75c54..882b1af 100644 --- a/src/Lucene.Net/Store/MMapDirectory.cs +++ b/src/Lucene.Net/Store/MMapDirectory.cs @@ -42,13 +42,14 @@ namespace Lucene.Net.Store /// if you have problems with mmap failing because of fragmented /// address space. If you get an <see cref="OutOfMemoryException"/>, it is recommended /// to reduce the chunk size, until it works. - /// <para> - /// <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 <see cref="MMapDirectory"/> will throw a <see cref="ObjectDisposedException"/>. - /// </para> + /// <para/> + /// <font color="red"><b>NOTE:</b> Unlike in Java, it is not recommended to use + /// <see cref="System.Threading.Thread.Interrupt()"/> in .NET + /// in conjunction with an open <see cref="FSDirectory"/> because it is not guaranteed to exit atomically. + /// Any <c>lock</c> statement or <see cref="System.Threading.Monitor.Enter(object)"/> call can throw a + /// <see cref="System.Threading.ThreadInterruptedException"/>, which makes shutting down unpredictable. + /// To exit parallel tasks safely, we recommend using <see cref="System.Threading.Tasks.Task"/>s + /// and "interrupt" them with <see cref="System.Threading.CancellationToken"/>s.</font> /// </summary> public class MMapDirectory : FSDirectory { diff --git a/src/Lucene.Net/Store/NIOFSDirectory.cs b/src/Lucene.Net/Store/NIOFSDirectory.cs index d254baf..f60e6af 100644 --- a/src/Lucene.Net/Store/NIOFSDirectory.cs +++ b/src/Lucene.Net/Store/NIOFSDirectory.cs @@ -30,23 +30,21 @@ namespace Lucene.Net.Store /// <para/> /// This class only uses <see cref="FileStream"/> when reading; writing is achieved with /// <see cref="FSDirectory.FSIndexOutput"/>. - /// <para> - /// <b>NOTE</b>: <see cref="NIOFSDirectory"/> is not recommended on Windows because of a bug in - /// how FileChannel.read is implemented in Sun's JRE. Inside of the - /// implementation the position is apparently synchronized. See <a - /// href="http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=6265734";>here</a> - /// for details. - /// </para> - /// <para> - /// <font color="red"><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 <see cref="NIOFSDirectory"/> will throw a <see cref="ObjectDisposedException"/>. If - /// your application uses - /// <see cref="System.Threading.Tasks.Task"/> you should use <see cref="SimpleFSDirectory"/> in - /// favor of <see cref="NIOFSDirectory"/>.</font> - /// </para> + /// <para/> + /// <b>NOTE</b>: Since the .NET <see cref="NIOFSDirectory"/> uses additional seeking during reads, + /// it will generally be slightly less efficient than <see cref="SimpleFSDirectory"/>. + /// This class has poor concurrent read performance (multiple threads will + /// bottleneck) as it synchronizes when multiple threads + /// read from the same file. It's usually better to use + /// <see cref="MMapDirectory"/> for reading. + /// <para/> + /// <font color="red"><b>NOTE:</b> Unlike in Java, it is not recommended to use + /// <see cref="System.Threading.Thread.Interrupt()"/> in .NET + /// in conjunction with an open <see cref="FSDirectory"/> because it is not guaranteed to exit atomically. + /// Any <c>lock</c> statement or <see cref="System.Threading.Monitor.Enter(object)"/> call can throw a + /// <see cref="System.Threading.ThreadInterruptedException"/>, which makes shutting down unpredictable. + /// To exit parallel tasks safely, we recommend using <see cref="System.Threading.Tasks.Task"/>s + /// and "interrupt" them with <see cref="System.Threading.CancellationToken"/>s.</font> /// </summary> public class NIOFSDirectory : FSDirectory { diff --git a/src/Lucene.Net/Store/SimpleFSDirectory.cs b/src/Lucene.Net/Store/SimpleFSDirectory.cs index 8247314..64f8c18 100644 --- a/src/Lucene.Net/Store/SimpleFSDirectory.cs +++ b/src/Lucene.Net/Store/SimpleFSDirectory.cs @@ -24,11 +24,23 @@ namespace Lucene.Net.Store /// <summary> /// A straightforward implementation of <see cref="FSDirectory"/> - /// using <see cref="FileStream"/>. However, this class has - /// poor concurrent performance (multiple threads will + /// using <see cref="FileStream"/>. + /// <para/> + /// <see cref="FSDirectory"/> is ideal for use cases where efficient + /// writing is required without utilizing too much RAM. However, reading + /// is less efficient than when using <see cref="MMapDirectory"/>. + /// This class has poor concurrent read performance (multiple threads will /// bottleneck) as it synchronizes when multiple threads - /// read from the same file. It's usually better to use - /// <see cref="NIOFSDirectory"/> or <see cref="MMapDirectory"/> instead. + /// read from the same file. It's usually better to use + /// <see cref="MMapDirectory"/> for reading. + /// <para/> + /// <font color="red"><b>NOTE:</b> Unlike in Java, it is not recommended to use + /// <see cref="System.Threading.Thread.Interrupt()"/> in .NET + /// in conjunction with an open <see cref="FSDirectory"/> because it is not guaranteed to exit atomically. + /// Any <c>lock</c> statement or <see cref="System.Threading.Monitor.Enter(object)"/> call can throw a + /// <see cref="System.Threading.ThreadInterruptedException"/>, which makes shutting down unpredictable. + /// To exit parallel tasks safely, we recommend using <see cref="System.Threading.Tasks.Task"/>s + /// and "interrupt" them with <see cref="System.Threading.CancellationToken"/>s.</font> /// </summary> public class SimpleFSDirectory : FSDirectory {
