static void abort(os_transaction* = get_current());Aborts the specified transaction. For dynamic transactions, control flows to the next statement after you call abort(). For lexical transactions, control flows to the next statement after the end of the current transaction block. Persistent data is rolled back to its state at the beginning of the transaction. In addition, if the aborted transaction is not nested within another transaction, all locks are released and other sessions can access the pages that the aborted transaction accessed.
static void abort_top_level();Aborts the outermost transaction within which control currently resides. If the current transaction is not nested, this function aborts the current transaction.
static os_transaction *begin(
transaction_type_enum t_type = update,
transaction_scope_enum t_scope = local
);
Begins a dynamic transaction. A pointer to an object representing the transaction is returned. The user is responsible for deleting this object after terminating the transaction. The os_int32 argument should be coded as either os_transaction::update or os_transaction::read_only, depending on the type of transaction desired. Unlike lexical transactions, which are started with a transaction macro (OS_BEGIN_TXN() or OS_BEGIN_NAMED_TXN()), dynamic transactions are not retried automatically when aborted because of deadlock. For information about the lexical-transaction macros, see OS_BEGIN_TXN(). The t_scope argument specifies whether a transaction is local (the default) or global. To start a global transaction in a single session, call os_transaction::begin() with the t_scope argument set to os_transaction::global. For information about local and global transactions, see Local and Global Transactions in Chapter 5 of the C++ API User Guide.
For multithreaded applications, calling os_transaction::begin() in one thread can affect other, concurrent threads. For applications that do not use the sessions facility, starting a transaction in one thread causes all other concurrent threads to enter the same transaction. For applications that use the sessions facility, starting a transaction in one thread causes all other concurrent threads in the calling thread's current session to enter the same transaction.
Applications that do not use the sessions facility must synchronize access to persistent data by all concurrent threads. In addition, such applications must synchronize threads before a transaction commit, abort, or checkpoint; that is, when one thread performs a commit, abort, or checkpoint, there must be no concurrent access to persistent data by any other threads.
In addition, such applications must synchronize threads before a transaction commit, abort, or checkpoint; that is, when one thread performs a commit, abort, or checkpoint, no concurrent access to persistent data by other threads in the same session is allowed.
static os_transaction *os_transaction::begin(
char *name,
transaction_type_enum t_type = update,
transaction_scope_enum t_scope = local
);
Like the first overloading, except that the new transaction has the specified name.
static void checkpoint();Invokes checkpoint on the current transaction.
static checkpoint(os_transaction*);Invokes checkpoint on the given transaction. Note that checkpoint is valid only for a top-level dynamic transaction. Attempts to checkpoint nested or stack transactions result in an exception's being thrown.
os_boolean os_transaction::checkpoint_in_progress();Returns 1 if a checkpoint is currently in progress. This function is for use in hook functions registered for invocation during transaction commit processing.
static void commit(os_transaction* = get_current());Commits the specified dynamic transaction. Unlike transactions started with a transaction statement, dynamic transactions are not retried automatically when aborted because of deadlock.
static os_transaction *get_current();Returns a pointer to the most deeply nested transaction in which control currently resides. The value is 0 if no transaction is in progress.
char *get_name() const;Returns the name of the specified transaction, as set by os_transaction::set_name(). It is the caller's responsibility to deallocate the string when it is no longer needed.
os_transaction *get_parent() const;Returns a pointer to the transaction within which the specified transaction is directly nested.
os_transaction_scope_enum get_scope() const;Returns os_transaction::local or os_transaction::global, depending on whether the current transaction is local or global.
os_transaction_type get_type() const;Returns os_transaction::read_only or os_transaction::update, depending on the one that is true of the current transaction.
os_boolean is_aborted() const;Returns nonzero if the specified dynamic transaction is aborted, and 0 otherwise. For a transaction newly created by os_transaction::begin(), 0 is returned.
os_boolean is_committed() const;Returns nonzero if the specified dynamic transaction is committed, and 0 otherwise. For a transaction newly created by os_transaction::begin(), 0 is returned.
static os_boolean is_lock_contention();Returns nonzero (true) if a Server involved in the specified transaction has experienced contention for some persistent memory that the calling application is using; otherwise, returns 0 (false). It also returns false if it is not called from within a transaction.
This function can be used in conjunction with multiversion concurrency control (MVCC) to help determine whether to start a new transaction to make available more up-to-date data. If your application has a database open for MVCC, and during the current transaction another application has write-locked a page read by your application, is_lock_contention() returns nonzero (true).
Calling this function outside a transaction signals err_trans.
This function is advisory only; it does not have to be called and you can ignore its return value without jeopardizing in any way the correctness of ObjectStore's behavior.
os_boolean is_prepared() const;Returns nonzero (true) if os_transaction::prepare_to_commit() was invoked in the current transaction; otherwise, returns 0 (false).
prepare_to_commit();Performs, in advance, the parts of transaction commit that can fail due to the inability to acquire a resource. If this method completes successfully, the actual transaction commit is virtually reduced to sending a commit message to the ObjectStore Server. All the modified data was sent to the Server during the invocation of the prepare_to_commit call. After the call to prepare_to_commit, the only ObjectStore operations that should occur are transaction commit or abort.
Some of the failures that can occur during the call to prepare_to_commit() are
The exception err_prepare_to_commit is signaled if
For information about the macros, see OS_BEGIN_TXN(). For information about begin(), see os_transaction::begin().
os_session *session_of() const;Returns the os_session object for the session in which the specified os_transaction* was retrieved.
This method can be used with os_session::set_current() to enable a thread to join the session associated with an os_transaction object. For example, if txn_ptr references an os_transaction object, then the statement
os_session::set_current(txn_ptr->session_of());enables the currently executing thread to access the object by setting the thread's current session to the session associated with txn_ptr.
void set_name(const char *new_name);Sets the name of the specified transaction. The function copies the string new_name.
os_boolean top_level() const;Returns nonzero if the specified transaction is nonnested; returns 0 otherwise.
For information about the macros, see OS_BEGIN_TXN(). For information about begin(), see os_transaction::begin().
Updated: 03/15/99 16:41:22