You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@lucenenet.apache.org by ni...@apache.org on 2022/01/25 21:32:28 UTC
[lucenenet] 02/02: Lucene.Net.Store: Changed documentation on FSDirectory implementations to pertain to .NET and removed the irrelevant Java-centric information.
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 <sh...@shadstorhaug.com>
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
{