From 7f9a2c456d0545670f938846d7bfad68f23342c8 Mon Sep 17 00:00:00 2001 From: Don Anderson Date: Mon, 6 Jul 2015 10:50:13 -0400 Subject: WT-1988. Added a doc subsection discussing the interation between cursors and eviction, and the need for using WT_CURSOR::reset. --- src/docs/cursors.dox | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) (limited to 'src/docs') 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 -- cgit v1.2.1