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 2021/11/23 04:41:54 UTC
[lucenenet] 03/03: 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.
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 <sh...@shadstorhaug.com>
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>