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:51:02 UTC
[lucenenet] branch docs/4.8.0-beta00015 updated (7ee09cf -> fd1fd33)
This is an automated email from the ASF dual-hosted git repository.
nightowl888 pushed a change to branch docs/4.8.0-beta00015
in repository https://gitbox.apache.org/repos/asf/lucenenet.git.
from 7ee09cf website: Added API docs link for 4.8.0-beta00015
new f2f7a16 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.
new fd1fd33 Lucene.Net.Replicator.IndexAndTaxonomyRevision: Updated documentation.
The 2 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails. The revisions
listed as "add" were already present in the repository and have only
been added to this reference.
Summary of changes:
src/Lucene.Net.Replicator/IndexAndTaxonomyRevision.cs | 18 ++++++------------
src/Lucene.Net/Index/IndexWriter.cs | 17 +++++++++++------
src/Lucene.Net/Store/FSDirectory.cs | 17 ++++++-----------
src/Lucene.Net/Store/NIOFSDirectory.cs | 2 +-
4 files changed, 24 insertions(+), 30 deletions(-)
[lucenenet] 01/02: 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.
Posted by ni...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
nightowl888 pushed a commit to branch docs/4.8.0-beta00015
in repository https://gitbox.apache.org/repos/asf/lucenenet.git
commit f2f7a1688de65a7aa0f7f780b31a5386bc01d59d
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>
[lucenenet] 02/02: Lucene.Net.Replicator.IndexAndTaxonomyRevision: Updated documentation.
Posted by ni...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
nightowl888 pushed a commit to branch docs/4.8.0-beta00015
in repository https://gitbox.apache.org/repos/asf/lucenenet.git
commit fd1fd336100d63758cae55a8236f8a899a22fe8a
Author: Shad Storhaug <sh...@shadstorhaug.com>
AuthorDate: Tue Nov 23 09:54:30 2021 +0700
Lucene.Net.Replicator.IndexAndTaxonomyRevision: Updated documentation.
---
src/Lucene.Net.Replicator/IndexAndTaxonomyRevision.cs | 18 ++++++------------
1 file changed, 6 insertions(+), 12 deletions(-)
diff --git a/src/Lucene.Net.Replicator/IndexAndTaxonomyRevision.cs b/src/Lucene.Net.Replicator/IndexAndTaxonomyRevision.cs
index 2d845a3..b395475 100644
--- a/src/Lucene.Net.Replicator/IndexAndTaxonomyRevision.cs
+++ b/src/Lucene.Net.Replicator/IndexAndTaxonomyRevision.cs
@@ -53,19 +53,13 @@ namespace Lucene.Net.Replicator
private SnapshotDeletionPolicy sdp;
private IndexWriter writer; // LUCENENET TODO: Why does disposing this in Dispose(true) throw an excpetion?
- /// <summary>
- /// <see cref="DirectoryTaxonomyWriter(Directory, OpenMode, ITaxonomyWriterCache)"/>
- /// </summary>
- /// <exception cref="IOException"></exception>
+ /// <inheritdoc/>
public SnapshotDirectoryTaxonomyWriter(Directory directory, OpenMode openMode, ITaxonomyWriterCache cache)
: base(directory, openMode, cache)
{
}
- /// <summary>
- /// <see cref="DirectoryTaxonomyWriter(Directory, OpenMode)"/>
- /// </summary>
- /// <exception cref="IOException"></exception>
+ /// <inheritdoc/>
public SnapshotDirectoryTaxonomyWriter(Directory directory, OpenMode openMode = OpenMode.CREATE_OR_APPEND)
: base(directory, openMode)
{
@@ -107,7 +101,6 @@ namespace Lucene.Net.Replicator
/// <summary>
/// Returns a map of the revision files from the given <see cref="IndexCommit"/>s of the search and taxonomy indexes.
/// </summary>
- /// <exception cref="IOException"></exception>
public static IDictionary<string, IList<RevisionFile>> RevisionFiles(IndexCommit indexCommit, IndexCommit taxonomyCommit)
{
return new Dictionary<string, IList<RevisionFile>>{
@@ -131,7 +124,8 @@ namespace Lucene.Net.Replicator
/// <see cref="IndexCommit"/> found in the <see cref="Directory"/> managed by the given
/// writer.
/// </summary>
- /// <exception cref="IOException"></exception>
+ /// <exception cref="InvalidOperationException">If this index does not have any commits yet.</exception>
+ /// <exception cref="ArgumentException">If the <see cref="IndexWriterConfig.IndexDeletionPolicy"/> is not a <see cref="SnapshotDeletionPolicy"/>.</exception>
public IndexAndTaxonomyRevision(IndexWriter indexWriter, SnapshotDirectoryTaxonomyWriter taxonomyWriter)
{
this.indexSdp = indexWriter.Config.IndexDeletionPolicy as SnapshotDeletionPolicy;
@@ -183,7 +177,7 @@ namespace Lucene.Net.Replicator
public virtual IDictionary<string, IList<RevisionFile>> SourceFiles => sourceFiles;
- /// <exception cref="IOException"></exception>
+ /// <exception cref="IOException">An IO exception occurred.</exception>
public virtual Stream Open(string source, string fileName)
{
if (Debugging.AssertsEnabled) Debugging.Assert(source.Equals(INDEX_SOURCE, StringComparison.Ordinal) || source.Equals(TAXONOMY_SOURCE, StringComparison.Ordinal), "invalid source; expected=({0} or {1}) got={2}", INDEX_SOURCE, TAXONOMY_SOURCE, source);
@@ -191,7 +185,7 @@ namespace Lucene.Net.Replicator
return new IndexInputStream(commit.Directory.OpenInput(fileName, IOContext.READ_ONCE));
}
- /// <exception cref="IOException"></exception>
+ /// <exception cref="IOException">An IO exception occurred.</exception>
public virtual void Release()
{
try