NAME

UR::Context::Transaction - API for software transactions

SYNOPSIS

my $o = Some::Obj->create(foo => 1);
print "o's foo is ",$o->foo,"\n";  # prints 1

my $t = UR::Context::Transaction->begin();

$o->foo(4);

print "In transaction, o's foo is ",$o->foo,"\n";  # prints 4

if (&should_we_commit()) {
    $t->commit();
    print "Transaction committed, o's foo is ",$o->foo,"\n";  # prints 4

} else {
    $t->rollback();
    print "Transaction rollback, o's foo is ",$o->foo,"\n";  # prints 1
}

DESCRIPTION

UR::Context::Transaction instances represent in-memory transactions as a diff of the contents of the object cache in the Process context. Transactions are nestable. Their instances exist in the object cache and are subject to the same scoping rules as other UR-based objects, meaning that they do not disappear mearly because the lexical variable they're assigned to goes out of scope. They must be explicitly disposed of via the commit or rollback methods.

INHERITANCE

UR::Context::Transaction is a subclass of UR::Context

CONSTRUCTOR

begin

$t = UR::Context::Transaction->begin();

Creates a new software transaction context to track changes to UR-based objects. As all activity to objects occurs in some kind of transaction context, the newly created transaction exists within whatever context was current before the call to begin().

$t = UR::Context::Transaction->begin(commit_validator => sub { ... });

A validation function may be assigned with the commit_validator property. When the transaction is committed, this function is called. The commit proceeds if this function returns a true value. The default function, changes_can_be_saved requires that all objects changed within the transaction be valid, ie. that $obj-__errors__()> returns an empty list. The validation function is passed one argument: the transaction object being committed.

METHODS

commit

$t->commit();

Causes all objects with changes to save those changes back to the underlying context.

If the validation function (specified with the commit_validator param when the transaction was created with begin()) returns false, the changes are not committed to the encompassing context, commit() returns false and this transaction remains in effect.

Returns true if all the transaction's changes are committed to the encompassing Context. This transaction object then becomes invalid, and its state will be 'committed'.

rollback

$t->rollback();

Causes all objects with changes to have those changes reverted to their state when the transaction began. Classes with properties whose meta-property is_transactional => 0 are not tracked within a transaction and will not be reverted.

After rollback(), this transaction becomes invalid, and the object will become a UR::DeletedRef.

delete

$t->delete();

delete() is a synomym for rollback

has_changes

$bool = $t->has_changes();

Returns true if any UR-based objects have changes within the transaction.

get_changes

@changes = $t->get_changes();

Return a list or UR::Change objects representing changes within the transaction.

CLASS METHODS

eval

UR::Context::Transaction::eval BLOCK

Executes the BLOCK (with no arguments) wrapped by a software transaction and a CORE::eval. If the BLOCK dies then the exception is caught and the software transaction is rolled back.

do

UR::Context::Transaction::do BLOCK

Executes the BLOCK (with no arguments) wrapped by a software transaction and a CORE::eval. If the BLOCK returns a true value and does not die then the software transaction is committed. If the BLOCK returns false or dies then the software transaction is rolled back.

If the BLOCK throws an exception, it will be caught, the software transaction rolled back, and the exception will be re-thrown with die().

EXPORTS

This module can export constants that match the valid values of the state property: TRANSACTION_STATE_OPEN and TRANSACTION_STATE_COMMITTED

SEE ALSO

UR::Context