|
Participant in a transaction; may be a resource manager, a transactional
cache, or just a logging/monitoring object. Event sequence is approximately as follows:
join(participant)
( readyToVote voteForCommit commitTransaction ) | abortTransaction
An abortTransaction may occur at any point following join(), and
aborts the transaction.
Generally speaking, participants fall into a few broad categories:
Database connections Resource managers that write data to another participant, e.g. a
storage manager writing to a database connection Resource managers that manage their own storage transactions,
e.g. ZODB Database/Storage objects, a filesystem-based queue, etc. Objects which don't manage any transactional resources, but need to
know what's happening with a transaction, in order to log it.
Each kind of participant will typically use different messages to
achieve their goals. Resource managers that use other
participants for storage, for example, won't care much about
voteForCommit(), while a resource manager that manages direct storage
will care about voteForCommit() very deeply!
Resource managers that use other participants for storage, but
buffer writes to the other participant, will need to pay close
attention to the readyToVote() message. Specifically, they must
flush all pending writes to the participant that handles their
storage, and return False if there was anything to flush.
readyToVote() will be called repeatedly on all participants until
they all return True, at which point the transaction will initiate
the voteForCommit() phase.
By following this algorithm, any number of participants may be
chained together, such as a persistence manager that writes to an
XML document, which is persisted in a database table, which is
persisted in a disk file. The persistence manager, the XML
document, the database table, and the disk file would all be
participants, but only the disk file would actually use
voteForCommit() and commitTransaction() to handle a commit.
All of the other participants would flush pending updates during the
readyToVote() loop, guaranteeing that the disk file participant
would know about all the updates by the time voteForCommit() was
issued, regardless of the order in which the participants received
the messages.
|
Methods
|
|
abortTransaction
commitTransaction
finishTransaction
readyToVote
voteForCommit
|
|
|
abortTransaction
|
abortTransaction ( txnService )
This message can be received at any time, and means the
entire transaction must be rolled back. Transactional caches
might use this message to reset themselves.
|
|
|
commitTransaction
|
commitTransaction ( txnService )
This message follows vote_commit, if no participants vetoed
the commit. DB connections will probably issue COMMIT TRAN
here. Transactional caches might use this message to reset
themselves.
|
|
|
finishTransaction
|
finishTransaction ( txnService, committed )
The transaction is over, whether it aborted or committed.
|
|
|
readyToVote
|
readyToVote ( txnService )
Transaction commit is beginning; flush dirty objects and
enter write-through mode, if applicable. Return a true
value if nothing needed to be done, or a false value if
work needed to be done. DB connections will probably never
do anything here, and thus will just return a true value.
Object managers like Entity DMs will write their objects and
return false, or return true if they have nothing to write.
Note: participants must continue to accept writes until
voteForCommit() occurs, and must accept repeated writes
of the same objects!
|
|
|
voteForCommit
|
voteForCommit ( txnService )
Raise an exception if commit isn't possible. This will
mostly be used by resource managers that handle their own
storage, or the few DB connections that are capable of
multi-phase commit.
|
|