Merge branch 'master' of ssh://aaron@git.10gen.com/data/gitroot/p

3 files changed, 47 insertions, 15 deletions

diff --git a/client/connpool.h b/client/connpool.h
index 9c6cf6fadf1..30b86a06241 100644
--- a/client/connpool.h
+++ b/client/connpool.h
@@ -28,6 +28,7 @@ namespace mongo {
     };
 
     /** Database connection pool.
+
         Generally, use ScopedDbConnection and do not call these directly.
 
         This class, so far, is suitable for use with unauthenticated connections. 
@@ -61,30 +62,35 @@ namespace mongo {
         const string host;
         DBClientBase *_conn;
     public:
+        /** get the associated connection object */
         DBClientBase* operator->(){ 
             uassert( "did you call done already" , _conn );
             return _conn; 
         }
 
+        /** get the associated connection object */
         DBClientBase& conn() {
             uassert( "did you call done already" , _conn );
             return *_conn;
         }
 
-        /* throws UserAssertionAcception if can't connect */
+        /** throws UserException if can't connect */
         ScopedDbConnection(const string& _host) :
                 host(_host), _conn( pool.get(_host) ) { }
 
-        /* Force closure of the connection.  You should call this if you leave it in
-           a bad state.  Destructor will do this too, but it is verbose.
+        /** Force closure of the connection.  You should call this if you leave it in
+            a bad state.  Destructor will do this too, but it is verbose.
         */
         void kill() {
             delete _conn;
             _conn = 0;
         }
 
-        /* Call this when you are done with the connection.
-             Why?  See note in the destructor below.
+        /** Call this when you are done with the connection.
+            
+            If you do not call done() before this object goes out of scope, 
+            we can't be sure we fully read all expected data of a reply on the socket.  so
+            we don't try to reuse the connection in that situation.
         */
         void done() {
             if ( ! _conn )
@@ -101,11 +107,7 @@ namespace mongo {
 
         ~ScopedDbConnection() {
             if ( _conn ) {
-                /* you are supposed to call done().  if you did that, correctly, we
-                   only get here if an exception was thrown.  in such a scenario, we can't
-                   be sure we fully read all expected data of a reply on the socket.  so
-                   we don't try to reuse the connection.  The out() is just informational.
-                   */
+                /* see done() comments above for why we log this line */
                 out() << "~ScopedDBConnection: _conn != null\n";
                 kill();
             }
diff --git a/client/dbclient.h b/client/dbclient.h
index 090f72481d1..b4775f111c4 100644
--- a/client/dbclient.h
+++ b/client/dbclient.h
@@ -75,7 +75,10 @@ namespace mongo {
     };
 #pragma pack()
 
-    /** Represents a query */    
+    /** Represents a query.  Typically one uses the QUERY(...) macro to construct a query object. 
+        Example:
+           QUERY( "age" << 33 << "school" << "UCLA" ).sort("name")
+    */    
     class Query {
     public:
         BSONObj obj;
@@ -503,8 +506,11 @@ namespace mongo {
          */
         virtual void update( const char * ns , Query query , BSONObj obj , bool upsert = 0 );
 
-        /**
-           if name isn't specified, it will be created from the keys (recommended)
+        /** Create an index if it does not already exist.
+            ensureIndex calls are remembered so it is safe/fast to call this function many 
+            times in your code.
+           @param name if not isn't specified, it will be created from the keys (recommended)
+           @param keys the "key pattern" for the index.  e.g., { name : 1 }
            @return whether or not sent message to db.
              should be true on first call, false on subsequent unless resetIndexCache was called
          */
diff --git a/client/examples/tutorial.cpp b/client/examples/tutorial.cpp
index df38883533d..b585af64fed 100644
--- a/client/examples/tutorial.cpp
+++ b/client/examples/tutorial.cpp
@@ -1,18 +1,42 @@
 #include <iostream>
 #include "../../client/dbclient.h"
 
-// g++ -I ../.. -L ../.. tutorial.cpp -lmongoclient -lboost_thread -lboost_filesystem
+// g++ tutorial.cpp -lmongoclient -lboost_thread -lboost_filesystem -o tutorial
 
 using namespace mongo;
 
+void printIfAge(DBClientConnection& c, int age) {

+  auto_ptr<DBClientCursor> cursor = c.query("tutorial.persons", QUERY( "age" << age ).sort("name") );

+  while( cursor->more() ) {

+    BSONObj p = cursor->next();

+    cout << p.getStringField("name") << endl;

+  }

+}
+
 void run() {
   DBClientConnection c;
-  c.connect("192.168.58.1");
+  c.connect("localhost"); //"192.168.58.1");
   cout << "connected ok" << endl;
   BSONObj p = BSON( "name" << "Joe" << "age" << 33 );
   c.insert("tutorial.persons", p);
+  p = BSON( "name" << "Jane" << "age" << 40 );
+  c.insert("tutorial.persons", p);
+  p = BSON( "name" << "Abe" << "age" << 33 );
+  c.insert("tutorial.persons", p);
+  p = BSON( "name" << "Samantha" << "age" << 21 << "city" << "Los Angeles" << "state" << "CA" );
+  c.insert("tutorial.persons", p);
+
+  c.ensureIndex("tutorial.persons", fromjson("{age:1}"));
 
   cout << "count:" << c.count("tutorial.persons") << endl;
+
+  auto_ptr<DBClientCursor> cursor = c.query("tutorial.persons", emptyObj);
+  while( cursor->more() ) { 
+      cout << cursor->next().toString() << endl;
+  }
+
+  cout << "\nprintifage:\n";
+  printIfAge(c, 33);
 }
 
 int main() {