SERVER-17062 rename NEED_FETCH to NEED_YIELD

34 files changed, 119 insertions, 131 deletions

diff --git a/src/mongo/db/exec/and_hash.cpp b/src/mongo/db/exec/and_hash.cpp
index 10271666d47..35156f32277 100644
--- a/src/mongo/db/exec/and_hash.cpp
+++ b/src/mongo/db/exec/and_hash.cpp
@@ -165,7 +165,7 @@ namespace mongo {
                         _dataMap.clear();
                         return PlanStage::FAILURE;
                     }
-                    // We ignore NEED_TIME. TODO: what do we want to do if we get NEED_FETCH here?
+                    // We ignore NEED_TIME. TODO: what do we want to do if we get NEED_YIELD here?
                 }
             }
 
@@ -330,8 +330,8 @@ namespace mongo {
             if (PlanStage::NEED_TIME == childStatus) {
                 ++_commonStats.needTime;
             }
-            else if (PlanStage::NEED_FETCH == childStatus) {
-                ++_commonStats.needFetch;
+            else if (PlanStage::NEED_YIELD == childStatus) {
+                ++_commonStats.needYield;
                 *out = id;
             }
 
@@ -433,8 +433,8 @@ namespace mongo {
             if (PlanStage::NEED_TIME == childStatus) {
                 ++_commonStats.needTime;
             }
-            else if (PlanStage::NEED_FETCH == childStatus) {
-                ++_commonStats.needFetch;
+            else if (PlanStage::NEED_YIELD == childStatus) {
+                ++_commonStats.needYield;
                 *out = id;
             }
 
diff --git a/src/mongo/db/exec/and_sorted.cpp b/src/mongo/db/exec/and_sorted.cpp
index 5641f52a048..e0e0a664806 100644
--- a/src/mongo/db/exec/and_sorted.cpp
+++ b/src/mongo/db/exec/and_sorted.cpp
@@ -143,8 +143,8 @@ namespace mongo {
             if (PlanStage::NEED_TIME == state) {
                 ++_commonStats.needTime;
             }
-            else if (PlanStage::NEED_FETCH == state) {
-                ++_commonStats.needFetch;
+            else if (PlanStage::NEED_YIELD == state) {
+                ++_commonStats.needYield;
                 *out = id;
             }
 
@@ -262,8 +262,8 @@ namespace mongo {
             if (PlanStage::NEED_TIME == state) {
                 ++_commonStats.needTime;
             }
-            else if (PlanStage::NEED_FETCH == state) {
-                ++_commonStats.needFetch;
+            else if (PlanStage::NEED_YIELD == state) {
+                ++_commonStats.needYield;
                 *out = id;
             }
 
diff --git a/src/mongo/db/exec/cached_plan.cpp b/src/mongo/db/exec/cached_plan.cpp
index 2bc2e39bd1b..1c01f9f827d 100644
--- a/src/mongo/db/exec/cached_plan.cpp
+++ b/src/mongo/db/exec/cached_plan.cpp
@@ -114,8 +114,8 @@ namespace mongo {
             _commonStats.needTime++;
             return PlanStage::NEED_TIME;
         }
-        else if (PlanStage::NEED_FETCH == childStatus) {
-            _commonStats.needFetch++;
+        else if (PlanStage::NEED_YIELD == childStatus) {
+            _commonStats.needYield++;
         }
         else if (PlanStage::NEED_TIME == childStatus) {
             _commonStats.needTime++;
diff --git a/src/mongo/db/exec/collection_scan.cpp b/src/mongo/db/exec/collection_scan.cpp
index 975d78f8bfb..af7605c512b 100644
--- a/src/mongo/db/exec/collection_scan.cpp
+++ b/src/mongo/db/exec/collection_scan.cpp
@@ -66,7 +66,7 @@ namespace mongo {
         _specificStats.direction = params.direction;
 
         // We pre-allocate a WSM and use it to pass up fetch requests. This should never be used
-        // for anything other than passing up NEED_FETCH. We use the loc and owned obj state, but
+        // for anything other than passing up NEED_YIELD. We use the loc and owned obj state, but
         // the loc isn't really pointing at any obj. The obj field of the WSM should never be used.
         WorkingSetMember* member = _workingSet->get(_wsidForFetch);
         member->state = WorkingSetMember::LOC_AND_OWNED_OBJ;
@@ -114,7 +114,7 @@ namespace mongo {
                 // Leave us in a state to try again next time.
                 _iter.reset();
                 *out = WorkingSet::INVALID_ID;
-                return PlanStage::NEED_FETCH;
+                return PlanStage::NEED_YIELD;
             }
 
             ++_commonStats.needTime;
@@ -136,9 +136,8 @@ namespace mongo {
         _lastSeenLoc = curr;
 
         // See if the record we're about to access is in memory. If not, pass a fetch request up.
-        // Note that curr() does not touch the record (on MMAPv1 which is the only place we use
-        // NEED_FETCH) so we are able to yield before touching the record, as long as we do so
-        // before calling getNext().
+        // Note that curr() does not touch the record. This way, we are able to yield before
+        // fetching the record.
         {
             std::auto_ptr<RecordFetcher> fetcher(
                 _params.collection->documentNeedsFetch(_txn, curr));
@@ -148,8 +147,8 @@ namespace mongo {
                 // Pass the RecordFetcher off to the WSM.
                 member->setFetcher(fetcher.release());
                 *out = _wsidForFetch;
-                _commonStats.needFetch++;
-                return NEED_FETCH;
+                _commonStats.needYield++;
+                return NEED_YIELD;
             }
         }
 
@@ -166,7 +165,7 @@ namespace mongo {
             // If getNext thows, it leaves us on the original document.
             invariant(_iter->curr() == curr);
             *out = WorkingSet::INVALID_ID;
-            return PlanStage::NEED_FETCH;
+            return PlanStage::NEED_YIELD;
         }
 
         WorkingSetID id = _workingSet->allocate();
diff --git a/src/mongo/db/exec/count.cpp b/src/mongo/db/exec/count.cpp
index a6bd76382d4..512ae52a2e2 100644
--- a/src/mongo/db/exec/count.cpp
+++ b/src/mongo/db/exec/count.cpp
@@ -156,10 +156,10 @@ namespace mongo {
                 _ws->free(id);
             }
         }
-        else if (PlanStage::NEED_FETCH == state) {
+        else if (PlanStage::NEED_YIELD == state) {
             *out = id;
-            _commonStats.needFetch++;
-            return PlanStage::NEED_FETCH;
+            _commonStats.needYield++;
+            return PlanStage::NEED_YIELD;
         }
 
         _commonStats.needTime++;
diff --git a/src/mongo/db/exec/count_scan.cpp b/src/mongo/db/exec/count_scan.cpp
index 25ad31fea50..4283a4e57a4 100644
--- a/src/mongo/db/exec/count_scan.cpp
+++ b/src/mongo/db/exec/count_scan.cpp
@@ -123,7 +123,7 @@ namespace mongo {
                 _btreeCursor.reset();
                 _endCursor.reset();
                 *out = WorkingSet::INVALID_ID;
-                return PlanStage::NEED_FETCH;
+                return PlanStage::NEED_YIELD;
             }
             ++_commonStats.needTime;
             return PlanStage::NEED_TIME;
@@ -140,7 +140,7 @@ namespace mongo {
             // The cursor shouldn't have moved.
             invariant(_btreeCursor->getValue() == loc);
             *out = WorkingSet::INVALID_ID;
-            return PlanStage::NEED_FETCH;
+            return PlanStage::NEED_YIELD;
         }
 
         checkEnd();
diff --git a/src/mongo/db/exec/delete.cpp b/src/mongo/db/exec/delete.cpp
index bfa27122881..a2184a87b41 100644
--- a/src/mongo/db/exec/delete.cpp
+++ b/src/mongo/db/exec/delete.cpp
@@ -179,8 +179,8 @@ namespace mongo {
                 _idRetrying = id;
                 memberFreer.Dismiss(); // Keep this member around so we can retry deleting it.
                 *out = WorkingSet::INVALID_ID;
-                _commonStats.needFetch++;
-                return NEED_FETCH;
+                _commonStats.needYield++;
+                return NEED_YIELD;
             }
 
             //  As restoreState may restore (recreate) cursors, cursors are tied to the
@@ -193,8 +193,8 @@ namespace mongo {
                 // Note we don't need to retry anything in this case since the delete already
                 // was committed.
                 *out = WorkingSet::INVALID_ID;
-                _commonStats.needFetch++;
-                return NEED_FETCH;
+                _commonStats.needYield++;
+                return NEED_YIELD;
             }
 
             ++_commonStats.needTime;
@@ -215,9 +215,9 @@ namespace mongo {
         else if (PlanStage::NEED_TIME == status) {
             ++_commonStats.needTime;
         }
-        else if (PlanStage::NEED_FETCH == status) {
+        else if (PlanStage::NEED_YIELD == status) {
             *out = id;
-            ++_commonStats.needFetch;
+            ++_commonStats.needYield;
         }
 
         return status;
diff --git a/src/mongo/db/exec/fetch.cpp b/src/mongo/db/exec/fetch.cpp
index 307804dd58f..b98a04da01c 100644
--- a/src/mongo/db/exec/fetch.cpp
+++ b/src/mongo/db/exec/fetch.cpp
@@ -105,7 +105,7 @@ namespace mongo {
                 verify(member->hasLoc());
 
                 // We might need to retrieve 'nextLoc' from secondary storage, in which case we send
-                // a NEED_FETCH request up to the PlanExecutor.
+                // a NEED_YIELD request up to the PlanExecutor.
                 std::auto_ptr<RecordFetcher> fetcher(_collection->documentNeedsFetch(_txn,
                                                                                      member->loc));
                 if (NULL != fetcher.get()) {
@@ -114,8 +114,8 @@ namespace mongo {
                     _idRetrying = id;
                     member->setFetcher(fetcher.release());
                     *out = id;
-                    _commonStats.needFetch++;
-                    return NEED_FETCH;
+                    _commonStats.needYield++;
+                    return NEED_YIELD;
                 }
 
                 // The doc is already in memory, so go ahead and grab it. Now we have a RecordId
@@ -130,8 +130,8 @@ namespace mongo {
                 catch (const WriteConflictException& wce) {
                     _idRetrying = id;
                     *out = WorkingSet::INVALID_ID;
-                    _commonStats.needFetch++;
-                    return NEED_FETCH;
+                    _commonStats.needYield++;
+                    return NEED_YIELD;
                 }
             }
 
@@ -153,8 +153,8 @@ namespace mongo {
         else if (PlanStage::NEED_TIME == status) {
             ++_commonStats.needTime;
         }
-        else if (PlanStage::NEED_FETCH == status) {
-            ++_commonStats.needFetch;
+        else if (PlanStage::NEED_YIELD == status) {
+            ++_commonStats.needYield;
             *out = id;
         }
 
diff --git a/src/mongo/db/exec/geo_near.cpp b/src/mongo/db/exec/geo_near.cpp
index 1ad289ff8ab..af6b60e1c45 100644
--- a/src/mongo/db/exec/geo_near.cpp
+++ b/src/mongo/db/exec/geo_near.cpp
@@ -395,7 +395,7 @@ namespace mongo {
             // Clean up working set.
             workingSet->free(workingSetID);
             return PlanStage::IS_EOF;
-        } else if (state == PlanStage::NEED_FETCH) {
+        } else if (state == PlanStage::NEED_YIELD) {
             *out = workingSetID;
         }
 
@@ -1067,7 +1067,7 @@ namespace mongo {
             // Clean up working set.
             workingSet->free(workingSetID);
             return PlanStage::IS_EOF;
-        } else if (state == PlanStage::NEED_FETCH) {
+        } else if (state == PlanStage::NEED_YIELD) {
             *out = workingSetID;
         }
 
diff --git a/src/mongo/db/exec/group.cpp b/src/mongo/db/exec/group.cpp
index 9b669b1b83b..435b48f47b2 100644
--- a/src/mongo/db/exec/group.cpp
+++ b/src/mongo/db/exec/group.cpp
@@ -199,8 +199,8 @@ namespace mongo {
             ++_commonStats.needTime;
             return state;
         }
-        else if (PlanStage::NEED_FETCH == state) {
-            ++_commonStats.needFetch;
+        else if (PlanStage::NEED_YIELD == state) {
+            ++_commonStats.needYield;
             *out = id;
             return state;
         }
diff --git a/src/mongo/db/exec/idhack.cpp b/src/mongo/db/exec/idhack.cpp
index 5fd7bf8b62d..8d1e9b0b92f 100644
--- a/src/mongo/db/exec/idhack.cpp
+++ b/src/mongo/db/exec/idhack.cpp
@@ -148,8 +148,8 @@ namespace mongo {
                 _idBeingPagedIn = id;
                 member->setFetcher(fetcher.release());
                 *out = id;
-                _commonStats.needFetch++;
-                return NEED_FETCH;
+                _commonStats.needYield++;
+                return NEED_YIELD;
             }
 
             // The doc was already in memory, so we go ahead and return it.
@@ -170,8 +170,8 @@ namespace mongo {
                 _workingSet->free(id);
 
             *out = WorkingSet::INVALID_ID;
-            _commonStats.needFetch++;
-            return NEED_FETCH;
+            _commonStats.needYield++;
+            return NEED_YIELD;
         }
     }
 
diff --git a/src/mongo/db/exec/index_scan.cpp b/src/mongo/db/exec/index_scan.cpp
index c05d42ed7a7..7a302365c9f 100644
--- a/src/mongo/db/exec/index_scan.cpp
+++ b/src/mongo/db/exec/index_scan.cpp
@@ -200,7 +200,7 @@ namespace mongo {
                 _endCursor.reset();
                 _btreeCursor = NULL;
                 *out = WorkingSet::INVALID_ID;
-                return PlanStage::NEED_FETCH;
+                return PlanStage::NEED_YIELD;
             }
         }
 
@@ -212,7 +212,7 @@ namespace mongo {
                 // checkEnd only fails in ways that is safe to call again after yielding.
                 _scanState = CHECKING_END;
                 *out = WorkingSet::INVALID_ID;
-                return PlanStage::NEED_FETCH;
+                return PlanStage::NEED_YIELD;
             }
         }
 
@@ -246,7 +246,7 @@ namespace mongo {
                 // If next throws, it leaves us at the original position.
                 invariant(_indexCursor->getValue() == loc);
                 *out = WorkingSet::INVALID_ID;
-                return PlanStage::NEED_FETCH;
+                return PlanStage::NEED_YIELD;
             }
 
             if (_shouldDedup) {
diff --git a/src/mongo/db/exec/keep_mutations.cpp b/src/mongo/db/exec/keep_mutations.cpp
index adc1c69e5a4..a6db0eb0efd 100644
--- a/src/mongo/db/exec/keep_mutations.cpp
+++ b/src/mongo/db/exec/keep_mutations.cpp
@@ -76,8 +76,8 @@ namespace mongo {
                 else if (PlanStage::NEED_TIME == status) {
                     ++_commonStats.needTime;
                 }
-                else if (PlanStage::NEED_FETCH == status) {
-                    ++_commonStats.needFetch;
+                else if (PlanStage::NEED_YIELD == status) {
+                    ++_commonStats.needYield;
                 }
 
                 return status;
diff --git a/src/mongo/db/exec/limit.cpp b/src/mongo/db/exec/limit.cpp
index a098206f8db..6aa83f083bc 100644
--- a/src/mongo/db/exec/limit.cpp
+++ b/src/mongo/db/exec/limit.cpp
@@ -83,8 +83,8 @@ namespace mongo {
         else if (PlanStage::NEED_TIME == status) {
             ++_commonStats.needTime;
         }
-        else if (PlanStage::NEED_FETCH == status) {
-            ++_commonStats.needFetch;
+        else if (PlanStage::NEED_YIELD == status) {
+            ++_commonStats.needYield;
             *out = id;
         }
 
diff --git a/src/mongo/db/exec/merge_sort.cpp b/src/mongo/db/exec/merge_sort.cpp
index aaf0b9ac962..ab6e9f547e2 100644
--- a/src/mongo/db/exec/merge_sort.cpp
+++ b/src/mongo/db/exec/merge_sort.cpp
@@ -156,9 +156,9 @@ namespace mongo {
                 if (PlanStage::NEED_TIME == code) {
                     ++_commonStats.needTime;
                 }
-                else if (PlanStage::NEED_FETCH == code) {
+                else if (PlanStage::NEED_YIELD == code) {
                     *out = id;
-                    ++_commonStats.needFetch;
+                    ++_commonStats.needYield;
                 }
 
                 return code;
diff --git a/src/mongo/db/exec/multi_iterator.cpp b/src/mongo/db/exec/multi_iterator.cpp
index 46f75f410ad..9f45d9e4531 100644
--- a/src/mongo/db/exec/multi_iterator.cpp
+++ b/src/mongo/db/exec/multi_iterator.cpp
@@ -46,7 +46,7 @@ namespace mongo {
           _ws(ws),
           _wsidForFetch(_ws->allocate()) {
         // We pre-allocate a WSM and use it to pass up fetch requests. This should never be used
-        // for anything other than passing up NEED_FETCH. We use the loc and owned obj state, but
+        // for anything other than passing up NEED_YIELD. We use the loc and owned obj state, but
         // the loc isn't really pointing at any obj. The obj field of the WSM should never be used.
         WorkingSetMember* member = _ws->get(_wsidForFetch);
         member->state = WorkingSetMember::LOC_AND_OWNED_OBJ;
@@ -76,7 +76,7 @@ namespace mongo {
                 // Pass the RecordFetcher off to the WSM on which we're performing the fetch.
                 member->setFetcher(fetcher.release());
                 *out = _wsidForFetch;
-                return NEED_FETCH;
+                return NEED_YIELD;
             }
 
             obj = Snapshotted<BSONObj>(_txn->recoveryUnit()->getSnapshotId(),
@@ -91,7 +91,7 @@ namespace mongo {
             invariant(!_iterators.empty());
             invariant(_iterators.back()->curr() == curr);
             *out = WorkingSet::INVALID_ID;
-            return NEED_FETCH;
+            return NEED_YIELD;
         }
 
         if (curr.isNull())
diff --git a/src/mongo/db/exec/multi_plan.cpp b/src/mongo/db/exec/multi_plan.cpp
index 5400df6f1f3..6f8b84260e7 100644
--- a/src/mongo/db/exec/multi_plan.cpp
+++ b/src/mongo/db/exec/multi_plan.cpp
@@ -150,21 +150,20 @@ namespace mongo {
         else if (PlanStage::NEED_TIME == state) {
             _commonStats.needTime++;
         }
-        else if (PlanStage::NEED_FETCH == state) {
-            _commonStats.needFetch++;
+        else if (PlanStage::NEED_YIELD == state) {
+            _commonStats.needYield++;
         }
 
         return state;
     }
 
     Status MultiPlanStage::tryYield(PlanYieldPolicy* yieldPolicy) {
-        // There are two conditions which cause us to yield during plan selection if we have a
-        // YIELD_AUTO policy:
+        // These are the conditions which can cause us to yield:
         //   1) The yield policy's timer elapsed, or
-        //   2) some stage requested a yield due to a document fetch (NEED_FETCH).
-        // In both cases, the actual yielding happens here.
+        //   2) some stage requested a yield due to a document fetch, or
+        //   3) we need to yield and retry due to a WriteConflictException.
+        // In all cases, the actual yielding happens here.
         if (yieldPolicy->shouldYield()) {
-            // Here's where we yield.
             bool alive = yieldPolicy->yield(_fetcher.get());
 
             if (!alive) {
@@ -379,9 +378,7 @@ namespace mongo {
                 // Assumes that the ranking will pick this plan.
                 doneWorking = true;
             }
-            else if (PlanStage::NEED_FETCH == state) {
-                // Yielding for a NEED_FETCH is handled above. Here we just make sure that the
-                // WSM is fetchable as a sanity check.
+            else if (PlanStage::NEED_YIELD == state) {
                 if (id == WorkingSet::INVALID_ID) {
                     if (!yieldPolicy->allowedToYield())
                         throw WriteConflictException();
diff --git a/src/mongo/db/exec/near.cpp b/src/mongo/db/exec/near.cpp
index 7681b0e983f..a07b5d7e2d1 100644
--- a/src/mongo/db/exec/near.cpp
+++ b/src/mongo/db/exec/near.cpp
@@ -125,9 +125,9 @@ namespace mongo {
             *out = toReturn;
             ++_stats->common.advanced;
         }
-        else if (PlanStage::NEED_FETCH == nextState) {
+        else if (PlanStage::NEED_YIELD == nextState) {
             *out = toReturn;
-            ++_stats->common.needFetch;
+            ++_stats->common.needYield;
         }
         else if (PlanStage::NEED_TIME == nextState) {
             ++_stats->common.needTime;
@@ -157,7 +157,7 @@ namespace mongo {
         double distance;
     };
 
-    // Set "toReturn" when NEED_FETCH.
+    // Set "toReturn" when NEED_YIELD.
     PlanStage::StageState NearStage::bufferNext(WorkingSetID* toReturn, Status* error) {
 
         //
@@ -201,7 +201,7 @@ namespace mongo {
             *error = WorkingSetCommon::getMemberStatus(*_workingSet->get(nextMemberID));
             return intervalState;
         }
-        else if (PlanStage::NEED_FETCH == intervalState) {
+        else if (PlanStage::NEED_YIELD == intervalState) {
             *toReturn = nextMemberID;
             return intervalState;
         }
diff --git a/src/mongo/db/exec/oplogstart.cpp b/src/mongo/db/exec/oplogstart.cpp
index c5fb5eb6066..7fe3257b5cf 100644
--- a/src/mongo/db/exec/oplogstart.cpp
+++ b/src/mongo/db/exec/oplogstart.cpp
@@ -81,7 +81,7 @@ namespace mongo {
             catch (const WriteConflictException& wce) {
                 _subIterators.clear();
                 *out = WorkingSet::INVALID_ID;
-                return NEED_FETCH;
+                return NEED_YIELD;
             }
         }
 
@@ -99,7 +99,7 @@ namespace mongo {
         const RecordId loc = _subIterators.back()->curr();
         if (loc.isNull()) return PlanStage::NEED_TIME;
 
-        // TODO: should we ever try and return NEED_FETCH here?
+        // TODO: should we ever try and return NEED_YIELD here?
         const BSONObj obj = _subIterators.back()->dataFor(loc).releaseToBson();
         if (!_filter->matchesBSON(obj)) {
             _done = true;
diff --git a/src/mongo/db/exec/or.cpp b/src/mongo/db/exec/or.cpp
index b9c1c8f3170..8b3dd286b1b 100644
--- a/src/mongo/db/exec/or.cpp
+++ b/src/mongo/db/exec/or.cpp
@@ -135,12 +135,12 @@ namespace mongo {
         else if (PlanStage::NEED_TIME == childStatus) {
             ++_commonStats.needTime;
         }
-        else if (PlanStage::NEED_FETCH == childStatus) {
-            ++_commonStats.needFetch;
+        else if (PlanStage::NEED_YIELD == childStatus) {
+            ++_commonStats.needYield;
             *out = id;
         }
 
-        // NEED_TIME, ERROR, NEED_FETCH, pass them up.
+        // NEED_TIME, ERROR, NEED_YIELD, pass them up.
         return childStatus;
     }
 
diff --git a/src/mongo/db/exec/plan_stage.h b/src/mongo/db/exec/plan_stage.h
index 4e9f3310b95..98d1d80698d 100644
--- a/src/mongo/db/exec/plan_stage.h
+++ b/src/mongo/db/exec/plan_stage.h
@@ -119,29 +119,28 @@ namespace mongo {
             // nothing output in the out parameter.
             NEED_TIME,
 
-            // The storage engine says we need to yield, possibly to fetch a record from disk.
+            // The storage engine says we need to yield, possibly to fetch a record from disk, or
+            // due to an aborted transaction in the storage layer.
             //
-            // TODO this should be renamed NEED_YIELD.
+            // Full yield request semantics:
             //
-            // Full fetch semantics:
-            //
-            // Each stage that receives a NEED_FETCH from a child must propagate the NEED_FETCH up
+            // Each stage that receives a NEED_YIELD from a child must propagate the NEED_YIELD up
             // and perform no work.
             //
             // If a yield is requested due to a WriteConflict, the out parameter of work(...) should
             // be populated with WorkingSet::INVALID_ID. If it is illegal to yield, a
             // WriteConflictException will be thrown.
             //
-            // A fetch-requesting stage populates the out parameter of work(...) with a WSID that
+            // A yield-requesting stage populates the out parameter of work(...) with a WSID that
             // refers to a WSM with a Fetcher*. If it is illegal to yield, this is ignored. This
             // difference in behavior can be removed once SERVER-16051 is resolved.
             //
             // The plan executor is responsible for yielding and, if requested, paging in the data
-            // upon receipt of a NEED_FETCH. The plan executor does NOT free the WSID of the
+            // upon receipt of a NEED_YIELD. The plan executor does NOT free the WSID of the
             // requested fetch. The stage that requested the fetch holds the WSID of the loc it
             // wants fetched. On the next call to work() that stage can assume a fetch was performed
             // on the WSM that the held WSID refers to.
-            NEED_FETCH,
+            NEED_YIELD,
 
             // Something went wrong but it's not an internal error.  Perhaps our collection was
             // dropped or state deleted.
@@ -165,8 +164,8 @@ namespace mongo {
             else if (NEED_TIME == state) {
                 return "NEED_TIME";
             }
-            else if (NEED_FETCH == state) {
-                return "NEED_FETCH";
+            else if (NEED_YIELD == state) {
+                return "NEED_YIELD";
             }
             else if (DEAD == state) {
                 return "DEAD";
diff --git a/src/mongo/db/exec/plan_stats.h b/src/mongo/db/exec/plan_stats.h
index 252122f0025..3238055d9f3 100644
--- a/src/mongo/db/exec/plan_stats.h
+++ b/src/mongo/db/exec/plan_stats.h
@@ -64,7 +64,7 @@ namespace mongo {
                         invalidates(0),
                         advanced(0),
                         needTime(0),
-                        needFetch(0),
+                        needYield(0),
                         executionTimeMillis(0),
                         isEOF(false) { }
         // String giving the type of the stage. Not owned.
@@ -79,7 +79,7 @@ namespace mongo {
         // How many times was this state the return value of work(...)?
         size_t advanced;
         size_t needTime;
-        size_t needFetch;
+        size_t needYield;
 
         // BSON representation of a MatchExpression affixed to this node. If there
         // is no filter affixed, then 'filter' should be an empty BSONObj.
@@ -312,10 +312,6 @@ namespace mongo {
         // Have we seen anything that already had an object?
         size_t alreadyHasObj;
 
-        // How many fetches weren't in memory?  it's common.needFetch.
-        // How many total fetches did we do?  it's common.advanced.
-        // So the number of fetches that were in memory are common.advanced - common.needFetch.
-
         // How many records were we forced to fetch as the result of an invalidation?
         size_t forcedFetches;
 
diff --git a/src/mongo/db/exec/plan_stats_test.cpp b/src/mongo/db/exec/plan_stats_test.cpp
index 55ff41f9cad..805401ea9a5 100644
--- a/src/mongo/db/exec/plan_stats_test.cpp
+++ b/src/mongo/db/exec/plan_stats_test.cpp
@@ -48,7 +48,7 @@ namespace {
         ASSERT_EQUALS(stats.invalidates, static_cast<size_t>(0));
         ASSERT_EQUALS(stats.advanced, static_cast<size_t>(0));
         ASSERT_EQUALS(stats.needTime, static_cast<size_t>(0));
-        ASSERT_EQUALS(stats.needFetch, static_cast<size_t>(0));
+        ASSERT_EQUALS(stats.needYield, static_cast<size_t>(0));
         ASSERT_FALSE(stats.isEOF);
     }
 
diff --git a/src/mongo/db/exec/projection.cpp b/src/mongo/db/exec/projection.cpp
index 0a8b09e07bf..e907a5eca7a 100644
--- a/src/mongo/db/exec/projection.cpp
+++ b/src/mongo/db/exec/projection.cpp
@@ -242,8 +242,8 @@ namespace mongo {
         else if (PlanStage::NEED_TIME == status) {
             _commonStats.needTime++;
         }
-        else if (PlanStage::NEED_FETCH == status) {
-            _commonStats.needFetch++;
+        else if (PlanStage::NEED_YIELD == status) {
+            _commonStats.needYield++;
             *out = id;
         }
 
diff --git a/src/mongo/db/exec/shard_filter.cpp b/src/mongo/db/exec/shard_filter.cpp
index 2e5388f3807..c1aa49df04e 100644
--- a/src/mongo/db/exec/shard_filter.cpp
+++ b/src/mongo/db/exec/shard_filter.cpp
@@ -118,8 +118,8 @@ namespace mongo {
         else if (PlanStage::NEED_TIME == status) {
             ++_commonStats.needTime;
         }
-        else if (PlanStage::NEED_FETCH == status) {
-            ++_commonStats.needFetch;
+        else if (PlanStage::NEED_YIELD == status) {
+            ++_commonStats.needYield;
         }
 
         return status;
diff --git a/src/mongo/db/exec/skip.cpp b/src/mongo/db/exec/skip.cpp
index f20f4a90935..a0026d2b829 100644
--- a/src/mongo/db/exec/skip.cpp
+++ b/src/mongo/db/exec/skip.cpp
@@ -85,12 +85,12 @@ namespace mongo {
         else if (PlanStage::NEED_TIME == status) {
             ++_commonStats.needTime;
         }
-        else if (PlanStage::NEED_FETCH == status) {
-            ++_commonStats.needFetch;
+        else if (PlanStage::NEED_YIELD == status) {
+            ++_commonStats.needYield;
             *out = id;
         }
 
-        // NEED_TIME, NEED_FETCH, ERROR, IS_EOF
+        // NEED_TIME, NEED_YIELD, ERROR, IS_EOF
         return status;
     }
 
diff --git a/src/mongo/db/exec/sort.cpp b/src/mongo/db/exec/sort.cpp
index 611ae612a0b..275f99b62db 100644
--- a/src/mongo/db/exec/sort.cpp
+++ b/src/mongo/db/exec/sort.cpp
@@ -399,8 +399,8 @@ namespace mongo {
             else if (PlanStage::NEED_TIME == code) {
                 ++_commonStats.needTime;
             }
-            else if (PlanStage::NEED_FETCH == code) {
-                ++_commonStats.needFetch;
+            else if (PlanStage::NEED_YIELD == code) {
+                ++_commonStats.needYield;
                 *out = id;
             }
 
diff --git a/src/mongo/db/exec/subplan.cpp b/src/mongo/db/exec/subplan.cpp
index 40d458f879a..d1f1377980e 100644
--- a/src/mongo/db/exec/subplan.cpp
+++ b/src/mongo/db/exec/subplan.cpp
@@ -482,8 +482,8 @@ namespace mongo {
         if (PlanStage::NEED_TIME == state) {
             ++_commonStats.needTime;
         }
-        else if (PlanStage::NEED_FETCH == state) {
-            ++_commonStats.needFetch;
+        else if (PlanStage::NEED_YIELD == state) {
+            ++_commonStats.needYield;
         }
         else if (PlanStage::ADVANCED == state) {
             ++_commonStats.advanced;
diff --git a/src/mongo/db/exec/text.cpp b/src/mongo/db/exec/text.cpp
index d247311a878..fc876d0f17c 100644
--- a/src/mongo/db/exec/text.cpp
+++ b/src/mongo/db/exec/text.cpp
@@ -92,7 +92,7 @@ namespace mongo {
                 _internalState = INIT_SCANS;
                 _scanners.clear();
                 *out = WorkingSet::INVALID_ID;
-                stageState = NEED_FETCH;
+                stageState = NEED_YIELD;
             }
             break;
 
@@ -115,8 +115,8 @@ namespace mongo {
         case PlanStage::NEED_TIME:
             ++_commonStats.needTime;
             break;
-        case PlanStage::NEED_FETCH:
-            ++_commonStats.needFetch;
+        case PlanStage::NEED_YIELD:
+            ++_commonStats.needYield;
             break;
         default:
             break;
@@ -311,8 +311,8 @@ namespace mongo {
         catch (const WriteConflictException& wce) {
             // Do this record again next time around.
             *out = WorkingSet::INVALID_ID;
-            _commonStats.needFetch++;
-            return NEED_FETCH;
+            _commonStats.needYield++;
+            return NEED_YIELD;
         }
 
         _scoreIterator++;
@@ -425,7 +425,7 @@ namespace mongo {
                 catch (const WriteConflictException& wce) {
                     _idRetrying = wsid;
                     *out = WorkingSet::INVALID_ID;
-                    return NEED_FETCH;
+                    return NEED_YIELD;
                 }
                 catch (const TextMatchableDocument::DocumentDeletedException&) {
                     // We attempted to fetch the document but decided it should be excluded from the
diff --git a/src/mongo/db/exec/text.h b/src/mongo/db/exec/text.h
index 2eb85df585d..6a5d01a818b 100644
--- a/src/mongo/db/exec/text.h
+++ b/src/mongo/db/exec/text.h
@@ -76,8 +76,8 @@ namespace mongo {
      * Prerequisites: None; is a leaf node.
      * Output type: LOC_AND_OBJ_UNOWNED.
      *
-     * TODO: Should the TextStage ever generate NEED_FETCH requests? Right now this stage could
-     * reduce concurrency by failing to request a yield during fetch.
+     * TODO: Should the TextStage ever generate NEED_YIELD requests for fetching MMAP v1 records?
+     * Right now this stage could reduce concurrency by failing to request a yield during fetch.
      */
     class TextStage : public PlanStage {
     public:
diff --git a/src/mongo/db/exec/update.cpp b/src/mongo/db/exec/update.cpp
index 75eab481201..a2b1c991185 100644
--- a/src/mongo/db/exec/update.cpp
+++ b/src/mongo/db/exec/update.cpp
@@ -859,8 +859,8 @@ namespace mongo {
                 _idRetrying = id;
                 memberFreer.Dismiss(); // Keep this member around so we can retry updating it.
                 *out = WorkingSet::INVALID_ID;
-                _commonStats.needFetch++;
-                return NEED_FETCH;
+                _commonStats.needYield++;
+                return NEED_YIELD;
             }
 
             // This should be after transformAndUpdate to make sure we actually updated this doc.
@@ -877,8 +877,8 @@ namespace mongo {
                 // Note we don't need to retry anything in this case since the update already
                 // was committed.
                 *out = WorkingSet::INVALID_ID;
-                _commonStats.needFetch++;
-                return NEED_FETCH;
+                _commonStats.needYield++;
+                return NEED_YIELD;
             }
 
             ++_commonStats.needTime;
@@ -905,8 +905,8 @@ namespace mongo {
         else if (PlanStage::NEED_TIME == status) {
             ++_commonStats.needTime;
         }
-        else if (PlanStage::NEED_FETCH == status) {
-            ++_commonStats.needFetch;
+        else if (PlanStage::NEED_YIELD == status) {
+            ++_commonStats.needYield;
             *out = id;
         }
 
diff --git a/src/mongo/db/exec/working_set_common.h b/src/mongo/db/exec/working_set_common.h
index a31079a36c1..e1e207d22bc 100644
--- a/src/mongo/db/exec/working_set_common.h
+++ b/src/mongo/db/exec/working_set_common.h
@@ -56,9 +56,8 @@ namespace mongo {
         static void prepareForSnapshotChange(WorkingSet* workingSet);
 
         /**
-         * After a NEED_FETCH is requested, this is used to actually retrieve the document
-         * corresponding to 'member' from 'collection', and to set the state of 'member'
-         * appropriately.
+         * Retrieves the document corresponding to 'member' from 'collection', and sets the state of
+         * 'member' appropriately.
          *
          * If false is returned, the document should not be considered for the result set. It is the
          * caller's responsibility to free 'member' in this case.
diff --git a/src/mongo/db/query/explain.cpp b/src/mongo/db/query/explain.cpp
index 671f48c4791..6247040e267 100644
--- a/src/mongo/db/query/explain.cpp
+++ b/src/mongo/db/query/explain.cpp
@@ -231,7 +231,7 @@ namespace mongo {
             bob->appendNumber("works", stats.common.works);
             bob->appendNumber("advanced", stats.common.advanced);
             bob->appendNumber("needTime", stats.common.needTime);
-            bob->appendNumber("needFetch", stats.common.needFetch);
+            bob->appendNumber("needYield", stats.common.needYield);
             bob->appendNumber("saveState", stats.common.yields);
             bob->appendNumber("restoreState", stats.common.unyields);
             bob->appendNumber("isEOF", stats.common.isEOF);
diff --git a/src/mongo/db/query/plan_executor.cpp b/src/mongo/db/query/plan_executor.cpp
index d12c04a391d..4e62046da81 100644
--- a/src/mongo/db/query/plan_executor.cpp
+++ b/src/mongo/db/query/plan_executor.cpp
@@ -317,13 +317,12 @@ namespace mongo {
         size_t writeConflictsInARow = 0;
 
         for (;;) {
-            // There are two conditions which cause us to yield if we have an YIELD_AUTO
-            // policy:
+            // These are the conditions which can cause us to yield:
             //   1) The yield policy's timer elapsed, or
-            //   2) some stage requested a yield due to a document fetch (NEED_FETCH).
-            // In both cases, the actual yielding happens here.
+            //   2) some stage requested a yield due to a document fetch, or
+            //   3) we need to yield and retry due to a WriteConflictException.
+            // In all cases, the actual yielding happens here.
             if (_yieldPolicy->shouldYield()) {
-                // Here's where we yield.
                 _yieldPolicy->yield(fetcher.get());
 
                 if (_killed) {
@@ -338,7 +337,7 @@ namespace mongo {
             WorkingSetID id = WorkingSet::INVALID_ID;
             PlanStage::StageState code = _root->work(&id);
 
-            if (code != PlanStage::NEED_FETCH)
+            if (code != PlanStage::NEED_YIELD)
                 writeConflictsInARow = 0;
 
             if (PlanStage::ADVANCED == code) {
@@ -390,9 +389,7 @@ namespace mongo {
                 }
                 // This result didn't have the data the caller wanted, try again.
             }
-            else if (PlanStage::NEED_FETCH == code) {
-                // Yielding on a NEED_FETCH is handled above, so there's not much to do here.
-                // Just verify that the NEED_FETCH gave us back a WSM that is actually fetchable.
+            else if (PlanStage::NEED_YIELD == code) {
                 if (id == WorkingSet::INVALID_ID) {
                     if (!_yieldPolicy->allowedToYield()) throw WriteConflictException();
                     _opCtx->getCurOp()->debug().writeConflicts++;
@@ -410,6 +407,7 @@ namespace mongo {
                     fetcher.reset(member->releaseFetcher());
                 }
 
+                // If we're allowed to, we will yield next time through the loop.
                 if (_yieldPolicy->allowedToYield()) _yieldPolicy->forceYield();
             }
             else if (PlanStage::NEED_TIME == code) {