From 1f7cbc70d0779f246629278dfd90bdee732ce652 Mon Sep 17 00:00:00 2001 From: Kyle Banker Date: Tue, 6 Sep 2011 16:33:36 -0400 Subject: [PATCH] RUBY-295 document tailable cursor API. --- README.md | 13 +++++----- docs/TAILABLE_CURSORS.md | 51 ++++++++++++++++++++++++++++++++++++++++ 2 files changed, 58 insertions(+), 6 deletions(-) create mode 100644 docs/TAILABLE_CURSORS.md diff --git a/README.md b/README.md index ea62d63..4309159 100644 --- a/README.md +++ b/README.md @@ -7,12 +7,13 @@ This documentation includes other articles of interest, include: 1. [A tutorial](http://api.mongodb.org/ruby/current/file.TUTORIAL.html). 2. [Replica Sets in Ruby](http://api.mongodb.org/ruby/current/file.REPLICA_SETS.html). 3. [Write Concern in Ruby](http://api.mongodb.org/ruby/current/file.WRITE_CONCERN.html). -4. [Read Preference in Ruby](http://api.mongodb.org/ruby/current/file.READ_PREFERENCE.html). -5. [GridFS in Ruby](http://api.mongodb.org/ruby/current/file.GridFS.html). -6. [Frequently Asked Questions](http://api.mongodb.org/ruby/current/file.FAQ.html). -7. [History](http://api.mongodb.org/ruby/current/file.HISTORY.html). -8. [Release plan](http://api.mongodb.org/ruby/current/file.RELEASES.html). -9. [Credits](http://api.mongodb.org/ruby/current/file.CREDITS.html). +4. [Tailable Cursors in Ruby](http://api.mongodb.org/ruby/current/file.TAILABLE_CURSORS.html). +5. [Read Preference in Ruby](http://api.mongodb.org/ruby/current/file.READ_PREFERENCE.html). +6. [GridFS in Ruby](http://api.mongodb.org/ruby/current/file.GridFS.html). +7. [Frequently Asked Questions](http://api.mongodb.org/ruby/current/file.FAQ.html). +8. [History](http://api.mongodb.org/ruby/current/file.HISTORY.html). +9. [Release plan](http://api.mongodb.org/ruby/current/file.RELEASES.html). +10. [Credits](http://api.mongodb.org/ruby/current/file.CREDITS.html). Here's a quick code sample. Again, see the [MongoDB Ruby Tutorial](http://api.mongodb.org/ruby/current/file.TUTORIAL.html) for much more: diff --git a/docs/TAILABLE_CURSORS.md b/docs/TAILABLE_CURSORS.md new file mode 100644 index 0000000..033e595 --- /dev/null +++ b/docs/TAILABLE_CURSORS.md @@ -0,0 +1,51 @@ +# Tailable in Ruby + +Tailable cursors are cursors that remain open even after they've returned +a final result. This way, if more documents are added to a collection (i.e., +to the cursor's result set), then you can continue to call `Cursor#next` to +retrieve those results. Here's a complete test case that demonstrates the use +of tailable cursors. + +Note that tailable cursors are for capped collections only. + + require 'mongo' + require 'test/unit' + + class TestTailable < Test::Unit::TestCase + include Mongo + + def test_tailable + + # Create a connection and capped collection. + @con = Connection.new + @db = @con['test'] + @db.drop_collection('log') + @capped = @db.create_collection('log', :capped => true, :size => 1024) + + # Insert 10 documents. + 10.times do |n| + @capped.insert({:n => n}) + end + + # Create a tailable cursor that iterates the collection in natural order + @tail = Cursor.new(@capped, :tailable => true, :order => [['$natural', 1]]) + + # Call Cursor#next 10 times. Each call returns a document. + 10.times do + assert @tail.next + end + + # But the 11th time, the cursor returns nothing. + assert_nil @tail.next + + # Add a document to the capped collection. + @capped.insert({:n => 100}) + + # Now call Cursor#next again. This will return the just-inserted result. + assert @tail.next + + # Close the cursor. + @tail.close + end + + end