minor: documentation updates

README.md

@@ -25,18 +25,18 @@ For the reference manual, use the links in the upper-left and upper-right corner
 
 This documentation has other articles of interest, including:
 
-1. [A tutorial](docs/TUTORIAL.md).
-2. [Replica Sets in Ruby](docs/REPLICA_SETS.md).
-3. [Write Concern in Ruby](docs/WRITE_CONCERN.md).
-4. [Tailable Cursors in Ruby](docs/TAILABLE_CURSORS.md).
-5. [Read Preference in Ruby](docs/READ_PREFERENCE.md).
-6. [GridFS in Ruby](docs/GridFS.md).
-7. [Frequently Asked Questions](docs/FAQ.md).
-8. [History](docs/HISTORY.md).
-9. [Release plan](docs/RELEASES.md).
-10. [Credits](docs/CREDITS.md).
-
-Here's a quick code sample. Again, see the [MongoDB Ruby Tutorial](docs/TUTORIAL.md)
+1. [A tutorial](file.TUTORIAL.html).
+2. [Replica Sets in Ruby](file.REPLICA_SETS.html).
+3. [Write Concern in Ruby](file.WRITE_CONCERN.html).
+4. [Tailable Cursors in Ruby](file.TAILABLE_CURSORS.html).
+5. [Read Preference in Ruby](file.READ_PREFERENCE.html).
+6. [GridFS in Ruby](file.GRID_FS.html).
+7. [Frequently Asked Questions](file.FAQ.html).
+8. [History](file.HISTORY.html).
+9. [Release plan](file.RELEASES.html).
+10. [Credits](file.CREDITS.html).
+
+Here's a quick code sample. Again, see the [MongoDB Ruby Tutorial](file.TUTORIAL.html)
 for much more:
 
     require 'rubygems'
@@ -104,7 +104,7 @@ That's all there is to it!
 
 # Examples
 
