lib/DBIx/Class/Storage/TxnScopeGuard.pm

   1 package DBIx::Class::Storage::TxnScopeGuard;
   2
   3 use strict;
   4 use warnings;
   5 use Scalar::Util qw(weaken blessed refaddr);
   6 use DBIx::Class;
   7 use DBIx::Class::_Util qw(is_exception detected_reinvoked_destructor);
   8 use DBIx::Class::Carp;
   9 use namespace::clean;
  10
  11 sub new {
  12   my ($class, $storage) = @_;
  13
  14   my $guard = {
  15     inactivated => 0,
  16     storage => $storage,
  17   };
  18
  19   # we are starting with an already set $@ - in order for things to work we need to
  20   # be able to recognize it upon destruction - store its weakref
  21   # recording it before doing the txn_begin stuff
  22   #
  23   # FIXME FRAGILE - any eval that fails but *does not* rethrow between here
  24   # and the unwind will trample over $@ and invalidate the entire mechanism
  25   # There got to be a saner way of doing this...
  26   #
  27   # Deliberately *NOT* using is_exception - if someone left a misbehaving
  28   # antipattern value in $@, it's not our business to whine about it
  29   if( defined $@ and length $@ ) {
  30     weaken(
  31       $guard->{existing_exception_ref} = (length ref $@) ? $@ : \$@
  32     );
  33   }
  34
  35   $storage->txn_begin;
  36
  37   weaken( $guard->{dbh} = $storage->_dbh );
  38
  39   bless $guard, ref $class || $class;
  40
  41   $guard;
  42 }
  43
  44 sub commit {
  45   my $self = shift;
  46
  47   $self->{storage}->throw_exception("Refusing to execute multiple commits on scope guard $self")
  48     if $self->{inactivated};
  49
  50   # FIXME - this assumption may be premature: a commit may fail and a rollback
  51   # *still* be necessary. Currently I am not aware of such scenarious, but I
  52   # also know the deferred constraint handling is *severely* undertested.
  53   # Making the change of "fire txn and never come back to this" in order to
  54   # address RT#107159, but this *MUST* be reevaluated later.
  55   $self->{inactivated} = 1;
  56   $self->{storage}->txn_commit;
  57 }
  58
  59 sub DESTROY {
  60   return if &detected_reinvoked_destructor;
  61
  62   return if $_[0]->{inactivated};
  63
  64
  65   # grab it before we've done volatile stuff below
  66   my $current_exception = (
  67     is_exception $@
  68       and
  69     (
  70       ! defined $_[0]->{existing_exception_ref}
  71         or
  72       refaddr( (length ref $@) ? $@ : \$@ ) != refaddr($_[0]->{existing_exception_ref})
  73     )
  74   )
  75     ? $@
  76     : undef
  77   ;
  78
  79
  80   # if our dbh is not ours anymore, the $dbh weakref will go undef
  81   $_[0]->{storage}->_verify_pid unless DBIx::Class::_ENV_::BROKEN_FORK;
  82   return unless defined $_[0]->{dbh};
  83
  84
  85   carp 'A DBIx::Class::Storage::TxnScopeGuard went out of scope without explicit commit or error. Rolling back'
  86     unless defined $current_exception;
  87
  88
  89   if (
  90     my $rollback_exception = $_[0]->{storage}->__delicate_rollback(
  91       defined $current_exception
  92         ? \$current_exception
  93         : ()
  94     )
  95       and
  96     ! defined $current_exception
  97   ) {
  98     carp (join ' ',
  99       "********************* ROLLBACK FAILED!!! ********************",
 100       "\nA rollback operation failed after the guard went out of scope.",
 101       'This is potentially a disastrous situation, check your data for',
 102       "consistency: $rollback_exception"
 103     );
 104   }
 105
 106   $@ = $current_exception
 107     if DBIx::Class::_ENV_::UNSTABLE_DOLLARAT;
 108
 109   # Dummy NEXTSTATE ensuring the all temporaries on the stack are garbage
 110   # collected before leaving this scope. Depending on the code above, this
 111   # may very well be just a preventive measure guarding future modifications
 112   undef;
 113 }
 114
 115 1;
 116
 117 __END__
 118
 119 =head1 NAME
 120
 121 DBIx::Class::Storage::TxnScopeGuard - Scope-based transaction handling
 122
 123 =head1 SYNOPSIS
 124
 125  sub foo {
 126    my ($self, $schema) = @_;
 127
 128    my $guard = $schema->txn_scope_guard;
 129
 130    # Multiple database operations here
 131
 132    $guard->commit;
 133  }
 134
 135 =head1 DESCRIPTION
 136
 137 An object that behaves much like L<Scope::Guard>, but hardcoded to do the
 138 right thing with transactions in DBIx::Class.
 139
 140 =head1 METHODS
 141
 142 =head2 new
 143
 144 Creating an instance of this class will start a new transaction (by
 145 implicitly calling L<DBIx::Class::Storage/txn_begin>. Expects a
 146 L<DBIx::Class::Storage> object as its only argument.
 147
 148 =head2 commit
 149
 150 Commit the transaction, and stop guarding the scope. If this method is not
 151 called and this object goes out of scope (e.g. an exception is thrown) then
 152 the transaction is rolled back, via L<DBIx::Class::Storage/txn_rollback>
 153
 154 =cut
 155
 156 =head1 SEE ALSO
 157
 158 L<DBIx::Class::Schema/txn_scope_guard>.
 159
 160 L<Scope::Guard> by chocolateboy (inspiration for this module)
 161
 162 =head1 FURTHER QUESTIONS?
 163
 164 Check the list of L<additional DBIC resources|DBIx::Class/GETTING HELP/SUPPORT>.
 165
 166 =head1 COPYRIGHT AND LICENSE
 167
 168 This module is free software L<copyright|DBIx::Class/COPYRIGHT AND LICENSE>
 169 by the L<DBIx::Class (DBIC) authors|DBIx::Class/AUTHORS>. You can
 170 redistribute it and/or modify it under the same terms as the
 171 L<DBIx::Class library|DBIx::Class/COPYRIGHT AND LICENSE>.