agi.foundation

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

Class TransactionContext

java.lang.Object

agi.foundation.TransactionContext

public class TransactionContext
extends Object

A context for a group of transactions in the software transactional memory (STM) system. Different contexts can be thought of as separate in-memory databases. A TransactedProperty exists within exactly one context and can only be read or modified by a Transaction within the same context.

The software transactional memory (STM) implementation uses multiversion concurrency control to achieve snapshot isolation for in-memory properties and collections. Conceptually, a snapshot of the entire TransactionContext is taken when a new Transaction is constructed. All reads of transacted properties or collections will see the snapshot values, even if the values are changed by another transaction in the meantime. When transacted properties or collections are modified within a collection, those modifications are not visible to any other transaction until the first transaction is committed with a call to Transaction.commit(). If another transaction has modified the same properties or collections, the committing transaction will raise a TransactionConflictException and the transaction must be retried. Read-only transactions will never block, nor will they conflict with other transactions.

Constructor Summary

Constructors

Constructor and Description
TransactionContext() Initializes a new instance.

Method Summary

Modifier and Type	Method and Description
void	addCommitted(EventHandler<TransactionCommittedEventArgs> value) Adds a handler for an event that is raised each time that a transaction is committed in this context.
void	doTransactionally(Action1<Transaction> callback) Executes the provided callback within a transaction, and automatically commits the transaction when the callback returns.
void	removeCommitted(EventHandler<TransactionCommittedEventArgs> value) Removes a handler for an event that is raised each time that a transaction is committed in this context.
<TResult> TResult	selectTransactionally(TransactionalSelectCallback<TResult> selector) Executes the provided callback within a transaction, and automatically commits the transaction when the callback returns.

Methods inherited from class java.lang.Object

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

Constructor Detail

TransactionContext

public TransactionContext()

Initializes a new instance.

Method Detail

addCommitted

public final void addCommitted(EventHandler<TransactionCommittedEventArgs> value)

Adds a handler for an event that is raised each time that a transaction is committed in this context.

This event is raised in the thread that committed the transaction and is raised inside the commit lock. This means that it is only raised by one thread at a time and it is raised once per transaction in the order in which the transactions are committed.

When this event is raised, all values modified by the transaction have already been committed and will be visible to a transaction started within an event handler. Attempting to commit another transaction within a handler hooked up to this event will result in an IllegalStateException, however. If additional changes are necessary, use the ChainedTransaction (get) and do not manually commit it. It will be automatically committed after all handlers for this event have finished executing. It is guaranteed that the chained transaction will commit immediately after all event handlers return, before any other transaction can commit, and that it will not raise a TransactionConflictException.

It is very important that subscribers to this event execute very quickly in order to avoid blocking the entire transaction system.

Parameters:

value - The handler.

removeCommitted

public final void removeCommitted(EventHandler<TransactionCommittedEventArgs> value)

Removes a handler for an event that is raised each time that a transaction is committed in this context.

This event is raised in the thread that committed the transaction and is raised inside the commit lock. This means that it is only raised by one thread at a time and it is raised once per transaction in the order in which the transactions are committed.

When this event is raised, all values modified by the transaction have already been committed and will be visible to a transaction started within an event handler. Attempting to commit another transaction within a handler hooked up to this event will result in an IllegalStateException, however. If additional changes are necessary, use the ChainedTransaction (get) and do not manually commit it. It will be automatically committed after all handlers for this event have finished executing. It is guaranteed that the chained transaction will commit immediately after all event handlers return, before any other transaction can commit, and that it will not raise a TransactionConflictException.

It is very important that subscribers to this event execute very quickly in order to avoid blocking the entire transaction system.

Parameters:

value - The handler.

doTransactionally

public final void doTransactionally(@Nonnull
                                    Action1<Transaction> callback)

Executes the provided callback within a transaction, and automatically commits the transaction when the callback returns. If the transaction conflicts (it raises a TransactionConflictException), the callback is executed again with a new transaction. This process continues until the transaction commits successfully.

Parameters:

callback - The callback to execute transactionally.

selectTransactionally

public final <TResult> TResult selectTransactionally(@Nonnull
                                                     TransactionalSelectCallback<TResult> selector)

Executes the provided callback within a transaction, and automatically commits the transaction when the callback returns. If the transaction conflicts (it raises a TransactionConflictException), the callback is executed again with a new transaction. This process continues until the transaction commits successfully. When the transaction commits successfully, the value returned by the provided callback is returned by this method.

Type Parameters:

TResult - The return type of the callback.

Parameters:

selector - The callback to execute transactionally.

Returns:

The return value of the callback when executed.