PR feedback

Author: paulirwin

src/Lucene.Net.Grouping/package.md

@@ -166,4 +166,4 @@ int maxDoc = s.MaxDoc;
 FixedBitSet groupHeadsBitSet = c.RetrieveGroupHeads(maxDoc);
 ```
 
-For each of the above collector types there is also a variant that works with `ValueSource` instead of of fields. Concretely this means that these variants can work with functions. These variants are slower than there term based counter parts. These implementations are located in the `Lucene.Net.Search.Grouping.Function` package, but can also be used with the `GroupingSearch` convenience utility
+For each of the above collector types there is also a variant that works with `ValueSource` instead of of fields. Concretely this means that these variants can work with functions. These variants are slower than there term based counter parts. These implementations are located in the `Lucene.Net.Search.Grouping.Function` package, but can also be used with the `GroupingSearch` convenience utility

src/Lucene.Net.TestFramework/Search/ShardSearchingTestBase.cs

@@ -193,7 +193,7 @@ internal virtual void BroadcastNodeReopen(int nodeID, long version, IndexSearche
         // MOCK: in a real env you have to hit the wire
         // (send this query to all remote nodes
         // concurrently):
-        internal virtual TopDocs SearchNode(int nodeID, long[] nodeVersions, Query q, Sort sort, int numHits, ScoreDoc searchAfter)
+        internal virtual TopDocs SearchNode(int nodeID, long[] nodeVersions, Query q, Sort sort, int numHits, ScoreDoc searchAfter, CancellationToken cancellationToken = default)
         {
             NodeState.ShardIndexSearcher s = m_nodes[nodeID].Acquire(nodeVersions);
             try
@@ -202,17 +202,17 @@ internal virtual TopDocs SearchNode(int nodeID, long[] nodeVersions, Query q, So
                 {
                     if (searchAfter != null)
                     {
-                        return s.LocalSearchAfter(searchAfter, q, numHits);
+                        return s.LocalSearchAfter(searchAfter, q, numHits, cancellationToken);
                     }
                     else
                     {
-                        return s.LocalSearch(q, numHits);
+                        return s.LocalSearch(q, numHits, cancellationToken);
                     }
                 }
                 else
                 {
                     if (Debugging.AssertsEnabled) Debugging.Assert(searchAfter is null); // not supported yet
-                    return s.LocalSearch(q, numHits, sort);
+                    return s.LocalSearch(q, numHits, sort, cancellationToken);
                 }
             }
             finally
@@ -554,7 +554,7 @@ public override TopFieldDocs Search(Query query, int numHits, Sort sort, Cancell
                         }
                         else
                         {
-                            shardHits[nodeID] = outerInstance.outerInstance.SearchNode(nodeID, nodeVersions, query, sort, numHits, null);
+                            shardHits[nodeID] = outerInstance.outerInstance.SearchNode(nodeID, nodeVersions, query, sort, numHits, null, cancellationToken);
                         }
                     }
 

src/Lucene.Net/Search/IndexSearcher.cs

@@ -76,7 +76,11 @@ namespace Lucene.Net.Search
     /// <see cref="TaskScheduler"/> passed to the constructor will be used to execute the search operations
     /// and the <see cref="CancellationToken"/> will be passed to the awaited tasks. If the <see cref="TaskScheduler"/>
     /// is <c>null</c>, the search operations will be executed synchronously, and the <see cref="CancellationToken"/>
-    /// will throw if cancellation is requested upon entry to each leaf reader.
+    /// will throw an <see cref="OperationCanceledException"/> if cancellation is requested upon entry to each leaf
+    /// reader. Each task in the multithreaded case acts as if it were a single-threaded search, and will do the same.
+    /// <para />
+    /// In both cases, this is a "best effort" attempt at cancellation, and some work may continue to proceed
+    /// after the cancellation has been requested.
     /// </remarks>
     public class IndexSearcher
     {
@@ -289,6 +293,7 @@ protected virtual Query WrapFilter(Query query, Filter? filter)
         /// <exception cref="BooleanQuery.TooManyClausesException"> If a query would exceed
         ///         <see cref="BooleanQuery.MaxClauseCount"/> clauses. </exception>
         /// <exception cref="ArgumentNullException"><paramref name="query"/> is <c>null</c>.</exception>
+        /// <exception cref="OperationCanceledException">If cancellation is requested via the <paramref name="cancellationToken"/>.</exception>
         public virtual TopDocs SearchAfter(ScoreDoc? after, Query query, int n, CancellationToken cancellationToken = default)
         {
             return Search(CreateNormalizedWeight(query), after, n, cancellationToken);
@@ -306,6 +311,7 @@ public virtual TopDocs SearchAfter(ScoreDoc? after, Query query, int n, Cancella
         /// <exception cref="BooleanQuery.TooManyClausesException"> If a query would exceed
         ///         <see cref="BooleanQuery.MaxClauseCount"/> clauses. </exception>
         /// <exception cref="ArgumentNullException"><paramref name="query"/> is <c>null</c>.</exception>
+        /// <exception cref="OperationCanceledException">If cancellation is requested via the <paramref name="cancellationToken"/>.</exception>
         public virtual TopDocs SearchAfter(ScoreDoc? after, Query query, Filter? filter, int n, CancellationToken cancellationToken = default)
         {
             return Search(CreateNormalizedWeight(WrapFilter(query, filter)), after, n, cancellationToken);
@@ -318,6 +324,7 @@ public virtual TopDocs SearchAfter(ScoreDoc? after, Query query, Filter? filter,
         /// <exception cref="BooleanQuery.TooManyClausesException"> If a query would exceed
         ///         <see cref="BooleanQuery.MaxClauseCount"/> clauses. </exception>
         /// <exception cref="ArgumentNullException"><paramref name="query"/> is <c>null</c>.</exception>
+        /// <exception cref="OperationCanceledException">If cancellation is requested via the <paramref name="cancellationToken"/>.</exception>
         public virtual TopDocs Search(Query query, int n, CancellationToken cancellationToken = default)
         {
             return Search(query, filter: null, n, cancellationToken);
@@ -329,6 +336,7 @@ public virtual TopDocs Search(Query query, int n, CancellationToken cancellation
         /// </summary>
         /// <exception cref="BooleanQuery.TooManyClausesException"> If a query would exceed
         ///         <see cref="BooleanQuery.MaxClauseCount"/> clauses. </exception>
+        /// <exception cref="OperationCanceledException">If cancellation is requested via the <paramref name="cancellationToken"/>.</exception>
         public virtual TopDocs Search(Query query, Filter? filter, int n, CancellationToken cancellationToken = default)
         {
             return Search(CreateNormalizedWeight(WrapFilter(query, filter)), after: null, n, cancellationToken);
@@ -347,6 +355,7 @@ public virtual TopDocs Search(Query query, Filter? filter, int n, CancellationTo
         ///         <see cref="BooleanQuery.MaxClauseCount"/> clauses. </exception>
         /// <exception cref="ArgumentNullException"><paramref name="query"/> or
         ///         <paramref name="results"/> is <c>null</c>.</exception>
+        /// <exception cref="OperationCanceledException">If cancellation is requested via the <paramref name="cancellationToken"/>.</exception>
         public virtual void Search(Query query, Filter? filter, ICollector results, CancellationToken cancellationToken = default)
         {
             Search(m_leafContexts, CreateNormalizedWeight(WrapFilter(query, filter)), results, cancellationToken);
@@ -361,6 +370,7 @@ public virtual void Search(Query query, Filter? filter, ICollector results, Canc
         ///         <see cref="BooleanQuery.MaxClauseCount"/> clauses. </exception>
         /// <exception cref="ArgumentNullException"><paramref name="query"/> or
         ///         <paramref name="results"/> is <c>null</c>.</exception>
+        /// <exception cref="OperationCanceledException">If cancellation is requested via the <paramref name="cancellationToken"/>.</exception>
         public virtual void Search(Query query, ICollector results, CancellationToken cancellationToken = default)
         {
             Search(m_leafContexts, CreateNormalizedWeight(query), results, cancellationToken);
@@ -380,6 +390,7 @@ public virtual void Search(Query query, ICollector results, CancellationToken ca
         ///         <see cref="BooleanQuery.MaxClauseCount"/> clauses. </exception>
         /// <exception cref="ArgumentNullException"><paramref name="query"/> or
         ///         <paramref name="sort"/> is <c>null</c>.</exception>
+        /// <exception cref="OperationCanceledException">If cancellation is requested via the <paramref name="cancellationToken"/>.</exception>
         public virtual TopFieldDocs Search(Query query, Filter? filter, int n, Sort sort, CancellationToken cancellationToken = default)
         {
             return Search(CreateNormalizedWeight(WrapFilter(query, filter)), n, sort, false, false, cancellationToken);
@@ -401,6 +412,7 @@ public virtual TopFieldDocs Search(Query query, Filter? filter, int n, Sort sort
         ///         <see cref="BooleanQuery.MaxClauseCount"/> clauses. </exception>
         /// <exception cref="ArgumentNullException"><paramref name="query"/> or
         ///         <paramref name="sort"/> is <c>null</c>.</exception>
+        /// <exception cref="OperationCanceledException">If cancellation is requested via the <paramref name="cancellationToken"/>.</exception>
         public virtual TopFieldDocs Search(Query query, Filter? filter, int n, Sort sort, bool doDocScores, bool doMaxScore, CancellationToken cancellationToken = default)
         {
             return Search(CreateNormalizedWeight(WrapFilter(query, filter)), n, sort, doDocScores, doMaxScore, cancellationToken);
@@ -419,6 +431,7 @@ public virtual TopFieldDocs Search(Query query, Filter? filter, int n, Sort sort
         ///         <seealso cref="BooleanQuery.MaxClauseCount"/> clauses. </exception>
         /// <exception cref="ArgumentNullException"><paramref name="query"/> or
         ///         <paramref name="sort"/> is <c>null</c>.</exception>
+        /// <exception cref="OperationCanceledException">If cancellation is requested via the <paramref name="cancellationToken"/>.</exception>
         public virtual TopDocs SearchAfter(ScoreDoc? after, Query query, Filter? filter, int n, Sort sort, CancellationToken cancellationToken = default)
         {
             FieldDoc? fieldDoc = GetScoreDocAsFieldDocIfNotNull(after);
@@ -449,6 +462,7 @@ public virtual TopDocs SearchAfter(ScoreDoc? after, Query query, Filter? filter,
         /// <exception cref="IOException"> if there is a low-level I/O error </exception>
         /// <exception cref="ArgumentNullException"><paramref name="query"/> or
         ///         <paramref name="sort"/> is <c>null</c>.</exception>
+        /// <exception cref="OperationCanceledException">If cancellation is requested via the <paramref name="cancellationToken"/>.</exception>
         public virtual TopFieldDocs Search(Query query, int n, Sort sort, CancellationToken cancellationToken = default)
         {
             return Search(CreateNormalizedWeight(query), n, sort, false, false, cancellationToken);
@@ -467,6 +481,7 @@ public virtual TopFieldDocs Search(Query query, int n, Sort sort, CancellationTo
         ///         <see cref="BooleanQuery.MaxClauseCount"/> clauses. </exception>
         /// <exception cref="ArgumentNullException"><paramref name="query"/> or
         ///         <paramref name="sort"/> is <c>null</c>.</exception>
+        /// <exception cref="OperationCanceledException">If cancellation is requested via the <paramref name="cancellationToken"/>.</exception>
         public virtual TopDocs SearchAfter(ScoreDoc? after, Query query, int n, Sort sort, CancellationToken cancellationToken = default)
         {
             var fieldDoc = GetScoreDocAsFieldDocIfNotNull(after);
@@ -492,6 +507,7 @@ public virtual TopDocs SearchAfter(ScoreDoc? after, Query query, int n, Sort sor
         ///         <see cref="BooleanQuery.MaxClauseCount"/> clauses. </exception>
         /// <exception cref="ArgumentNullException"><paramref name="query"/> or
         ///         <paramref name="sort"/> is <c>null</c>.</exception>
+        /// <exception cref="OperationCanceledException">If cancellation is requested via the <paramref name="cancellationToken"/>.</exception>
         public virtual TopDocs SearchAfter(ScoreDoc? after, Query query, Filter? filter, int n, Sort sort, bool doDocScores, bool doMaxScore, CancellationToken cancellationToken = default)
         {
             var fieldDoc = GetScoreDocAsFieldDocIfNotNull(after);
@@ -508,6 +524,7 @@ public virtual TopDocs SearchAfter(ScoreDoc? after, Query query, Filter? filter,
         /// <exception cref="BooleanQuery.TooManyClausesException"> If a query would exceed
         ///         <see cref="BooleanQuery.MaxClauseCount"/> clauses. </exception>
         /// <exception cref="ArgumentNullException"><paramref name="weight"/> is <c>null</c>.</exception>
+        /// <exception cref="OperationCanceledException">If cancellation is requested via the <paramref name="cancellationToken"/>.</exception>
         protected virtual TopDocs Search(Weight weight, ScoreDoc? after, int nDocs, CancellationToken cancellationToken = default)
         {
             int limit = reader.MaxDoc;
@@ -573,6 +590,7 @@ protected virtual TopDocs Search(Weight weight, ScoreDoc? after, int nDocs, Canc
         ///         <see cref="BooleanQuery.MaxClauseCount"/> clauses. </exception>
         /// <exception cref="ArgumentNullException"><paramref name="leaves"/> or
         ///         <paramref name="weight"/> is <c>null</c>.</exception>
+        /// <exception cref="OperationCanceledException">If cancellation is requested via the <paramref name="cancellationToken"/>.</exception>
         protected virtual TopDocs Search(IList<AtomicReaderContext> leaves, Weight weight, ScoreDoc? after, int nDocs, CancellationToken cancellationToken = default)
         {
             // LUCENENET: Added guard clause
@@ -605,6 +623,7 @@ protected virtual TopDocs Search(IList<AtomicReaderContext> leaves, Weight weigh
         ///         <see cref="BooleanQuery.MaxClauseCount"/> clauses. </exception>
         /// <exception cref="ArgumentNullException"><paramref name="weight"/> or
         ///         <paramref name="sort"/> is <c>null</c>.</exception>
+        /// <exception cref="OperationCanceledException">If cancellation is requested via the <paramref name="cancellationToken"/>.</exception>
         protected virtual TopFieldDocs Search(Weight weight, int nDocs, Sort sort, bool doDocScores, bool doMaxScore, CancellationToken cancellationToken = default)
         {
             return Search(weight, after: null, nDocs, sort, true, doDocScores, doMaxScore, cancellationToken);
@@ -617,6 +636,7 @@ protected virtual TopFieldDocs Search(Weight weight, int nDocs, Sort sort, bool
         /// </summary>
         /// <exception cref="ArgumentNullException"><paramref name="weight"/> or
         ///         <paramref name="sort"/> is <c>null</c>.</exception>
+        /// <exception cref="OperationCanceledException">If cancellation is requested via the <paramref name="cancellationToken"/>.</exception>
         protected virtual TopFieldDocs Search(Weight weight, FieldDoc? after, int nDocs, Sort sort, bool fillFields, bool doDocScores, bool doMaxScore, CancellationToken cancellationToken = default)
         {
             if (sort is null)
@@ -676,6 +696,7 @@ protected virtual TopFieldDocs Search(Weight weight, FieldDoc? after, int nDocs,
         /// </summary>
         /// <exception cref="ArgumentNullException"><paramref name="leaves"/> or
         ///          <paramref name="weight"/> is <c>null</c>.</exception>
+        /// <exception cref="OperationCanceledException">If cancellation is requested via the <paramref name="cancellationToken"/>.</exception>
         protected virtual TopFieldDocs Search(IList<AtomicReaderContext> leaves, Weight weight, FieldDoc? after, int nDocs, Sort sort, bool fillFields, bool doDocScores, bool doMaxScore, CancellationToken cancellationToken = default)
         {
             // LUCENENET: Added guard clause
@@ -715,6 +736,7 @@ protected virtual TopFieldDocs Search(IList<AtomicReaderContext> leaves, Weight
         ///         <see cref="BooleanQuery.MaxClauseCount"/> clauses. </exception>
         /// <exception cref="ArgumentNullException"><paramref name="leaves"/>, <paramref name="weight"/>,
         ///         or <paramref name="collector"/> is <c>null</c>.</exception>
+        /// <exception cref="OperationCanceledException">If cancellation is requested via the <paramref name="cancellationToken"/>.</exception>
         protected virtual void Search(IList<AtomicReaderContext> leaves, Weight weight, ICollector collector, CancellationToken cancellationToken = default)
         {
             // LUCENENET: Added guard clauses
@@ -756,8 +778,6 @@ protected virtual void Search(IList<AtomicReaderContext> leaves, Weight weight,
                     }
                 }
             }
-
-            cancellationToken.ThrowIfCancellationRequested(); // LUCENENET specific - cancellation support
         }
 
         /// <summary>

src/Lucene.Net/Search/package.md

@@ -35,7 +35,7 @@ Code to search indices.
 
  Lucene offers a wide variety of <xref:Lucene.Net.Search.Query> implementations, most of which are in this package, its subpackages ([Lucene.Net.Spans](xref:Lucene.Net.Search.Spans), [Lucene.Net.Payloads](xref:Lucene.Net.Search.Payloads)), or the [Lucene.Net.Queries module](../queries/Lucene.Net.Queries.html). These implementations can be combined in a wide variety of ways to provide complex querying capabilities along with information about where matches took place in the document collection. The [Query Classes](#query-classes) section below highlights some of the more important Query classes. For details on implementing your own Query class, see [Custom Queries -- Expert Level](#custom-queries--expert-level) below.
 
- To perform a search, applications usually call [Search(Query, int)](xref:Lucene.Net.Search.IndexSearcher#Lucene_Net_Search_IndexSearcher_Search_Lucene_Net_Search_Query_System_Int32_) or [Search(Query, Filter, int)](xref:Lucene.Net.Search.IndexSearcher#Lucene_Net_Search_IndexSearcher_Search_Lucene_Net_Search_Query_Lucene_Net_Search_Filter_System_Int32_).
+ To perform a search, applications usually call [Search(Query, int, CancellationToken)](xref:Lucene.Net.Search.IndexSearcher#Lucene_Net_Search_IndexSearcher_Search_Lucene_Net_Search_Query_System_Int32_System_Threading_CancellationToken_) or [Search(Query, Filter, int, CancellationToken)](xref:Lucene.Net.Search.IndexSearcher#Lucene_Net_Search_IndexSearcher_Search_Lucene_Net_Search_Query_Lucene_Net_Search_Filter_System_Int32_System_Threading_CancellationToken_).
 
  Once a Query has been created and submitted to the [IndexSearcher](xref:Lucene.Net.Search.IndexSearcher), the scoring process begins. After some infrastructure setup, control finally passes to the [Weight](xref:Lucene.Net.Search.Weight) implementation and its [Scorer](xref:Lucene.Net.Search.Scorer) or [BulkScorer](xref:Lucene.Net.Search.BulkScorer) instances. See the [Algorithm](#appendix-search-algorithm) section for more notes on the process.
 

src/Lucene.Net/overview.md

@@ -118,7 +118,7 @@ and add documents to it with [AddDocument()](xref:Lucene.Net.Index.IndexWriter#L
 to build a query from a string; and
 
 4.  Create an [IndexSearcher](xref:Lucene.Net.Search.IndexSearcher)
-and pass the query to its [Search()](xref:Lucene.Net.Search.IndexSearcher#Lucene_Net_Search_IndexSearcher_Search_Lucene_Net_Search_Query_System_Int32_)
+and pass the query to its [Search()](xref:Lucene.Net.Search.IndexSearcher#Lucene_Net_Search_IndexSearcher_Search_Lucene_Net_Search_Query_System_Int32_System_Threading_CancellationToken_)
 method.
 
 Some simple examples of code which does this are: