Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

We’re showing branches in this repository, but you can also compare across forks.

base: 7b7f52c4cb
...
compare: ba87955a32
  • 3 commits
  • 2 files changed
  • 0 commit comments
  • 2 contributors
Commits on Oct 22, 2012
Tokuhiro Matsuno tokuhirom Split document for users and developers. c011f19
Tokuhiro Matsuno tokuhirom docs enhancment 3390464
Commits on Feb 15, 2013
Atsushi Kobayashi Merge pull request #1 from tokuhirom/better-doc
Split document for users and developers.
ba87955
96 lib/DBIx/TransactionManager.pm
View
@@ -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
69 lib/DBIx/TransactionManager/Developers.pod
View
@@ -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.