Skip to content

Comparing changes

Choose two branches to see what’s changed or to start a new pull request. If you need to, you can also compare across forks.

Open a pull request

Create a new pull request by comparing changes across two branches. If you need to, you can also compare across forks.
...
  • 3 commits
  • 2 files changed
  • 0 commit comments
  • 2 contributors
Commits on Oct 22, 2012
@tokuhirom tokuhirom Split document for users and developers. c011f19
@tokuhirom tokuhirom docs enhancment 3390464
Commits on Feb 15, 2013
@nekokak Merge pull request #1 from tokuhirom/better-doc
Split document for users and developers.
ba87955
Showing with 107 additions and 58 deletions.
  1. +38 −58 lib/DBIx/TransactionManager.pm
  2. +69 −0 lib/DBIx/TransactionManager/Developers.pod
View
96 lib/DBIx/TransactionManager.pm
@@ -93,13 +93,13 @@ sub new {
}
sub rollback {
- return if $_[0]->[0];
+ return if $_[0]->[0]; # do not run twice.
$_[0]->[1]->txn_rollback;
$_[0]->[0] = 1;
}
sub commit {
- return if $_[0]->[0];
+ return if $_[0]->[0]; # do not run twice.
$_[0]->[1]->txn_commit;
$_[0]->[0] = 1;
}
@@ -122,37 +122,28 @@ __END__
=head1 NAME
-DBIx::TransactionManager - transaction handling for database.
+DBIx::TransactionManager - Transaction handling for database.
=head1 SYNOPSIS
-basic usage:
-
- use DBI;
- use DBIx::TransactionManager;
- my $dbh = DBI->connect('dbi:SQLite:');
- my $tm = DBIx::TransactionManager->new($dbh);
-
- $tm->txn_begin;
-
- $dbh->do("insert into foo (id, var) values (1,'baz')");
-
- $tm->txn_commit;
-
-scope_gurad usage:
+RAII style transaction management:
use DBI;
use DBIx::TransactionManager;
my $dbh = DBI->connect('dbi:SQLite:');
my $tm = DBIx::TransactionManager->new($dbh);
+ # create transaction object
my $txn = $tm->txn_scope;
+ # execute query
$dbh->do("insert into foo (id, var) values (1,'baz')");
+ # And you can do multiple database operations here
+ # and commit it.
$txn->commit;
-nested transaction usage:
+Nested transaction usage:
use DBI;
use DBIx::TransactionManager;
@@ -178,71 +169,60 @@ nested transaction usage:
=head1 DESCRIPTION
DBIx::TransactionManager is a simple transaction manager.
-like L<DBIx::Class::Storage::TxnScopeGuard>.
+like L<DBIx::Class::Storage::TxnScopeGuard>.
-=head1 METHODS
+This module provides two futures.
-=head2 my $tm = DBIx::TransactionManager->new($dbh)
+=over 4
-get DBIx::TransactionManager's instance object.
-$dbh parameter must be required.
+=item RAII based transaction management
-=head2 my $txn = $tm->txn_scope(%args)
+=item Nested transaction management
-get DBIx::TransactionManager::ScopeGuard's instance object.
-You may pass an optional argument to %args, to tell the scope guard
-where the scope was generated, like so:
+=back
- sub mymethod {
- my $self = shift;
- my $txn = $tm->txn_scope( caller => [ caller() ] );
- }
+If you are writing of DBIx::* or O/R Mapper, see L<DBIx::TransactionManager::Developers>.
- $self->mymethod();
-
-This will allow the guard object to report the caller's location
-from the perspective of C<mymethod()>, not where C<txn_scope()> was
-called.
+=head1 METHODS
-see L</DBIx::TransactionManager::ScopeGuard's METHODS>
+=over 4
-=head2 $tm->txn_begin(%args)
+=item my $tm = DBIx::TransactionManager->new($dbh)
-Start the transaction.
+Creating an instance of this class.
+C<$dbh> is required.
-C<txn_begin> may optionally take a 'caller' argument. This will allow you to
-provide caller information which will be used in C<in_transaction>. For example
-if you have a wrapper function that calls C<txn_begin>, you may want to
-let the user think that the caller was one stack above your wrapper.
+=item my $txn = $tm->txn_scope(%args)
- # use __my__ caller!
- $tm->txn_begin( caller => [ caller(0) ] );
+Get DBIx::TransactionManager::ScopeGuard's instance object.
+Options for this method is only for module creators, see L<DBIx::TransactionManager::Developers>.
-=head2 $tm->txn_rollback
+=back
-Rollback the transaction.
+=head1 DBIx::TransactionManager::ScopeGuard's METHODS
+
+=over 4
-=head2 $tm->txn_commit
+=item $txn->commit()
Commit the transaction.
-=head2 $tm->in_transaction
+If the C<$tm> is in a nested transaction, TransactionManager doesn't do COMMIT at here. TM just poped transaction stack and do nothing.
-Returns true if $txn is currently in a middle of a transaction. While normally
-you only need to use this value as a boolean, it actually returns a hashref
-consisting of 'caller' and 'pid' element. This will tell you exactly where
-the currently valid transaction started.
+=item $txn->rollback()
-=head1 DBIx::TransactionManager::ScopeGuard's METHODS
+Rollback the transaction.
-=head2 $txn->commit
+If the C<$tm> is in a nested transaction, TransactionManager doesn't do ROLLBACK at here. TM just poped transaction stack and do nothing.
-Commit the transaction.
+=back
-=head2 $txn->rollback
+=head1 DBIx::TransactionManager and other transaction managers
-Rollback the transaction.
+You B<cannot> use other transaction manager and DBIx::TransactionManager at once.
+
+If you are using O/R mapper, you should use that's transaction management feature.
=head1 AUTHOR
View
69 lib/DBIx/TransactionManager/Developers.pod
@@ -0,0 +1,69 @@
+=head1 NAME
+
+DBIx::TransactionManager::Developers - docs for developers
+
+=head1 DESCRIPTION
+
+This document describes a document for O/R mapper writer and/or DBIx::* writer.
+
+=head1 MORE DOCUMETNS for DBIx::TransactionManager class
+
+=over 4
+
+=item my $txn = $tm->txn_scope(%args)
+
+Create a new DBIx::TransactionManager::ScopeGuard's instance object.
+
+You can pass an optional argument to C<%args>, to tell the scope guard
+where the scope was generated, like so:
+
+ package Foo;
+ use Moose;
+ sub mymethod {
+ my $self = shift;
+ my $txn = $tm->txn_scope( caller => [ caller() ] );
+ return $txn;
+ }
+
+ package main;
+ my $obj = Foo->new();
+ my $txn = $obj->mymethod();
+
+This will allow the guard object to report the caller's location
+from the perspective of C<mymethod()>, not where C<txn_scope()> was
+called.
+
+see L</DBIx::TransactionManager::ScopeGuard's METHODS>
+
+=item $tm->txn_begin(%args)
+
+Start the transaction.
+
+C<txn_begin> may optionally take a 'caller' argument. This will allow you to
+provide caller information which will be used in C<in_transaction>. For example
+if you have a wrapper function that calls C<txn_begin>, you may want to
+let the user think that the caller was one stack above your wrapper.
+
+ # use __my__ caller!
+ $tm->txn_begin( caller => [ caller(0) ] );
+
+=item $tm->txn_commit()
+
+Commit the current transaction.
+
+If the C<$dbh> is in a nested transaction, TransactionManager doesn't do COMMIT at here. TM just poped transaction stack and do nothing.
+
+=item $tm->txn_rollback()
+
+Rollback the current transaction.
+
+If the C<$dbh> is in a nested transaction, TransactionManager doesn't do ROLLBACK at here. TM just poped transaction stack and do nothing.
+
+=item $tm->in_transaction() : Bool
+
+Returns true if $txn is currently in a middle of a transaction. While normally
+you only need to use this value as a boolean, it actually returns a hashref
+consisting of 'caller' and 'pid' element. This will tell you exactly where
+the currently valid transaction started.
+
+=back

No commit comments for this range

Something went wrong with that request. Please try again.