agi.foundation

(agi.foundation.tracking-2024r3.jar)

Class Transaction

java.lang.Object

agi.foundation.Transaction

All Implemented Interfaces:

IDisposable, AutoCloseable

public final class Transaction
extends Object
implements IDisposable

A transaction within the software transactional memory (STM) system. All reads made in a transaction will see a consistent snapshot of the TransactionContext. A transaction will only successfully commit if no update it has made conflicts with any concurrent updates that have been committed since the transaction was started.

See Also:

Transactions topic

Constructor Summary

Constructors

Constructor and Description
Transaction(TransactionContext context) Begins a new transaction.

Method Summary

Modifier and Type	Method and Description
void	abort() Aborts this transactions.
void	addModification(TransactedObject modifiedObject, Object details) Adds a modification to this transaction.
void	commit() Commits this transaction so that its changes are visible to other transactions.
void	dispose() Disposes this transaction.
TransactionContext	getContext() Gets the transaction context in which this transaction operates.
boolean	getIsActive() Gets a value indicating whether or not this transaction is still active.
long	getNumber() Gets the number of this transaction.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface agi.foundation.compatibility.IDisposable

close

Constructor Detail

Transaction

public Transaction(TransactionContext context)

Begins a new transaction. Be sure to IDisposable.close(), Transaction.commit(), or Transaction.abort() this transaction as soon as you are done using it. Keeping transactions open for a long time will substantially increase the memory usage and slow the performance of the software transactional memory system. You should generally use TransactionContext.doTransactionally(agi.foundation.compatibility.Action1<agi.foundation.Transaction>) instead of constructing a transaction directly.

Parameters:

context - The context in which this transaction operates. The new transaction can only be used to access transacted values in this context.

Method Detail

dispose

public final void dispose()

Disposes this transaction. It is safe to call this method on a transaction that has already been committed or aborted. If it has not already been committed or aborted, it will be aborted.

Specified by:

dispose in interface IDisposable

getContext

public final TransactionContext getContext()

Gets the transaction context in which this transaction operates. This transaction can only be used to access transacted objects in this context.

getNumber

public final long getNumber()

Gets the number of this transaction. Multiple transactions may share a single number and the number of a transaction may change when it is committed.

getIsActive

public final boolean getIsActive()

Gets a value indicating whether or not this transaction is still active. A transaction is active from the time it is constructed until Transaction.commit(), Transaction.abort(), or IDisposable.close() is called on it.

commit

public final void commit()

Commits this transaction so that its changes are visible to other transactions. This method may throw TransactionConflictException if another transaction modifies one of the same values as this transaction and the other transaction commits first. Use TransactionContext.doTransactionally(agi.foundation.compatibility.Action1<agi.foundation.Transaction>) to automatically retry conflicting exceptions.

Throws:

TransactionConflictException - Raised when another transaction modifies one of the same values as this one and the other transaction commits first. It can also be raised when a method like TransactedProperty.ensureValue(agi.foundation.Transaction) has been called within this transaction and the value was changed by another transaction. Use TransactionContext.doTransactionally(agi.foundation.compatibility.Action1<agi.foundation.Transaction>) to automatically retry conflicting exceptions.

abort

public final void abort()

Aborts this transactions. Any changes made by this transaction will be discarded.

addModification

public final void addModification(TransactedObject modifiedObject,
                                  Object details)

Adds a modification to this transaction. This method is intended to be called within custom TransactedObject implementations.

Parameters:

modifiedObject - The modified object.

details - Details about the modification that will be passed to the modified object's TransactedObject.commit(agi.foundation.Transaction, java.lang.Object), TransactedObject.abort(agi.foundation.Transaction, java.lang.Object), TransactedObject.cleanup(java.lang.Object), and TransactedObject.validateModification(agi.foundation.Transaction, java.lang.Object) methods.