diff options
| -rw-r--r-- | examples/c/ex_all.c | 59 | ||||
| -rw-r--r-- | src/docs/transactions.dox | 37 | ||||
| -rw-r--r-- | src/include/wiredtiger.in | 6 |
3 files changed, 44 insertions, 58 deletions
diff --git a/examples/c/ex_all.c b/examples/c/ex_all.c index 6c39aaeda20..b47ff231b25 100644 --- a/examples/c/ex_all.c +++ b/examples/c/ex_all.c @@ -447,18 +447,6 @@ session_ops(WT_SESSION *session) ret = session->verify(session, "table:mytable", NULL); /*! [Verify a table] */ - /*! [Begin a transaction] */ - ret = session->begin_transaction(session, NULL); - /*! [Begin a transaction] */ - - /*! [Commit a transaction] */ - ret = session->commit_transaction(session, NULL); - /*! [Commit a transaction] */ - - /*! [Rollback a transaction] */ - ret = session->rollback_transaction(session, NULL); - /*! [Rollback a transaction] */ - /*! [Close a session] */ ret = session->close(session, NULL); /*! [Close a session] */ @@ -469,44 +457,41 @@ session_ops(WT_SESSION *session) int transaction_ops(WT_CONNECTION *conn, WT_SESSION *session) { - WT_CURSOR *cursor; + WT_CURSOR *cursor, *cursor1, *cursor2; int ret; - /*! [simple transaction] */ - ret = session->begin_transaction(session, NULL); + /*! [transaction commit/rollback] */ ret = session->open_cursor(session, "table:mytable", NULL, NULL, &cursor); - cursor->set_key(cursor, "some-key"); - cursor->set_value(cursor, "some-value"); - ret = cursor->update(cursor); - ret = session->commit_transaction(session, NULL); - + ret = session->begin_transaction(session, NULL); /* - * The cursor position has been reset by the transaction commit, it - * can be used again until the handle is explicitly closed. + * Cursors may be opened before or after the transaction begins, and in + * either case, subsequent operations are included in the transaction. + * The begin_transaction call resets all open cursors. */ - ret = cursor->close(cursor); - /*! [simple transaction] */ - /*! [simple rollback transaction] */ - ret = - session->open_cursor(session, "table:mytable", NULL, NULL, &cursor); - ret = session->begin_transaction(session, NULL); - cursor->set_key(cursor, "some-key"); - cursor->set_value(cursor, "some-value"); - ret = cursor->update(cursor); - switch (ret) { - case 0: + cursor->set_key(cursor, "key"); + cursor->set_value(cursor, "value"); + switch (ret = cursor->update(cursor)) { + case 0: /* Update success */ ret = session->commit_transaction(session, NULL); + /* + * The commit_transaction call resets all open cursors. + * If commit_transaction fails, the transaction was rolled-back. + */ break; - case WT_DEADLOCK: /* Conflict */ + case WT_DEADLOCK: /* Update conflict */ default: /* Other error */ ret = session->rollback_transaction(session, NULL); + /* The rollback_transaction call resets all open cursors. */ break; } - /*! [simple rollback transaction] */ - /*! [simple transaction isolation] */ + /* Cursors remain open and may be used for multiple transactions. */ + /*! [transaction commit/rollback] */ + ret = cursor->close(cursor); + + /*! [transaction isolation] */ /* A single transaction configured for snapshot isolation. */ ret = session->open_cursor(session, "table:mytable", NULL, NULL, &cursor); @@ -515,7 +500,7 @@ transaction_ops(WT_CONNECTION *conn, WT_SESSION *session) cursor->set_value(cursor, "some-value"); ret = cursor->update(cursor); ret = session->commit_transaction(session, NULL); - /*! [simple transaction isolation] */ + /*! [transaction isolation] */ /*! [session isolation configuration] */ /* Open a session configured for read-uncommitted isolation. */ diff --git a/src/docs/transactions.dox b/src/docs/transactions.dox index 46df3589759..33e75c63ad0 100644 --- a/src/docs/transactions.dox +++ b/src/docs/transactions.dox @@ -24,28 +24,29 @@ properties: @section transactions_api Transactional API -In WiredTiger, the transactional context is managed by the WT_SESSION -class. Applications call WT_SESSION::begin_transaction to start a new -transaction. Operations performed with that WT_SESSION handle -(including cursors already open in that WT_SESSION handle and cursors -subsequently opened before the transaction ends), are then part of the -transaction and their effects committed or discarded by calling -WT_SESSION::commit_transaction and WT_SESSION::rollback_transaction. +In WiredTiger, transaction operations are methods off the WT_SESSION +class. -Both WT_SESSION::commit_transaction and WT_SESSION::rollback_transaction -implicitly reset all open cursors. +Applications call WT_SESSION::begin_transaction to start a new +transaction. Operations subsequently performed using that WT_SESSION +handle, including operations on any cursors open in that WT_SESSION +handle, are implicitly part of the transaction and their effects +committed by calling WT_SESSION::commit_transaction, or discarded by +calling WT_SESSION::rollback_transaction. -If WT_SESSION::commit_transaction returns an error for any reason, the -transaction was rolled-back, not committed. +If WT_SESSION::commit_transaction returns an error for any reason, +the transaction was rolled-back, not committed. -@snippet ex_all.c simple transaction +When transactions are used, data operations can encounter a conflict and +fail with the ::WT_DEADLOCK error. If this error occurs, transactions +should be rolled back with WT_SESSION::rollback_transaction and retried. -When transactions are used, update operations that conflict with a -concurrent transaction will fail with the ::WT_DEADLOCK error. -Transactions should be rolled back with WT_SESSION::rollback_transaction -and retried if this error occurs. +The WT_SESSION::begin_transaction, WT_SESSION::commit_transaction and +WT_SESSION::rollback_transaction methods all implicitly reset open +cursors, as if WT_CURSOR::reset were called, discarding any object +position or key values they may have. -@snippet ex_all.c simple rollback transaction +@snippet ex_all.c transaction commit/rollback @section transactions_concurrency Concurrency control @@ -89,7 +90,7 @@ reads. The transaction isolation level can be configured on a per-transaction basis: -@snippet ex_all.c simple transaction isolation +@snippet ex_all.c transaction isolation Additionally, the default transaction isolation can be configured and re-configured on a per-session basis: diff --git a/src/include/wiredtiger.in b/src/include/wiredtiger.in index 34fec563c5b..c5c41070439 100644 --- a/src/include/wiredtiger.in +++ b/src/include/wiredtiger.in @@ -796,7 +796,7 @@ struct __wt_session { * WT_SESSION::transaction_begin will fail if a transaction is already * in progress in the session. * - * @snippet ex_all.c Begin a transaction + * @snippet ex_all.c transaction commit/rollback * * @param session the session handle * @configstart{session.begin_transaction, see dist/api_data.py} @@ -826,7 +826,7 @@ struct __wt_session { * If WT_SESSION::commit_transaction returns an error, the transaction * was rolled-back, not committed. * - * @snippet ex_all.c Commit a transaction + * @snippet ex_all.c transaction commit/rollback * * @param session the session handle * @configempty{session.commit_transaction, see dist/api_data.py} @@ -840,7 +840,7 @@ struct __wt_session { * * All open cursors are reset. * - * @snippet ex_all.c Rollback a transaction + * @snippet ex_all.c transaction commit/rollback * * @param session the session handle * @configempty{session.rollback_transaction, see dist/api_data.py} |