os_transaction

The types os_int32 and os_boolean, used throughout this manual, are each defined as a signed 32-bit integer type. The type os_unsigned_int32 is defined as an unsigned 32-bit integer type.

All ObjectStore programs must include the header file <ostore/ostore.hh>.

os_transaction::abort()

static void abort(os_transaction* = get_current());

os_transaction::abort_only

• Read-only
• Protected against writes
• MVCC-opened

There are no write locks for any pages that are written during an abort-only transaction. This allows multiple concurrent abort-only writers to a database. However, there are read locks for all pages the client reads or writes. When used with MVCC-opened databases, the standard MVCC locks apply.

The client raises the exception err_commit_abort_only if an attempt is made to commit an abort-only transaction. If the top-level transaction is abort-only, both abort-only and update transactions can nest within it. Otherwise, the nesting rule described in os_transaction::begin() applies.

Note that an abort_only transaction does not automatically abort. You must specifically use the os_transaction::abort() function to abort the abort_only transaction, otherwise an exception is signaled.

You can use abort_top_level(), or for stack transactions use abort(), since you know exactly where the transaction ends. For example:

OS_BEGIN_TXN(txn, 0, os_transaction::abort_only) {
      ...
      os_transaction::abort();
} OS_END_TXN(txn);

static void abort_top_level();

os_transaction::begin()

static os_transaction *begin(
      transaction_type_enum t_type = update,
      transaction_scope_enum t_scope = local);

To support multithreaded applications, dynamic transactions can be either local or global. By default, dynamic transactions are local. You start a global transaction by passing the enumerator os_transaction::global as the second argument to os_transaction::begin().

The two kinds of transactions have the following characteristics:

• Local transaction: a thread enters a local transaction by calling os_transaction::begin() or OS_BEGIN_TXN(). When one thread enters a local transaction, this has no effect on whether other threads are within a transaction.
• Global transaction: a thread enters a global transaction when it calls os_transaction::begin() or when another thread of the same process calls os_transaction::begin(). When one thread enters a global transaction by calling os_transaction::begin(), all other threads automatically enter the same transaction.

Global transactions allow for a somewhat higher degree of concurrency. After one thread enters the ObjectStore run time, if another thread attempts to enter the ObjectStore run time, it is blocked until control in the first thread exits from the run time. Although two threads cannot be in the ObjectStore run time at the same time, there can be some interleaving of operations of different threads within a transaction.

If you use global transactions, be sure to synchronize the threads so that no thread attempts to access persistent data while another thread is committing or aborting. Place a barrier before the end of the transaction so that all participating threads complete work on persistent data before the end-of-transaction operation is allowed to proceed.

You cannot nest a local transaction within a global transaction, nor can you nest a global transaction within a local one. This table specifies how two transactions can

	Thread A tries global txn	Thread A tries local txn	Thread B tries global txn	Thread B tries local txn
Thread A runs global txn	OK, nested global txn	err_trans_wrong_type is signaled	OK, nested global txn	err_trans_wrong_type is signaled
Thread A runs local txn	err_trans_wrong_type is signaled	OK, nested local txn	OK, but block until A completes	OK, but block until A completes

interact:

static os_transaction *os_transaction::begin(
      transaction_type_enum t_type = update,
      transaction_scope_enum t_scope = local,
      os_transaction *parent

);

static os_transaction *os_transaction::begin(
      char *name,
      transaction_type_enum t_type = update,
      transaction_scope_enum t_scope = local);

static os_transaction *os_transaction::begin(
      char *name,
      transaction_type_enum t_type = update,
      transaction_scope_enum t_scope = local,
      os_transaction *parent

);

os_transaction::checkpoint()

static void checkpoint(); 

static checkpoint(os_transaction*);

os_transaction::checkpoint_in_progress();

os_boolean os_transaction::checkpoint_in_progress();

os_transaction::commit()

static void commit(os_transaction* = get_current());

os_transaction::exception_status

tix_exception *exception_status;

Raising an exception will cause a transaction to abort if the exception is handled outside the transaction's dynamic scope, or if there is no handler for the exception.

os_transaction::get_current()

static os_transaction *get_current();

os_transaction::get_max_retries()

static os_int32 get_max_retries();

os_transaction::get_name()

char *get_name() const;

os_transaction::get_parent()

os_transaction *get_parent() const;

os_transaction::get_scope()

os_transaction_scope_enum get_scope() const;

os_transaction::get_type()

os_transaction_type get_type() const;

os_transaction::is_aborted()

os_boolean is_aborted() const;

os_transaction::is_committed()

os_boolean is_committed() const;

os_transaction::is_prepare_to_commit_completed()

is_prepare_to_commit_completed();

os_transaction::is_prepare_to_commit_invoked()

is_prepare_to_commit_invoked();

os_transaction::prepare_to_commit()

prepare_to_commit();

Some of the failures that can occur during the call to prepare_to_commit() are

• Client's being selected as a deadlock victim by the Server. The exception err_deadlock would be raised.
• Server's running out of disk space while growing a segment or writing to the log file. The exception err_server_full would be raised.
• The exception err_broken_server_connection can occur if the Server fails during commit.

The exception err_prepare_to_commit is generated if

• Access to persistent data after a call to prepare_to_commit.
• Any objectstore operation other than commit or abort is attempted after a call to prepare_to_commit.
• The method is invoked within a nested transaction.

os_transaction::read_only

os_transaction::set_max_retries()

static void set_max_retries(os_int32);

os_transaction::set_name()

void set_name(const char *new_name);

os_transaction::top_level()

os_boolean top_level() const;

os_transaction::update

Updated: 03/31/98 17:25:09