Move reference priming to Cursor

[alcaeus]

This PR moves reference priming from the Query::execute method to the cursor which iterates over the results (as described in #1065). This increases performance when iterating over part of a large query result (e.g. by setting skip and limit on the returned cursor before iterating) as it will not prime references for the entire result set.
Note that using prime for findAndUpdate and findAndRemove will prime references when executing the query since it will not return a cursor.
This also fixes a side effect of #520 where using getSingleResult() on a query without limit in combination with prime would prime references for all documents returned in the query instead of just the one returned by getSingleResult().

Feedback is greatly appreciated, I'd really appreciate it if some people using reference priming could run their test suite against the branch and post some results.

NB: I'm not too happy with having to duplicate functionality in Cursor and EagerCursor, unfortunately I can't think of another way since the two classes don't share an interface.

[jwage]

Nice. Looks good to me! 👍

[smolinari]

👍 Thanks for the improvement!

Scott

[blockjon]

Could this PR have caused #1108 ?

[jmikola]

@blockjon: I just looked at this PR diff and I suspect that the new call to primeReferences() from within current() (here) may be related to #1108. Since MongoCursor iteration uses the standard Iterator interface methods, the order of execution will be rewind(), valid(), and then current(). Here, it looks like we're invoking rewind() once again on each first call to current(). So even if no reference priming is requested, it looks as if the query gets re-executed at least one additional time (after the foreach on configured primers, each of which rewind on their own, too!).

Even considering the original priming code, I don't see any reason that this should be re-executing the cursor for each primer. There is no guarantee that the query is going to return the same results on successive executions. Although it would come at an expense of memory, I think that priming would best be restricted to EagerCursors, where all of the documents are cached in an array and no re-execution takes place (rewind() simply resets the array pointer).

@jwage, @alcaeus, @malarzm: Thoughts?

[malarzm]

@jmikola sounds reasonable. So in QueryBuilder ODM will enforce creating query returning EagerCursor if prime() is called, right?

[jmikola]

I think it'd be reasonable to say that:

• prime(true) implies eagerCursor(true) (if eager cursor was never set).
• prime(true) throws if eagerCursor(false) was previously called
• eagerCursor(false) throws if prime(true) was previously called