LUCENE-2755: documentation updates, formatting and tiny mods to CMS (trunk)

git-svn-id: https://svn.apache.org/repos/asf/lucene/dev/trunk@1059905 13f79535-47bb-0310-9956-ffa450edef68

lucene/src/java/org/apache/lucene/index/ConcurrentMergeScheduler.java

@@ -142,8 +142,12 @@ public class ConcurrentMergeScheduler extends MergeScheduler {
     }
   };
 
-  /** Called whenever the running merges have changed, to
-   *  pause & unpause threads. */
+  /**
+   * Called whenever the running merges have changed, to pause & unpause
+   * threads. This method sorts the merge threads by their merge size in
+   * descending order and then pauses/unpauses threads from first to lsat --
+   * that way, smaller merges are guaranteed to run before larger ones.
+   */
   protected synchronized void updateMergeThreads() {
 
     // Only look at threads that are alive & not in the
@@ -164,6 +168,7 @@ public class ConcurrentMergeScheduler extends MergeScheduler {
       threadIdx++;
     }
 
+    // Sort the merge threads in descending order.
     CollectionUtil.mergeSort(activeMerges, compareByMergeDocCount);
     
     int pri = mergeThreadPriority;
@@ -175,12 +180,8 @@ public class ConcurrentMergeScheduler extends MergeScheduler {
         continue;
       }
 
-      final boolean doPause;
-      if (threadIdx < activeMergeCount-maxThreadCount) {
-        doPause = true;
-      } else {
-        doPause = false;
-      }
+      // pause the thread if maxThreadCount is smaller than the number of merge threads.
+      final boolean doPause = threadIdx < activeMergeCount - maxThreadCount;
 
       if (verbose()) {
         if (doPause != merge.getPause()) {
@@ -205,13 +206,26 @@ public class ConcurrentMergeScheduler extends MergeScheduler {
     }
   }
 
-  private boolean verbose() {
+  /**
+   * Returns true if verbosing is enabled. This method is usually used in
+   * conjunction with {@link #message(String)}, like that:
+   * 
+   * <pre>
+   * if (verbose()) {
+   *   message(&quot;your message&quot;);
+   * }
+   * </pre>
+   */
+  protected boolean verbose() {
     return writer != null && writer.verbose();
   }
   
-  private void message(String message) {
-    if (verbose())
-      writer.message("CMS: " + message);
+  /**
+   * Outputs the given message - this method assumes {@link #verbose()} was
+   * called and returned true.
+   */
+  protected void message(String message) {
+    writer.message("CMS: " + message);
   }
 
   private synchronized void initMergeThreadPriority() {
@@ -231,10 +245,10 @@ public class ConcurrentMergeScheduler extends MergeScheduler {
 
   /** Wait for any running merge threads to finish */
   public void sync() {
-    while(true) {
+    while (true) {
       MergeThread toSync = null;
-      synchronized(this) {
-        for(MergeThread t : mergeThreads) {
+      synchronized (this) {
+        for (MergeThread t : mergeThreads) {
           if (t.isAlive()) {
             toSync = t;
             break;
@@ -253,21 +267,20 @@ public class ConcurrentMergeScheduler extends MergeScheduler {
     }
   }
 
-  private synchronized int mergeThreadCount() {
+  /**
+   * Returns the number of merge threads that are alive. Note that this number
+   * is &le; {@link #mergeThreads} size.
+   */
+  protected synchronized int mergeThreadCount() {
     int count = 0;
-    final int numThreads = mergeThreads.size();
-    for(int i=0;i<numThreads;i++) {
-      final MergeThread t = mergeThreads.get(i);
-      if (t.isAlive() && t.getCurrentMerge() != null) {
-        count++;
-      }
+    for (MergeThread mt : mergeThreads) {
+      if (mt.isAlive()) count++;
     }
     return count;
   }
 
   @Override
-  public void merge(IndexWriter writer)
-    throws CorruptIndexException, IOException {
+  public void merge(IndexWriter writer) throws IOException {
 
     assert !Thread.holdsLock(writer);
 
@@ -291,7 +304,7 @@ public class ConcurrentMergeScheduler extends MergeScheduler {
     
     // Iterate, pulling from the IndexWriter's queue of
     // pending merges, until it's empty:
-    while(true) {
+    while (true) {
 
       // TODO: we could be careful about which merges to do in
       // the BG (eg maybe the "biggest" ones) vs FG, which
@@ -360,8 +373,7 @@ public class ConcurrentMergeScheduler extends MergeScheduler {
   }
 
   /** Does the actual merge, by calling {@link IndexWriter#merge} */
-  protected void doMerge(MergePolicy.OneMerge merge)
-    throws IOException {
+  protected void doMerge(MergePolicy.OneMerge merge) throws IOException {
     writer.merge(merge);
   }