From 5cc630efaa87d6a9e5ca2ab4f154bf449f04006c Mon Sep 17 00:00:00 2001 From: kay Date: Mon, 25 Aug 2014 19:27:34 -0400 Subject: [PATCH] DOCS-3666 tweak wording of isolated --- .../ref-toc-operator-update-isolation.yaml | 2 +- .../reference/method/db.collection.remove.txt | 24 ++++++++------ source/reference/operator/update/isolated.txt | 31 +++++++++++-------- 3 files changed, 34 insertions(+), 23 deletions(-) diff --git a/source/includes/ref-toc-operator-update-isolation.yaml b/source/includes/ref-toc-operator-update-isolation.yaml index 0faa9acab8c..6b9865feb38 100644 --- a/source/includes/ref-toc-operator-update-isolation.yaml +++ b/source/includes/ref-toc-operator-update-isolation.yaml @@ -1,4 +1,4 @@ name: ":update:`$isolated`" file: /reference/operator/update/isolated -description: "Modifies behavior of multi-updates to increase the isolation of the operation." +description: "Modifies the behavior of a write operation to increase the isolation of the operation." ... diff --git a/source/reference/method/db.collection.remove.txt b/source/reference/method/db.collection.remove.txt index 6b0b6809131..6f2b7bf9c25 100644 --- a/source/reference/method/db.collection.remove.txt +++ b/source/reference/method/db.collection.remove.txt @@ -70,6 +70,16 @@ limit the operation to removing a single document. To delete a single document sorted by a specified order, use the :ref:`findAndModify() ` method. +When removing multiple documents, the remove operation may interleave +with other read and/or write operations to the collection. For +*unsharded* collections, you can override this behavior with the +:update:`$isolated` operator, which "isolates" the remove operation and +disallows yielding during the operation. This ensures that no client +can see the affected documents until they are all processed or an error +stops the remove operation. + +See :ref:`isolate-remove-operations` for an example. + Capped Collections ~~~~~~~~~~~~~~~~~~ @@ -154,16 +164,12 @@ The following operation removes the first document from the collection db.products.remove( { qty: { $gt: 20 } }, true ) -Isolate Removal Operations -~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. _isolate-remove-operations: + +Isolate Remove Operations +~~~~~~~~~~~~~~~~~~~~~~~~~ -If the ```` argument to the :method:`~db.collection.remove()` -method matches multiple documents in the collection, the delete -operation may interleave with other write operations to that collection. -For an unsharded collection, you have the option to override this -behavior with the :update:`$isolated` isolation operator, effectively -isolating the delete operation and blocking other write operations -during the delete. To isolate the query, include ``$isolated: 1`` in the +To isolate the query, include ``$isolated: 1`` in the ```` parameter as in the following examples: .. code-block:: javascript diff --git a/source/reference/operator/update/isolated.txt b/source/reference/operator/update/isolated.txt index cbd6892b9ca..eab78241810 100644 --- a/source/reference/operator/update/isolated.txt +++ b/source/reference/operator/update/isolated.txt @@ -6,12 +6,14 @@ $isolated .. update:: $isolated - The :update:`$isolated` isolation operator **isolates** a write - operation that affects multiple documents so that once the first - document is changed the operation will not yield, to allow reads - or writes, until all documents are written. This significantly affects - the concurrency of the system as it holds the write lock much - longer than normal. + Prevents a write operation that affects multiple documents from + yielding to other reads or writes once the first document is + written. By using the :update:`$isolated` option, you can ensure + that no client sees the changes until the operation completes or + errors out. + + This behavior can significantly affect the concurrency of the system + as the operation holds the write lock much longer than normal. .. note:: @@ -22,20 +24,23 @@ $isolated .. code-block:: javascript - db.foo.update( { field1 : 1 , $isolated : 1 }, { $inc : { field2 : 1 } } , { multi: true } ) + db.foo.update( + { status : "A" , $isolated : 1 }, + { $inc : { count : 1 } }, + { multi: true } + ) - Without the :update:`$isolated` operator, multi-updates will allow - other operations to interleave with these updates. By specifying :update:`$isolated` you - can guarantee isolation for the entire multi-update so no other clients sees the - changes until the operation is finished (or errors -- see the note above). + Without the :update:`$isolated` operator, the ``multi``-update + operation will allow other operations to interleave with its update + of the matched documents. .. warning:: :update:`$isolated` does not work with :term:`sharded clusters `. - .. seealso:: See :method:`db.collection.update()` for more information about the - :method:`db.collection.update()` method. + .. seealso:: + :method:`db.collection.update()` and :method:`db.collection.remove()` .. update:: $atomic