SERVER-11938 Get collection metadata at ShardFilterStage build time

1 files changed, 34 insertions, 5 deletions

diff --git a/src/mongo/db/exec/shard_filter.h b/src/mongo/db/exec/shard_filter.h
index a9d13a35a22..6dc238e0539 100644
--- a/src/mongo/db/exec/shard_filter.h
+++ b/src/mongo/db/exec/shard_filter.h
@@ -38,14 +38,43 @@
 namespace mongo {
 
     /**
-     * This stage drops documents that don't belong to the shard we're executing on.
+     * This stage drops documents that didn't belong to the shard we're executing on at the time of
+     * construction. This matches the contract for sharded cursorids which guarantees that a
+     * StaleConfigException will be thrown early or the cursorid for its entire lifetime will return
+     * documents matching the shard version set on the connection at the time of cursorid creation.
+     *
+     * A related system will ensure that the data migrated away from a shard will not be deleted as
+     * long as there are active queries from before the migration. Currently, "active queries" is
+     * defined by cursorids so it is important that the metadata used in this stage uses the same
+     * version as the cursorid. Therefore, you must wrap any Runner using this Stage in a
+     * ClientCursor during the same lock grab as constructing the Runner.
+     *
+     * BEGIN NOTE FROM GREG
+     *
+     * There are three sharded query contracts:
+     *
+     * 0) Migration commit takes the db lock - i.e. is serialized with writes and reads.
+     * 1) No data should be returned from a query in ranges of migrations that committed after the
+     * query started, or from ranges not owned when the query began.
+     * 2) No migrated data should be removed from a shard while there are queries that were active
+     * before the migration.
+     *
+     * As implementation details, collection metadata is used to determine the ranges of all data
+     * not actively migrated (or orphaned).  CursorIds are currently used to establish "active"
+     * queries before migration commit.
+     *
+     * Combining all this: if a query is started in a db lock and acquires in that (same) lock the
+     * collection metadata and a cursorId, the query will return results for exactly the ranges in
+     * the metadata (though of arbitrary staleness).  This is the sharded collection query contract.
+     *
+     * END NOTE FROM GREG
      *
      * Preconditions: Child must be fetched.  TODO XXX: when covering analysis is in just build doc
      * and check that against shard key.
      */
     class ShardFilterStage : public PlanStage {
     public:
-        ShardFilterStage(const string& ns, WorkingSet* ws, PlanStage* child);
+        ShardFilterStage(const CollectionMetadataPtr& metadata, WorkingSet* ws, PlanStage* child);
         virtual ~ShardFilterStage();
 
         virtual bool isEOF();
@@ -60,14 +89,14 @@ namespace mongo {
     private:
         WorkingSet* _ws;
         scoped_ptr<PlanStage> _child;
-        string _ns;
 
         // Stats
         CommonStats _commonStats;
         ShardingFilterStats _specificStats;
 
-        bool _initted;
-        CollectionMetadataPtr _metadata;
+        // Note: it is important that this is the metadata from the time this stage is constructed.
+        // See class comment for details.
+        const CollectionMetadataPtr _metadata;
     };
 
 }  // namespace mongo