.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "UR::Context::Transaction 3pm"
.TH UR::Context::Transaction 3pm "2019-01-02" "perl v5.28.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
UR::Context::Transaction \- API for software transactions
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&  my $o = Some::Obj\->create(foo => 1);
\&  print "o\*(Aqs foo is ",$o\->foo,"\en";  # prints 1
\&
\&  my $t = UR::Context::Transaction\->begin();
\&
\&  $o\->foo(4);
\&
\&  print "In transaction, o\*(Aqs foo is ",$o\->foo,"\en";  # prints 4
\&
\&  if (&should_we_commit()) {
\&      $t\->commit();
\&      print "Transaction committed, o\*(Aqs foo is ",$o\->foo,"\en";  # prints 4
\&
\&  } else {
\&      $t\->rollback();
\&      print "Transaction rollback, o\*(Aqs foo is ",$o\->foo,"\en";  # prints 1
\&  }
.Ve
.SH "DESCRIPTION"
.IX Header "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.
.SH "INHERITANCE"
.IX Header "INHERITANCE"
UR::Context::Transaction is a subclass of UR::Context
.SH "CONSTRUCTOR"
.IX Header "CONSTRUCTOR"
.IP "begin" 4
.IX Item "begin"
.Vb 1
\&  $t = UR::Context::Transaction\->begin();
.Ve
.Sp
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 \fBbegin()\fR.
.Sp
.Vb 1
\&  $t = UR::Context::Transaction\->begin(commit_validator => sub { ... });
.Ve
.Sp
A validation function may be assigned with the \f(CW\*(C`commit_validator\*(C'\fR property.
When the transaction is committed, this function is called.  The commit
proceeds if this function returns a true value.  The default function,
\&\f(CW\*(C`changes_can_be_saved\*(C'\fR requires that all objects changed within the
transaction be valid, ie. that \f(CW\*(C`$obj\-\*(C'\fR_\|_errors_\|_()> returns an empty list.
The validation function is passed one argument: the transaction object
being committed.
.SH "METHODS"
.IX Header "METHODS"
.IP "commit" 4
.IX Item "commit"
.Vb 1
\&  $t\->commit();
.Ve
.Sp
Causes all objects with changes to save those changes back to the underlying
context.
.Sp
If the validation function (specified with the \f(CW\*(C`commit_validator\*(C'\fR param when
the transaction was created with \f(CW\*(C`begin()\*(C'\fR) returns false, the changes are
not committed to the encompassing context, \f(CW\*(C`commit()\*(C'\fR returns false and this
transaction remains in effect.
.Sp
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'.
.IP "rollback" 4
.IX Item "rollback"
.Vb 1
\&  $t\->rollback();
.Ve
.Sp
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.
.Sp
After \f(CW\*(C`rollback()\*(C'\fR, this transaction becomes invalid, and the object will become
a UR::DeletedRef.
.IP "delete" 4
.IX Item "delete"
.Vb 1
\&  $t\->delete();
.Ve
.Sp
\&\fBdelete()\fR is a synomym for rollback
.IP "has_changes" 4
.IX Item "has_changes"
.Vb 1
\&  $bool = $t\->has_changes();
.Ve
.Sp
Returns true if any UR-based objects have changes within the transaction.
.IP "get_changes" 4
.IX Item "get_changes"
.Vb 1
\&  @changes = $t\->get_changes();
.Ve
.Sp
Return a list or UR::Change objects representing changes within the transaction.
.SH "CLASS METHODS"
.IX Header "CLASS METHODS"
.IP "eval" 4
.IX Item "eval"
.Vb 1
\&  UR::Context::Transaction::eval BLOCK
.Ve
.Sp
Executes the \s-1BLOCK\s0 (with no arguments) wrapped by a software transaction and a
CORE::eval.  If the \s-1BLOCK\s0 dies then the exception is caught and the software
transaction is rolled back.
.IP "do" 4
.IX Item "do"
.Vb 1
\&  UR::Context::Transaction::do BLOCK
.Ve
.Sp
Executes the \s-1BLOCK\s0 (with no arguments) wrapped by a software transaction and a
CORE::eval.  If the \s-1BLOCK\s0 returns a true value and does not die then the
software transaction is committed.  If the \s-1BLOCK\s0 returns false or dies then the
software transaction is rolled back.
.Sp
If the \s-1BLOCK\s0 throws an exception, it will be caught, the software transaction
rolled back, and the exception will be re-thrown with \fBdie()\fR.
.SH "EXPORTS"
.IX Header "EXPORTS"
This module can export constants that match the valid values of the \f(CW\*(C`state\*(C'\fR
property: \s-1TRANSACTION_STATE_OPEN\s0 and \s-1TRANSACTION_STATE_COMMITTED\s0
.SH "SEE ALSO"
.IX Header "SEE ALSO"
UR::Context