WT-1988. Added a doc subsection discussing the interation between cursors and

eviction, and the need for using WT_CURSOR::reset.

1 files changed, 20 insertions, 0 deletions

diff --git a/src/docs/cursors.dox b/src/docs/cursors.dox
index 06f4321ad02..da719f259e6 100644
--- a/src/docs/cursors.dox
+++ b/src/docs/cursors.dox
@@ -72,6 +72,26 @@ well as any key and value.
 
 See @ref transactions for more information.
 
+@section cursors_eviction Cursors and Eviction
+
+Cursor positions hold resources that may inhibit the eviction of memory pages.
+While eviction can occur as the result of reaching a threshold of cache
+memory usage (see @ref_single tune_cache), it may also occur when an
+individual memory page grows to be larger than the configured \c
+memory_page_max (see the configuration in WT_SESSION::create).
+
+If a cursor is active on a page being considered for eviction, the eviction
+will defer until the cursor is moved. In the specific cases with multiple
+active cursors on a memory page that has reached maximum size, the
+WiredTiger library will never have simultaneous control over both cursors to
+move them to smaller, split pages.  This may prevent a large page from ever
+being split and may potentially slow down the application.
+
+To avoid this situation, or any situation where eviction must be deferred,
+applications should call WT_CURSOR::reset during times that it does not need
+to keep a cursor positioned.  A cursor that has been reset is not active and
+cannot inhibit eviction.
+
 @section cursor_raw Raw mode
 
 Cursors can be configured for raw mode by specifying the \c "raw" config