Merge pull request #2293 from wiredtiger/cusors-ops-wording

WT-2217: change WT_CURSOR.insert to clear "set" key/value on return

2 files changed, 36 insertions, 15 deletions

diff --git a/src/docs/cursor-ops.dox b/src/docs/cursor-ops.dox
index e4832267f08..b743d81db57 100644
--- a/src/docs/cursor-ops.dox
+++ b/src/docs/cursor-ops.dox
@@ -119,24 +119,31 @@ for the backup, config and statistics cursor types.
 
 @section cursor_memory_scoping Cursor key/value memory scoping
 
-When applications pass pointers to WT_CURSOR::set_key or WT_CURSOR::set_value,
-which can be a WT_ITEM or a string, the application is required to keep
-the memory valid until the next operation that successfully positions
-the cursor.  These operations are WT_CURSOR::remove, WT_CURSOR::search,
-WT_CURSOR::search_near and WT_CURSOR::update, but <b>do not include</b>
-WT_CURSOR::insert, as it does not position the cursor.
-
-If such an operation fails (for example, due to a ::WT_ROLLBACK error),
+When applications pass a pointer (either to a WT_ITEM or a string), to
+WT_CURSOR::set_key or WT_CURSOR::set_value, WiredTiger does not copy the
+memory referenced by the pointer. For this reason, the application must
+keep the referenced memory unchanged and valid until the next operation
+that successfully positions the cursor, modifies the underlying data,
+or the cursor is reset or closed (discarding its resources).  The
+operations that position the cursor are WT_CURSOR::next, WT_CURSOR::prev,
+WT_CURSOR::search and WT_CURSOR::search_near; the operations that modify
+the underlying data are WT_CURSOR::insert, WT_CURSOR::update and
+WT_CURSOR::remove.
+
+If a cursor operation fails (for example, due to a ::WT_ROLLBACK error),
 it may be retried without calling WT_CURSOR::set_key or
 WT_CURSOR::set_value again.  That is, the cursor may still reference the
-application-supplied memory until it is successfully positioned.
+application-supplied memory until the cursor is successfully positioned,
+underlying data is modified, or the cursor is closed or reset.
 
 @m_if{c}
-Any pointers returned by WT_CURSOR::get_key or WT_CURSOR::get_value are only
-valid until the cursor is positioned.  These pointers may reference private
-WiredTiger data structures that must not be modified or freed by the
-application.  If a longer scope is required, the application must make a copy
-of the memory before the cursor is positioned.
+Any pointers returned by WT_CURSOR::get_key or WT_CURSOR::get_value are
+only valid until a subsequent cursor call that successfully positions
+the cursor, modifies the underlying data, or the cursor is reset or
+closed. These pointers may reference private WiredTiger data structures
+that may not be modified or freed by the application.  If a longer scope
+is required, the application must make a copy of the memory before the
+cursor is re-used, closed or reset.
 
 The comments in this example code explain when the application can safely
 modify memory passed to WT_CURSOR::set_key or WT_CURSOR::set_value:
diff --git a/src/docs/upgrading.dox b/src/docs/upgrading.dox
index e0640660b0a..3b227d00198 100644
--- a/src/docs/upgrading.dox
+++ b/src/docs/upgrading.dox
@@ -11,7 +11,21 @@ was relying on this behavior, a connection will be opened with different
 settings after upgrading, which could lead to errors or unexpected behavior.
 </dd>
 
-<dl>
+<dt>Change to WT_CURSOR::insert</dt>
+<dd>
+The WT_CURSOR::insert method in this release has slightly different semantics
+with respect to referencing application memory. In previous releases,
+WT_CURSOR::insert continued to reference application-memory specified to
+either WT_CURSOR::set_key or WT_CURSOR::set_value after a successful return,
+which could potentially lead to a core dump if the application freed that
+memory before a subsequent call to a WT_CURSOR:: method without an intermediate
+WT_CURSOR::set_key or WT_CURSOR::set_value call. In the 2.6.2 release,
+WT_CURSOR::insert behaves like the other cursor methods and does not reference
+application memory after a successful return. Applications depending on the
+previous semantic will require modifications to set the cursor's key and/or
+value after a successful WT_CURSOR::insert call.
+</dd>
+
 <dt>WT_SESSION.verify</dt>
 <dd>
 The WT_SESSION.verify method in this release has a new configuration