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().

METHODS

commit

  $t->commit();

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

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.

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

execute

  $retval = UR::Context::Transaction->execute($coderef);

Executes the coderef with no arguments, within an eval and a software transaction. If the coderef returns true, the transaction is committed. If it returns false, the transaction is rolled back. Finally the coderef's return value is returned to the caller.

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

execute_and_rollback

  UR::Context::Transaction->execute_and_rollback($coderef);

Executes the coderef with no arguments, within an eval and a software transaction. Reguardless of the return value of the coderef, the transaction will be rolled back.