DOCS-379 write concern revision

Author: Sam Kleinman

source/applications/replication.txt

@@ -21,60 +21,77 @@ Write Concern
 
 When a :term:`client` sends a write operation to a database server,
 the operation will return without waiting for the operation to succeed
-or complete. To verify that the operation has completed, 
-and to check for an error, use the
-:dbcommand:`getLastError` command. You can configure
-:dbcommand:`getLastError` to wait until the journal flushes to disk or the data itself flushes to disk. For replica sets, you can
-configure :dbcommand:`getLastError` to return only after the write
-operation has propagated to more than one member of the set or to a
-majority of the set's members.
+or complete. The :dbcommand:`getLastError` command provides a way to
+check if write operations have succeeded, and provides operations to
+require various levels of write concern. [#write-concern]_ These
+levels are:
 
-Many drivers have a "safe" mode or "write concern" that automatically
-issues a :dbcommand:`getLastError` command following write
-operations to ensure that they complete. "Safe mode,"
-provides confirmation of write operations to the client.
+- without options. Confirms that the server has received the write
+  operations, and modified the :program:`mongod` instances in-memory
+  representation of the data.
 
-However, safe writes can take longer to return and are not required in
-all applications. Using the ``w: "majority"`` option for
-:dbcommand:`getLastError`, write operations to a replica set will
-return only after a write operation has replicated to a majority of
-the members of the set. At the :program:`mongo` shell, use the
-following command to ensure that writes have propagated to a majority
-of the replica set members:
+- with the ``journal`` option. Confirms that the server has committed
+  the data to the on-disk journal. This ensures that the data will be
+  durable in the event that :program:`mongod` experiences an
+  unexpected shut down.
+
+- with the ``fsync`` option. Confirms that the :program:`mongod` has
+  flushed the write operation to disk.
+
+- for replica sets, with the ``w`` option. Confirms that the write
+  operation has replicated to the specified number of
+  replica set members. You may specify a number of servers *or*
+  ``majority`` to ensure that the write propagates to a majority of
+  set members.
+
+Many drivers have a "safe" mode or "write concern" that automatically
+issues a :dbcommand:`getLastError` command following write operations
+to ensure that they complete. "Safe mode," provides confirmation of
+write operations to the client. However, safe writes can take longer
+to return and are not required in all applications. Consider the
+following operations.
 
 .. code-block:: javascript
 
    db.runCommand( { getLastError: 1, w: "majority" } )
    db.getLastErrorObj("majority")
 
-You may also specify ``w: 2`` so that the write operation replicates
-to a second member before the command returns.
+Following a write operation, these equivalent
+:dbcommand:`getLastError` operations will ensure that write operations
+return only after a write operation has replicated to a majority of
+the members of the set. You might also specify ``w: 2`` so that the
+write operation replicates to a second member before the command
+returns.
 
 .. note::
 
-   :dbcommand:`getLastError` assumes the primary replica node,
-   therefore, ``w: 2`` waits until the :term:`primary` and one other
-   member of the replica set acknowledges the write operation. The current
-   primary always counts as ``w: 1``. Using ``w: 0`` makes no sense and should
-   not be done.
+   :dbcommand:`getLastError` assumes the primary replica node, which
+   is equivalent to ``w: 1``. ``w: 2`` waits until 2 members of the
+   set, or the :term:`primary` and one other member of the replica set
+   before confirming the write operation.
 
-You can also configure a "default" :dbcommand:`getLastError` behavior on the
-replica set configuration. For instance:
+   Using ``w: 0`` is valid but does not produce useful behavior.
+
+You can also configure a "default" :dbcommand:`getLastError` behavior
+for the replica set configuration. Use the
+:data:`settings.getLastErrorDefaults` setting in the :doc:`replica set
+configuration </reference/replica-configuration>`. For instance:
 
 .. code-block:: javascript
 
    cfg = rs.conf()
    cfg.settings.getLastErrorDefaults = {w: "majority", j: true}
    rs.reconfig(cfg)
 
-When the new configuration is active, the effect of the
-:dbcommand:`getLastError` operation will wait until the write
-operation has completed on a majority of the set members before writing. By
-specifying ``j: true`` a complete commit of the operations to the 
-journal is all that :dbcommand:`getLastError` requires to return. Use the
-:data:`getLastErrorDefaults`" setting in the :ref:`replica set` configuration 
-to define the standards for a set-wide "safe mode." 
-The default setting will only affect :dbcommand:`getLastError` 
+When the new configuration is active, the :dbcommand:`getLastError`
+operation will wait for the write operation to complete on a majority
+of the set members before returning. By specifying ``j: true``,
+:dbcommand:`getLastError` waits for a complete commit of the
+operations to the journal before returning.
+
+Use the :data:`getLastErrorDefaults`" setting in the :ref:`replica
+set` configuration to define the standards for a set-wide "safe mode."
+The default setting will only affect :dbcommand:`getLastError`
 commands with *no* other arguments.
 
 .. index:: read preference
@@ -516,7 +533,7 @@ Database Commands
 
 Because some :term:`database commands <database command>` read and
 return data from the database, all of the official drivers support
-full :ref:`read preference mode semantics <replica-set-read-preference-modes>` 
+full :ref:`read preference mode semantics <replica-set-read-preference-modes>`
 for the following commands:
 
 - :dbcommand:`group`