hamsterdb Embedded Database 1.1.15
Defines | Typedefs | Functions
hamsterdb Transaction Functions

Defines

#define HAM_TXN_READ_ONLY   1

Typedefs

typedef struct ham_txn_t ham_txn_t

Functions

HAM_EXPORT ham_status_t ham_txn_begin (ham_txn_t **txn, ham_db_t *db, ham_u32_t flags)
HAM_EXPORT ham_status_t ham_txn_commit (ham_txn_t *txn, ham_u32_t flags)
HAM_EXPORT ham_status_t ham_txn_abort (ham_txn_t *txn, ham_u32_t flags)

Define Documentation

#define HAM_TXN_READ_ONLY   1

Flag for ham_txn_begin

Definition at line 1128 of file hamsterdb.h.


Typedef Documentation

typedef struct ham_txn_t ham_txn_t

Definition at line 1089 of file hamsterdb.h.


Function Documentation

HAM_EXPORT ham_status_t ham_txn_abort ( ham_txn_t txn,
ham_u32_t  flags 
)

Aborts a Transaction

This function aborts (= cancels) the sequence of Database operations.

Note that the function will fail with HAM_CURSOR_STILL_OPEN if a Cursor was attached to this Transaction (with ham_cursor_create or ham_cursor_clone), and the Cursor was not closed.

To improve the Durability, you can specify the flag HAM_WRITE_THROUGH when opening or creating the Environment. hamsterdb will then flush all open file handles when committing or aborting a Transaction using fsync(), fdatasync() or FlushFileBuffers(). This slows down performance but makes sure that all file handles and operating system caches are immediately transferred to disk, thus providing a stronger durability in case the computer crashes.

Parameters:
txnPointer to a Transaction structure
flagsOptional flags for aborting the Transaction, combined with bitwise OR. Unused, set to 0.
Returns:
HAM_SUCCESS upon success
HAM_IO_ERROR if writing to the Database file or logfile failed
HAM_CURSOR_STILL_OPEN if there are Cursors attached to this Transaction

Referenced by ham::txn::abort().

HAM_EXPORT ham_status_t ham_txn_begin ( ham_txn_t **  txn,
ham_db_t db,
ham_u32_t  flags 
)

Begins a new Transaction

A Transaction is an atomic sequence of Database operations. With ham_txn_begin a new sequence is started. To write all operations of this sequence to the Database use ham_txn_commit. To abort and cancel this sequence use ham_txn_abort.

In order to use Transactions, the Environment has to be created or opened with the flag HAM_ENABLE_TRANSACTIONS.

Although for historical reasons ham_txn_begin creates a Transaction and attaches it to a Database (the second parameter is a ham_db_t handle), the Transaction is actually valid for the whole Environment.

Note that as of hamsterdb 1.0.4, it is not possible to create multiple Transactions in parallel. This limitation will be removed in further versions.

Parameters:
txnPointer to a pointer of a Transaction structure
dbA valid Database handle
flagsOptional flags for beginning the Transaction, combined with bitwise OR. Possible flags are:
Returns:
HAM_SUCCESS upon success
HAM_OUT_OF_MEMORY if memory allocation failed
HAM_LIMITS_REACHED if there's already an open Transaction (see above)

Referenced by ham::db::begin().

HAM_EXPORT ham_status_t ham_txn_commit ( ham_txn_t txn,
ham_u32_t  flags 
)

Commits a Transaction

This function applies the sequence of Database operations.

Note that the function will fail with HAM_CURSOR_STILL_OPEN if a Cursor was attached to this Transaction (with ham_cursor_create or ham_cursor_clone), and the Cursor was not closed.

To improve the Durability, you can specify the flag HAM_WRITE_THROUGH when opening or creating the Environment. hamsterdb will then flush all open file handles when committing or aborting a Transaction using fsync(), fdatasync() or FlushFileBuffers(). This slows down performance but makes sure that all file handles and operating system caches are immediately transferred to disk, thus providing a stronger durability in case the computer crashes.

Parameters:
txnPointer to a Transaction structure
flagsOptional flags for committing the Transaction, combined with bitwise OR. Unused, set to 0.
Returns:
HAM_SUCCESS upon success
HAM_IO_ERROR if writing to the file failed
HAM_CURSOR_STILL_OPEN if there are Cursors attached to this Transaction

Referenced by ham::txn::commit().