History. RS Doc updates. Write concern docs.

Author: banker

Rakefile

@@ -169,7 +169,7 @@ task :ydoc do
   require File.join(File.dirname(__FILE__), 'lib', 'mongo')
   out = File.join('ydoc', Mongo::VERSION)
   FileUtils.rm_rf('ydoc')
-  system "yardoc lib/**/*.rb lib/mongo/**/*.rb lib/bson/**/*.rb -e yard/yard_ext.rb -p yard/templates -o #{out} --title MongoRuby-#{Mongo::VERSION} --files docs/TUTORIAL.md,docs/GridFS.md,docs/FAQ.md,docs/REPLICA_SETS.md,docs/HISTORY.md,docs/CREDITS.md,docs/1.0_UPGRADE.md"
+  system "yardoc lib/**/*.rb lib/mongo/**/*.rb lib/bson/**/*.rb -e yard/yard_ext.rb -p yard/templates -o #{out} --title MongoRuby-#{Mongo::VERSION} --files docs/TUTORIAL.md,docs/GridFS.md,docs/FAQ.md,docs/REPLICA_SETS.md,docs/WRITE_CONCERN.md,docs/HISTORY.md,docs/CREDITS.md,docs/1.0_UPGRADE.md"
 end
 
 namespace :gem do

docs/HISTORY.md

@@ -1,5 +1,17 @@
 # MongoDB Ruby Driver History
 
+### 1.1.3
+2010-11-29
+
+* Distributed reads for replica set secondaries. See /docs/examples/replica_set.rb and
+  http://api.mongodb.org/ruby/current/file.REPLICA_SETS.html for details.
+* Note: when connecting to a replica set, you must use Connection#multi.
+* Cursor#count takes optional skip and limit
+* Collection#ensure_index for caching index creation calls
+* Collection#update and Collection#remove now return error object when using safe mode
+* Important fix for int/long serialization on bug introduced in 1.0.9
+* Numerous tweaks and bug fixes.
+
 ### 1.1.2
 2010-11-4
 

docs/REPLICA_SETS.md

@@ -14,7 +14,7 @@ The driver will attempt to connect to a master node and, when found, will replac
 
 ### Read slaves
 
-If you want to read from a seconday node, you can pass :read_secondary => true.
+If you want to read from a seconday node, you can pass :read_secondary => true to Connection#multi.
 
     @connection = Connection.multi([['n1.mydb.net', 27017], ['n2.mydb.net', 27017], ['n3.mydb.net', 27017]],
                   :read_secondary => true)
@@ -23,20 +23,21 @@ A random secondary will be chosen to be read from. In a typical multi-process Ru
 
 ### Connection Failures
 
-Imagine that our master node goes offline. How will the driver respond?
+Imagine that either the master node or one of the read nodes goes offline. How will the driver respond?
 
-At first, the driver will try to send operations to what was the master node. These operations will fail, and the driver will raise a *ConnectionFailure* exception. It then becomes the client's responsibility to decide how to handle this.
+If any read operation fails, the driver will raise a *ConnectionFailure* exception. It then becomes the client's responsibility to decide how to handle this.
 
 If the client decides to retry, it's not guaranteed that another member of the replica set will have been promoted to master right away, so it's still possible that the driver will raise another *ConnectionFailure*. However, once a member has been promoted to master, typically within a few seconds, subsequent operations will succeed.
 
 The driver will essentially cycle through all known seed addresses until a node identifies itself as master.
 
 ### Recovery
 
-Driver users may wish to wrap their database calls with failure recovery code. Here's one possibility:
+Driver users may wish to wrap their database calls with failure recovery code. Here's one possibility, which will attempt to connection
+every half second and time out after thirty seconds.
 
     # Ensure retry upon failure
-    def rescue_connection_failure(max_retries=5)
+    def rescue_connection_failure(max_retries=60)
         success = false
         retries = 0
         while !success
@@ -46,7 +47,7 @@ Driver users may wish to wrap their database calls with failure recovery code. H
           rescue Mongo::ConnectionFailure => ex
             retries += 1
             raise ex if retries >= max_retries
-            sleep(1)
+            sleep(0.5)
           end
         end
       end
@@ -74,4 +75,3 @@ Make sure you have a replica set running on localhost before trying to run these
 
 * [Replica Sets](http://www.mongodb.org/display/DOCS/Replica+Set+Configuration)
 * [Replics Set Configuration](http://www.mongodb.org/display/DOCS/Replica+Set+Configuration)
-

docs/WRITE_CONCERN.md

@@ -0,0 +1,28 @@
+# Write Concern in Ruby
+
+## Setting the write concern
+
+Write concern is set using the `:safe` option. There are several possible options:
+
+    @collection.save({:doc => 'foo'}, :safe => true)
+    @collection.save({:doc => 'foo'}, :safe => {:w => 2})
+    @collection.save({:doc => 'foo'}, :safe => {:w => 2, :wtimeout => 200})
+    @collection.save({:doc => 'foo'}, :safe => {:w => 2, :wtimeout => 200, :fsync => true})
+
+The first, `true`, simply indicates that we should request a response from the server to ensure that to errors have occurred. The second, `{:w => 2}`forces the server to wait until at least two servers have recorded the write. The third does the same but will time out if the replication can't be completed in 200 milliseconds. The fourth forces an fsync on each server being written to (note: this option is rarely necessary and will have a dramaticly negative effect on performance).
+
+## Write concern inheritance
+
+The Ruby driver allows you to set write concern on each of four levels: the connection, database, collection, and write operation.
+Objects will inherit the default write concern from their parents. Thus, if you set a write concern of `{:w => 1}` when creating
+a new connection, then all databases and collections created from that connection will inherit the same setting. See this code example:
+
+    @con = Mongo::Connection.new('localhost', 27017, :safe => {:w => 2})
+    @db  = @con['test']
+    @collection = @db['foo']
+    @collection.save({:name => 'foo'})
+
+    @collection.save({:name => 'bar'}, :safe => false)
+
+Here, the first call to Collection#save will use the inherited write concern, `{:w => 2}`. But notice that the second call
+to Collection#save overrides this setting.