From 54d7c4244b13bbd6a2299a4b4055c703038a27d7 Mon Sep 17 00:00:00 2001
From: Bob Grabar <bob.grabar@10gen.com>
Date: Tue, 3 Sep 2013 12:07:34 -0400
Subject: [PATCH] DOCS-1190 asynchronous chunk deletion

---
 source/reference/command/moveChunk-field.yaml | 14 +++++++++++
 source/reference/command/moveChunk.txt        |  6 +++--
 source/release-notes/2.4.txt                  | 23 +++++++++++++++++++
 3 files changed, 41 insertions(+), 2 deletions(-)

diff --git a/source/reference/command/moveChunk-field.yaml b/source/reference/command/moveChunk-field.yaml
index d0cee76b974..b43ca4d368d 100644
--- a/source/reference/command/moveChunk-field.yaml
+++ b/source/reference/command/moveChunk-field.yaml
@@ -68,4 +68,18 @@ description: |
   for replication to :term:`secondaries <secondary>` when it copies
   and deletes data during chunk migrations. For details, see
   :ref:`sharded-cluster-config-secondary-throttle`.
+---
+object:
+  name: moveChunk
+  type: command
+field:
+  optional: true
+  type: field
+name: _waitForDelete
+type: Boolean
+position: 6
+description: |
+  Internal option for test purposess. The default is ``false``. If set
+  to ``true``, the delete phase of a :dbcommand:`moveChunk` operation
+  blocks.
 ...
diff --git a/source/reference/command/moveChunk.txt b/source/reference/command/moveChunk.txt
index 7dd7e2825c1..28f3121bb9e 100644
--- a/source/reference/command/moveChunk.txt
+++ b/source/reference/command/moveChunk.txt
@@ -19,7 +19,8 @@ Definition
       db.runCommand( { moveChunk : <namespace> ,
                        find : <query> ,
                        to : <string>,
-                       _secondaryThrottle : <boolean> } )
+                       _secondaryThrottle : <Boolean>,
+                       _waitForDelete : <Boolean> } )
 
    Alternately:
 
@@ -28,7 +29,8 @@ Definition
       db.runCommand( { moveChunk : <namespace> ,
                        bounds : <array> ,
                        to : <string>,
-                       _secondaryThrottle : <boolean> } )
+                       _secondaryThrottle : <Boolean>,
+                       _waitForDelete : <Boolean> } )
 
    The :dbcommand:`moveChunk` command has the following fields:
 
diff --git a/source/release-notes/2.4.txt b/source/release-notes/2.4.txt
index 02d62c32c21..c941cfa0a2e 100644
--- a/source/release-notes/2.4.txt
+++ b/source/release-notes/2.4.txt
@@ -248,6 +248,29 @@ potential speed of a chunk migration, but increases reliability and
 ensures that a large number of chunk migrations *cannot* affect the
 availability of a sharded cluster.
 
+Chunk Migration Queuing Improvements
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The MongoDB :term:`balancer` increases performance for moving multiple
+chunks off an overloaded shard, decreasing the time it takes to reduce
+the shard's read and write load. A migration no longer waits for its
+cleanup phase before completing, which means a second chunk migration
+can begin while the first migration's cleanup is still in progress. The
+cleanup phase is the deletion phase, where the balancer deletes the
+documents in the original location once they are fully migrated to the
+new location.
+
+This change in queuing behavior helps when the cluster is heavily imbalanced,
+allowing shards to unload chunks more quickly. This is the case, for
+example, when doing initial data loads without pre-splitting and when
+adding new shards. The improvement also means that migration scripts
+that use the :dbcommand:`moveChunk` command will no longer wait
+for chunk cleanup and may proceed more quickly.
+
+The cleanup might persist longer in some cases. Also, data from multiple
+migrations can be orphaned during a crash of a replica-set primary if
+multiple cleanups are queued but not yet completed.
+
 BSON Document Validation Enabled by Default for ``mongod`` and ``mongorestore``
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~