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 a7725fc9b2890d6e41ee83c6a728aec2bc8bc302 Author: Shad Storhaug <[email protected]> AuthorDate: Tue Nov 23 11:16:45 2021 +0700 docs: Changed info about Thread.Interrupt() to indicate it is not supported in Lucene.NET due to the high likelihood it could break a Commit() or cause a deadlock. Closes #526. --- src/Lucene.Net/Index/IndexWriter.cs | 17 +++++++++++------ src/Lucene.Net/Store/FSDirectory.cs | 17 ++++++----------- src/Lucene.Net/Store/NIOFSDirectory.cs | 2 +- 3 files changed, 18 insertions(+), 18 deletions(-) diff --git a/src/Lucene.Net/Index/IndexWriter.cs b/src/Lucene.Net/Index/IndexWriter.cs index ff205c9..f0f5461 100644 --- a/src/Lucene.Net/Index/IndexWriter.cs +++ b/src/Lucene.Net/Index/IndexWriter.cs @@ -155,12 +155,17 @@ namespace Lucene.Net.Index /// this may cause deadlock; use your own (non-Lucene) objects /// instead. </para> /// - /// <para><b>NOTE</b>: If you call - /// <see cref="Thread.Interrupt()"/> on a thread that's within - /// <see cref="IndexWriter"/>, <see cref="IndexWriter"/> will try to catch this (eg, if - /// it's in a <see cref="Monitor.Wait(object)"/> or <see cref="Thread.Sleep(int)"/>), and will then throw - /// the unchecked exception <see cref="Util.ThreadInterruptedException"/> - /// and <b>clear</b> the interrupt status on the thread.</para> + /// <para><b>NOTE</b>: + /// Do not use <see cref="Thread.Interrupt()"/> on a thread that's within + /// <see cref="IndexWriter"/>, as .NET will throw <see cref="ThreadInterruptedException"/> on any + /// wait, sleep, or join including any lock statement with contention on it. + /// As a result, it is not practical to try to support <see cref="Thread.Interrupt()"/> due to the + /// chance <see cref="ThreadInterruptedException"/> could potentially be thrown in the middle of a + /// <see cref="Commit()"/> or somewhere in the application that will cause a deadlock.</para> + /// <para> + /// We recommend using another shutdown mechanism to safely cancel a parallel operation. + /// See: <a href="https://github.com/apache/lucenenet/issues/526";>https://github.com/apache/lucenenet/issues/526</a>. + /// </para> /// </remarks> /* diff --git a/src/Lucene.Net/Store/FSDirectory.cs b/src/Lucene.Net/Store/FSDirectory.cs index b8bd548..2acf2e9 100644 --- a/src/Lucene.Net/Store/FSDirectory.cs +++ b/src/Lucene.Net/Store/FSDirectory.cs @@ -48,16 +48,12 @@ namespace Lucene.Net.Store /// synchronizes when multiple threads read from the /// same file.</description></item> /// - /// <item><description> <see cref="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 - /// href="http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=6265734";>Sun - /// JRE bug</a> this is a poor choice for Windows, but - /// on all other platforms this is the preferred - /// choice. Applications using <see cref="Thread.Interrupt()"/> or + /// <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"/> java doc + /// <see cref="SimpleFSDirectory"/> instead. See <see cref="NIOFSDirectory"/> documentation /// for details.</description></item> /// /// <item><description> <see cref="MMapDirectory"/> uses memory-mapped IO when @@ -67,8 +63,7 @@ namespace Lucene.Net.Store /// 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="Thread.Interrupt()"/> or - /// <see cref="Task{TResult}"/> should use + /// Applications using <see cref="Task{TResult}"/> should use /// <see cref="SimpleFSDirectory"/> instead. See <see cref="MMapDirectory"/> /// doc for details.</description></item> /// </list> diff --git a/src/Lucene.Net/Store/NIOFSDirectory.cs b/src/Lucene.Net/Store/NIOFSDirectory.cs index e99b11b..d254baf 100644 --- a/src/Lucene.Net/Store/NIOFSDirectory.cs +++ b/src/Lucene.Net/Store/NIOFSDirectory.cs @@ -43,7 +43,7 @@ namespace Lucene.Net.Store /// 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 either <see cref="System.Threading.Thread.Interrupt()"/> or + /// your application uses /// <see cref="System.Threading.Tasks.Task"/> you should use <see cref="SimpleFSDirectory"/> in /// favor of <see cref="NIOFSDirectory"/>.</font> /// </para>