-For extensive examples, see the [MongoDB Ruby Tutorial](http://api.mongodb.org/ruby/current/file.TUTORIAL.html).
+For extensive examples, see the [MongoDB Ruby Tutorial](file.TUTORIAL.html).
 
 Bundled with the driver are many examples, located in the "docs/examples" subdirectory. Samples include using
 the driver and using the GridFS class GridStore. MongoDB must be running for

docs/HISTORY.md

@@ -1,5 +1,15 @@
 # MongoDB Ruby Driver History
 
+### 1.7.0
+2012-08-20
+
+* Added testing and full support for MongoDB 2.1 & 2.2
+* Added Aggregation Framework helper method
+* Added support for Mongos high availability
+* Modified and added new read preferences (details in documentation)
+* Added support for data center awareness (tag_sets)
+* Fixed bug which attempted to close cursors on wrong replica set member
+
 ### 1.6.4
 2012-06-06
 

docs/READ_PREFERENCE.md

@@ -1,15 +1,22 @@
 # Read Preference in Ruby
 
-## Setting the read preference
+## About Read Preference
 
-You can using the `:read` option to specify a query's read preference. There are for now two possible options:
+Read preferences determine the candidate replica set members to which a query or command can be sent. They consist of a *mode* specified as a symbol and an array of hashes known as *tag_sets*.
 
-    @collection.find({:doc => 'foo'}, :read => :primary)
-    @collection.find({:doc => 'foo'}, :read => :secondary)
+Read preference mode is configured by providing the read option to a connection, database, collection, or cursor.
 
-In the first case, the query will be directed to the primary node in a replica set. In the second, the query will be sent
-to a secondary node. The driver will attempt to choose a secondary node that's nearby, as determined by ping time. If more
-than one secondary node is closeby (e.g, responds to pings within 10ms), then a random node within this subset will be chosen.
+    @collection.find({:doc => 'foo'}, :read => :primary)    # read from primary only
+    @collection.find({:doc => 'foo'}, :read => :secondary)  # read from secondaries only
+
+Used in conjunction with tag_sets:
+
+    @collection.find({:name => 'foo'}, :read => :secondary_preferred, :tag_sets => [{:continent => 'USA'}])
+
+*Please Note*: Behavior of some read preference modes have changed in version 1.7.0:
+
+* `:secondary_preferred` mode is now used to prefer reads from secondary members (before this was the behavior of `:secondary`).
+* `:secondary_only` mode (which only allowed reads from secondaries) is now called `:secondary`.
 
 ## Read preference inheritance
 
@@ -33,7 +40,60 @@ You can examine the read preference on any object by calling its `read_preferenc
     @db.read_preference
     @collection.read_preference
 
-## Future work
+## Modes
+
+You can using the `:read` option to specify a query's read preference mode. There are five possible options.
+
+### :primary
+
+With primary, all read operations from the client will use the primary member only. This is the default read preference.
+
+If the primary is unavailable, all operations with this preference produce an error or throw an exception. Primary read preference modes are not compatible with read preferences modes that use tag sets If you specify a tag set with primary, the driver will produce an error.
+
+### :primary_preferred
+
+With the primaryPreferred read preference mode, operations will read from the primary member of the set in most situations. However, if the primary is unavailable, as is the case during failover situations, then these read operations can read from secondary members.
+
+When the read preference includes a tag set, the client will first read from the primary, if it is available, and then from secondaries that match the specified tags. If there are no secondaries with tags that match the specified tags, this read operation will produce an error.
+
+### :secondary
+
+With the secondary read preference mode, operations will read from the secondary member of the set if available. However, if there are no secondaries available, then these operations will produce an error or exception.
+
+Most sets have at least one secondary, but there are situations where there may not be an available secondary. For example, a set with a primary, a secondary, and an arbiter may not have any secondaries if a member is ever in recovering mode.
+
+When the read preference includes a tag set, the client will attempt to find a secondary members that match the specified tag set and directs reads to a random secondary from among the nearest group. If there are no secondaries with tags that match the specified tag set, this read operation will produce an error.
+
+### :secondary_preferred
+
+With the secondaryPreferred, operations will read from secondary members, but in situations where the set only has a primary instance, the read operation will use the set’s primary.
+
+When secondaryPreferred reads from a secondary and the read preference includes a tag set, the client will attempt to find a secondary members that match the specified tag set and directs reads to a random secondary from among the nearest group. If there are no secondaries with tags that match the specified tag set, this read operation will produce an error.
+
+### :nearest
+
+With the nearest, the driver will read from the nearest member of the set according to the member selection process nearest read operations will not have any consideration for the type of the set member. Reads in nearest mode may read from both primaries and secondaries.
+
+Set this mode when you want minimize the effect of network latency on read operations without preference for current or stale data.
+
+If you specify a tag set, the client will attempt to find a secondary members that match the specified tag set and directs reads to a random secondary from among the nearest group.
+
+## Tag Sets
+
+Tag sets can be used in for data center awareness by filtering secondary read operations. Primary reads occur independent of any tags.
+
+A member matches a tag set if its tags match all the tags in the set. For example, a member tagged "{ dc: 'ny', rack: 2, size: 'large' }" matches the tag set "{ dc: 'ny', rack: 2 }". A member's extra tags don't affect whether it's a match.
+
+Here is an example of a query which sends read operations to members in rack 2.
+
+    @collection.find({:name => 'foo'}, :read => :secondary_preferred, :tag_sets => [{:rack => '2'}])
+
+Tag set keys may be symbols or strings. Tag set values should be specified using strings. The `to_s` method will be called on any values provided in the tag set.
+
+Tag sets are used in conjunction with read preference mode. In this example, because we specified a mode of secondary_preferred, if no secondaries can be found that match the tag_set `{:rack => '2'}` then the primary will be used for the query.
+
+If only one tag set is provided, the set can be passed as a single hash parameter iteself without the enclosing array.
+
+    @collection.find({:name => 'foo'}, :read => :secondary_preferred, :tag_sets => {:rack => '2'})
 
-In the v2.0 release of the driver, you'll also be able to specify a read preference consisting of a set of tags. This way,
-you'll be able to direct reads to a replica set member. You can follow this issue's progress here: (https://jira.mongodb.org/browse/RUBY-326).
+Specifiying tag_sets for mode `:primary` is considered an error and will raise a MongoArgumentError as tag_sets do not affect selection of primary members and only primary members can be selected in that particular mode.