From 9f12a2be6be76efa2d75fe92dccb29be836d6382 Mon Sep 17 00:00:00 2001
From: Michael McCandless <mikemccand@apache.org>
Date: Wed, 29 Jul 2009 18:53:25 +0000
Subject: [PATCH] LUCENE-1766: document IndexReader/Searcher's thread safety as
 well

git-svn-id: https://svn.apache.org/repos/asf/lucene/java/trunk@799011 13f79535-47bb-0310-9956-ffa450edef68
---
 src/java/org/apache/lucene/index/IndexReader.java    | 8 ++++++++
 src/java/org/apache/lucene/index/IndexWriter.java    | 8 ++++----
 src/java/org/apache/lucene/search/IndexSearcher.java | 8 ++++++++
 3 files changed, 20 insertions(+), 4 deletions(-)

diff --git a/src/java/org/apache/lucene/index/IndexReader.java b/src/java/org/apache/lucene/index/IndexReader.java
index 0c4e28db114..e3c61251527 100644
--- a/src/java/org/apache/lucene/index/IndexReader.java
+++ b/src/java/org/apache/lucene/index/IndexReader.java
@@ -67,6 +67,14 @@ import java.util.Map;
  if you want to make changes with the resulting IndexReader.
  </p>
 
+ <a name="thread-safety"></a><p><b>NOTE</b>: {@link
+ <code>IndexReader</code>} instances are completely thread
+ safe, meaning multiple threads can call any of its methods,
+ concurrently.  If your application requires external
+ synchronization, you should <b>not</b> synchronize on the
+ <code>IndexReader</code> instance; use your own
+ (non-Lucene) objects instead.
+ 
  @version $Id$
 */
 public abstract class IndexReader implements Cloneable {
diff --git a/src/java/org/apache/lucene/index/IndexWriter.java b/src/java/org/apache/lucene/index/IndexWriter.java
index e8c27960cf0..c28d74f62bc 100644
--- a/src/java/org/apache/lucene/index/IndexWriter.java
+++ b/src/java/org/apache/lucene/index/IndexWriter.java
@@ -191,10 +191,10 @@ import java.util.Map;
   <code>IndexWriter</code>} instances are completely thread
   safe, meaning multiple threads can call any of its
   methods, concurrently.  If your application requires
-  external synchronization, you should <b>not</b> use the
-  <code>IndexWriter</code> instance for synchronization as
-  this can lead to deadlock.  Use a private
-  <code>Object</code> instead. </p>
+  external synchronization, you should <b>not</b>
+  synchronize on the <code>IndexWriter</code> instance as
+  this may cause deadlock; use your own (non-Lucene) objects
+  instead. </p>
 */
 
 /*
diff --git a/src/java/org/apache/lucene/search/IndexSearcher.java b/src/java/org/apache/lucene/search/IndexSearcher.java
index 482760a4a1e..f9690c75657 100644
--- a/src/java/org/apache/lucene/search/IndexSearcher.java
+++ b/src/java/org/apache/lucene/search/IndexSearcher.java
@@ -36,6 +36,14 @@ import org.apache.lucene.store.Directory;
  * 
  * <p>Note that you can only access Hits from an IndexSearcher as long as it is
  * not yet closed, otherwise an IOException will be thrown. 
+ *
+ * <a name="thread-safety"></a><p><b>NOTE</b>: {@link
+ * <code>IndexSearcher</code>} instances are completely
+ * thread safe, meaning multiple threads can call any of its
+ * methods, concurrently.  If your application requires
+ * external synchronization, you should <b>not</b>
+ * synchronize on the <code>IndexSearcher</code> instance;
+ * use your own (non-Lucene) objects instead.</p>
  */
 public class IndexSearcher extends Searcher {
   IndexReader reader;