Import wiredtiger: 994aabd96c7c28ffd7c15e3b81bda3e41ca33005 from branch mongodb-master

ref: 2666d037c9..994aabd96c
for: 6.1.0-rc0

WT-9404       Review updated transactional documentation

4 files changed, 69 insertions, 54 deletions

diff --git a/src/third_party/wiredtiger/import.data b/src/third_party/wiredtiger/import.data
index d9d35bf20c1..92eaf0db2ff 100644
--- a/src/third_party/wiredtiger/import.data
+++ b/src/third_party/wiredtiger/import.data
@@ -2,5 +2,5 @@
     "vendor": "wiredtiger",
     "github": "wiredtiger/wiredtiger.git",
     "branch": "mongodb-master",
-    "commit": "2666d037c9ebfc84db2c739dfc10dab0e28b3e02"
+    "commit": "994aabd96c7c28ffd7c15e3b81bda3e41ca33005"
 }
diff --git a/src/third_party/wiredtiger/src/docs/explain-isolation.dox b/src/third_party/wiredtiger/src/docs/explain-isolation.dox
index ecb8175e51c..d07074f8e31 100644
--- a/src/third_party/wiredtiger/src/docs/explain-isolation.dox
+++ b/src/third_party/wiredtiger/src/docs/explain-isolation.dox
@@ -10,8 +10,8 @@ phantoms are possible.
 Transactions cannot see changes made by other transactions before those
 transactions are committed.  Dirty reads are not possible;
 non-repeatable reads and phantoms are possible.  Committed changes from
-concurrent transactions become visible when no cursor is positioned in
-the read-committed transaction.
+concurrent transactions become visible periodically during the lifecycle
+of the transaction.
 
 - <code>snapshot</code>:
 Transactions read the versions of records committed before the transaction
diff --git a/src/third_party/wiredtiger/src/docs/timestamp-txn.dox b/src/third_party/wiredtiger/src/docs/timestamp-txn.dox
index 9bafa55f2f8..a900ed763fd 100644
--- a/src/third_party/wiredtiger/src/docs/timestamp-txn.dox
+++ b/src/third_party/wiredtiger/src/docs/timestamp-txn.dox
@@ -65,6 +65,66 @@ the library will log an error message and drop core at the failing check.
 These are best-effort checks by WiredTiger, and there are cases where
 application misbehavior will not be detected.
 
+@section timestamp_txn_api_commit_timestamp Setting the transaction's commit timestamp
+
+The \c commit time is the time at which other transactions with appropriately set
+read timestamps will see the transaction's updates.
+
+The commit timestamp can be set at any point in the transaction's lifecycle.
+For prepared transactions, however, it can only be set after the transaction
+has been successfully prepared.
+
+\warning Commit (and prepare) timestamps must not be set in the past
+of any read timestamp
+that has ever been used. This rule is enforced by assertions in diagnostic
+builds, but if applications violate this rule in non-diagnostic builds, data
+consistency can be violated.
+Similarly, because reading without a read timestamp reads the latest
+values for all keys, one must not commit into the past of such a
+transaction.
+
+Applications using timestamps usually specify a timestamp to the
+WT_SESSION::commit_transaction method to set the commit time for all updates in
+the transaction.
+
+For prepared transactions, the commit timestamp must not be before the prepare
+timestamp. Otherwise, the commit timestamp must be after the stable timestamp.
+
+@section timestamp_txn_api_commit_multi_timestamp Setting multiple commit timestamps
+
+Applications may set different commit timestamps for different updates in a
+single transaction by calling WT_SESSION::timestamp_transaction repeatedly to
+set a new commit timestamp between updates in the transaction.  Each new commit
+timestamp is applied to any subsequent updates. This gives applications the
+ability to commit updates that take effect at different times;
+that is, it is possible to create chains of updates where each
+update appears at a different time to readers.  For transactions that set
+multiple commit timestamps, the first commit timestamp set is also required to
+be the earliest: the second and subsequent commit timestamps may not be
+earlier than the first commit timestamp.  This feature is not compatible with
+prepared transactions, which must use only a single commit timestamp.
+
+This functionality is generally available as a mechanism to allow an optimized
+implementation of re-creating a timestamp view of a data set. For example, in
+a MongoDB replica set, content is generated on one node where transactions are
+assigned a single commit timestamp, that content is re-created on each other
+member in a replica set. When re-creating the content multiple changes from
+the original node are batched together into a single WiredTiger transaction.
+
+@section timestamp_txn_api_read_timestamp Setting the transaction's read timestamp
+
+Setting the transaction's read timestamp causes a transaction to not see any
+commits with a newer timestamp. (Updates may still conflict with commits having
+a newer timestamp, of course.),
+
+The read timestamp may be set to any time equal to or after the system's
+\c oldest timestamp.
+
+This restriction is enforced and applications can rely on an error return to
+detect attempts to set the read timestamp older than the \c oldest timestamp.
+
+The read timestamp may only be set once in the lifetime of a transaction.
+
 @section timestamp_txn_api_query Querying transaction timestamp information
 
 The following table lists the timestamps that can be queried using
