Skip to content

Commit f8ee9eb

Browse files
committed
Iterate the docs of ActiveRecord::Transaction
1 parent 9ccbab1 commit f8ee9eb

File tree

1 file changed

+25
-11
lines changed

1 file changed

+25
-11
lines changed

activerecord/lib/active_record/transaction.rb

Lines changed: 25 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -5,16 +5,29 @@
55
module ActiveRecord
66
# Class specifies the interface to interact with the current transaction state.
77
#
8-
# It can either map to an actual transaction or represent the abscence of a transaction.
8+
# It can either map to an actual transaction/savepoint, or represent the
9+
# abscence of a transaction.
910
#
1011
# == State
1112
#
12-
# You can check whether a transaction is open with the +open?+ or +closed?+ methods
13+
# We say that a transaction is _finalized_ when it wraps a real transaction
14+
# that has been either committed or rolled back.
15+
#
16+
# A transaction is _open_ if it wraps a real transaction that is not finalized.
17+
#
18+
# On the other hand, a transaction is _closed_ when it is not open. That is,
19+
# when it represents absence of transaction, or it wraps a real but finalized
20+
# one.
21+
#
22+
# You can check whether a transaction is open or closed with the +open?+ and
23+
# +closed?+ predicates:
1324
#
1425
# if Article.current_transaction.open?
15-
# # We are inside a transaction
26+
# # We are inside a real and not finalized transaction.
1627
# end
1728
#
29+
# Closed transactions are `blank?` too.
30+
#
1831
# == Callbacks
1932
#
2033
# After updating the database state, you may sometimes need to perform some extra work, or reflect these
@@ -60,16 +73,15 @@ def initialize(internal_transaction) # :nodoc:
6073

6174
# Registers a block to be called after the transaction is fully committed.
6275
#
63-
# If there is no currently open transactions, the block is called immediately.
76+
# If there is no currently open transactions, the block is called
77+
# immediately, unless the transaction is finalized, in which case attempting
78+
# to register the callback raises ActiveRecord::ActiveRecordError.
6479
#
6580
# If the transaction has a parent transaction, the callback is transferred to
6681
# the parent when the current transaction commits, or dropped when the current transaction
6782
# is rolled back. This operation is repeated until the outermost transaction is reached.
6883
#
6984
# If the callback raises an error, the transaction remains committed.
70-
#
71-
# If the transaction is already finalized, attempting to register a callback
72-
# will raise ActiveRecord::ActiveRecordError
7385
def after_commit(&block)
7486
if @internal_transaction.nil?
7587
yield
@@ -80,7 +92,9 @@ def after_commit(&block)
8092

8193
# Registers a block to be called after the transaction is rolled back.
8294
#
83-
# If there is no currently open transactions, the block is never called.
95+
# If there is no currently open transactions, the block is not called. But
96+
# if the transaction is finalized, attempting to register the callback
97+
# raises ActiveRecord::ActiveRecordError.
8498
#
8599
# If the transaction is successfully committed but has a parent
86100
# transaction, the callback is automatically added to the parent transaction.
@@ -89,17 +103,17 @@ def after_commit(&block)
89103
# the block is never called.
90104
#
91105
# If the transaction is already finalized, attempting to register a callback
92-
# will raise ActiveRecord::ActiveRecordError
106+
# will raise ActiveRecord::ActiveRecordError.
93107
def after_rollback(&block)
94108
@internal_transaction&.after_rollback(&block)
95109
end
96110

97-
# Returns true if the transaction exists and isn't finalized yet
111+
# Returns true if the transaction exists and isn't finalized yet.
98112
def open?
99113
!closed?
100114
end
101115

102-
# Returns true if the transaction doesn't exists or is finalized (committed or rolled back)
116+
# Returns true if the transaction doesn't exists or is finalized.
103117
def closed?
104118
@internal_transaction.nil? || @internal_transaction.state.finalized?
105119
end

0 commit comments

Comments
 (0)