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

perl v5.32.1                                       2022-01-17                      UR::Context::Transaction(3pm)