What does useRecyclingCursor mean?

AndrewGilbert

The Table.Search method contains a parameter called useRecyclingCursor. However, the documentation on that parameter is cryptic to me:

If set to true, all the entries in RowCursor will reference the most current row returned by Current. To ensure all the entries in RowCursor remain unique, set useRecyclingCursor to false. The default is true.

Three questions on that:

1. On the first sentence there, what does "the most current row" mean (isn't there only one current row)?
2. On the second sentence, I found some old ArcMap Java documentation here under the "Recycling and cursors" section. Assuming this documentation applies, where the Pro SDK documentation says "To ensure all the entries in RowCursor remain unique," I presume that means "To ensure each row gets its own object instance," correct?
3. What are the use cases for "true" vs. "false" for this parameter?

Thanks.

 

Aashis

A cursor is a data access object with an interface similar to the System.Collections.IEnumerator interface ( except Reset method). RowCursor.MoveNext() returns a Boolean representing whether the last record in the result has been returned. If the result is empty, the first call to RowCursor.MoveNext() will return false.

The recycling cursors offer performance advantages by allocating a single row object and rehydrating it on each fetch of reading data. They can be used to optimize read-only access.

Nonrecycling cursors return a unique instance for each row returned by MoveNext. The rows returned by a non-recycling cursor can be edited. For further details, please see the conceptual doc. 

SearchCursor

Recycling