@@ -119,55 +179,4 @@ points in the transaction's lifetime, using WT_SESSION::timestamp_transaction:
 | prepare_timestamp | > stable and >= any system read timestamp | the transaction's prepare timestamp, see @ref timestamp_prepare for details |
 | read_timestamp | >= oldest | the transaction's read timestamp, see @ref timestamp_txn_api_read_timestamp for details |
 
-@section timestamp_txn_api_commit_timestamp Setting the transaction's commit timestamp
-
-The \c commit time is the time at which other transactions with appropriately set
-read timestamps will see the transaction's updates.
-
-The commit timestamp can be set at any point in the transaction's lifecycle.
-For prepared transactions, however, it can only be set after the transaction
-has been successfully prepared.
-
-\warning Commit (and prepare) timestamps must not be set in the past
-of any read timestamp
-that has ever been used. This rule is enforced by assertions in diagnostic
-builds, but if applications violate this rule in non-diagnostic builds, data
-consistency can be violated.
-Similarly, because reading without a read timestamp reads the latest
-values for all keys, one must not commit into the past of such a
-transaction.
-
-Applications using timestamps usually specify a timestamp to the
-WT_SESSION::commit_transaction method to set the commit time for all updates in
-the transaction.
-
-Applications may set different commit timestamps for different updates in a
-single transaction by calling WT_SESSION::timestamp_transaction repeatedly to
-set a new commit timestamp between updates in the transaction.  Each new commit
-timestamp is applied to any subsequent updates. This gives applications the
-ability to commit updates that take effect at different times;
-that is, it is possible to create chains of updates where each
-update appears at a different time to readers.  For transactions that set
-multiple commit timestamps, the first commit timestamp set is also required to
-be the earliest: the second and subsequent commit timestamps may not be
-earlier than the first commit timestamp.  This feature is not compatible with
-prepared transactions, which must use only a single commit timestamp.
-
-For prepared transactions, the commit timestamp must not be before the prepare
-timestamp. Otherwise, the commit timestamp must be after the stable timestamp.
-
-@section timestamp_txn_api_read_timestamp Setting the transaction's read timestamp
-
-Setting the transaction's read timestamp causes a transaction to not see any
-commits with a newer timestamp. (Updates may still conflict with commits having
-a newer timestamp, of course.),
-
-The read timestamp may be set to any time equal to or after the system's
-\c oldest timestamp.
-
-This restriction is enforced and applications can rely on an error return to
-detect attempts to set the read timestamp older than the \c oldest timestamp.
-
-The read timestamp may only be set once in the lifetime of a transaction.
-
  */
diff --git a/src/third_party/wiredtiger/src/docs/transactions_api.dox b/src/third_party/wiredtiger/src/docs/transactions_api.dox
index 3ccf2776fea..641ba2e8ed2 100644
--- a/src/third_party/wiredtiger/src/docs/transactions_api.dox
+++ b/src/third_party/wiredtiger/src/docs/transactions_api.dox
@@ -25,6 +25,12 @@ effects may be discarded by calling WT_SESSION::rollback_transaction. If
 WT_SESSION::commit_transaction returns any error, the transaction was rolled
 back, not committed.
 
+Schema changing operations are not generally transactional in WiredTiger, they
+can't be grouped together within the scope of a transaction and atomically
+committed or aborted. Think of them as one-shot transactions where the operation
+will either succeed or fail. Examples of schema changing operations are table
+create, drop and rename.
+
 A data operation executed within a transaction can fail if it conflicts with an
 operation in another concurrently running transaction.  (A conflict occurs
 between two operations when letting both of them continue would lead to a