Moderate updates to read prefs doc

source/applications/replication.txt

@@ -97,7 +97,7 @@ Read Preference
 ---------------
 
 Read preference describes how MongoDB clients route read operations to
-:term:`secondary` members of a :term:`replica set`.
+members of a :term:`replica set`.
 
 .. index:: read preference; background
 .. _replica-set-read-preference-background:
@@ -109,8 +109,8 @@ By default, an application directs its read operations to the :term:`primary`
 member in a :term:`replica set`. Reading from the primary guarantees that
 read operations reflect the latest version of a document. However,
 for an application that does not require fully up-to-date data, you
-can improve read throughput by distributing some or all reads to
-secondary members of the replica set.
+can improve read throughput, or reduce latency, by distributing some or all
+reads to secondary members of the replica set.
 
 The following are use cases where you might use secondary reads:
 
@@ -142,7 +142,7 @@ configuration, see the appropriate :ref:`driver` API documentation.
    preferences dictate if the application receives stale or
    current data from MongoDB. Use appropriate :term:`write concern`
    policies to ensure proper data
-   replication and constancy.
+   replication and consistency.
 
    If read operations account for a large percentage of your
    application's traffic, distributing reads to secondary members can
@@ -170,9 +170,9 @@ read preference modes:
 - :readmode:`secondaryPreferred`
 - :readmode:`nearest`
 
-You can specify a read preference mode on a per-collection or
-per-operation basis. The syntax for specifying the read preference
-mode is :api:`specific to the driver and to the idioms of the host
+You can specify a read preference mode on connection objects, database object,
+collection object, or per-operation. The syntax for specifying the read
+preference mode is :api:`specific to the driver and to the idioms of the host
 language <>`.
 
 Read preference modes are also available to clients connecting to a
@@ -440,7 +440,7 @@ As a result, MongoDB drivers and :program:`mongos`:
 
   After this error, the driver selects a new member using the
   specified read preference mode. In the absence of a specified read
-  preference, the driver uses :readmode:`PRIMARY`.
+  preference, the driver uses :readmode:`primary`.
 
 - After detecting a failover situation, [#fn-failover]_ the driver
   attempts to refresh the state of the replica set as quickly as
@@ -496,17 +496,19 @@ lifetime.
 Member Selection
 ````````````````
 
-Both clients, by way of their drivers, and :program:`mongos` instances for
-sharded clusters send periodic "ping," messages to all member of the
-replica set to determine latency from the application to each
-:program:`mongod` instance.
+Clients, by way of their drivers, and :program:`mongos` instances for
+sharded clusters periodically call :dbcommand:`isMaster` on all members of the
+replica set to update their view of the set's state, and to determine latency
+from the application to each :program:`mongod` instance.
 
 For any operation that targets a member *other* than the
 :term:`primary`, the driver:
 
 #. Assembles a list of suitable members, taking into account member type
    (i.e. secondary, primary, or all members.)
 
+#. Excludes members not matching the tag sets, if specified.
+
 #. Determines which suitable member is the closest to the
    client in absolute terms.
 
@@ -523,7 +525,9 @@ for more information.
 
 .. [#acceptable-secondary-latency] Applications can configure the
    threshold used in this stage. The default "acceptable latency" is
-   15 milliseconds. For :program:`mongos` you can use the
+   15 milliseconds, which you can override in the drivers with the
+   `secondaryAcceptableLatencyMS` option.
+   For :program:`mongos` you can use the
    :option:`--localThreshold <mongos --localThreshold>` or
    :setting:`localThreshold` runtime options to set this value.
 
@@ -594,6 +598,9 @@ for the following commands:
    otherwise these operations must run on the :term:`primary`
    members.
 
+:program:`mongos` currently does not route commands using read preferences; all
+commands are sent to shards' primaries. See :issue:`SERVER-7423`.
+
 Uses for non-Primary Read Preferences
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -614,6 +621,16 @@ using non-:readmode:`primary` read preference modes:
   direct connection to a :ref:`hidden member
   <replica-set-hidden-members>` of the set.
 
+.. warning::
+
+  Although it is tempting to use :readmode:`secondaryPreferred` to distribute
+  load, if your primary cannot accept your full read load, then
+  using :readmode:`secondaryPreferred` is dangerous: if all secondaries
+  become unavailable, but you have enough arbiters to prevent the primary from
+  stepping down, then this mode will redirect traffic to the primary. For this
+  reason, use :readmode:`secondary` to distribute load,
+  not :readmode:`secondaryPreferred`.
+
 - Providing local reads for geographically distributed applications.
 
   If you have application servers in multiple data centers, you may
@@ -622,6 +639,13 @@ using non-:readmode:`primary` read preference modes:
   read preference or the :readmode:`nearest` to avoid network
   latency.
 
+- Maintaining availability during a failover.
+
+  Use :readmode:`primaryPreferred` if you want your application to do
+  consistent reads from the primary under normal circumstances, but to allow
+  stale reads from secondaries in an emergency. This provides a "read-only mode"
+  for your application during a failover.
+
 Using read modes other than :readmode:`primary` and
 :readmode:`primaryPreferred` to provide extra capacity is not in and
 of itself justification for non-:readmode:`primary` in many