Overview

This page describes the classes involved in handling distributed transactions in the C++ broker. The store plugins are not described; only the classes in the broker proper are described here. The store plugin modules should have separate documentation.

Much of the code is common for local/one-phase transactions; however, this document is primarily concerned with distributed/two-phase transactions.

The basic approach taken in the C++ broker is that, once a transaction is begun, enqueue/dequeue commands received from a client are recorded in a list of operations associated with the transaction but not actually carried out until the transaction is committed (one phase) or prepared (two-phase).

Classes

These classes are all in the qpid::broker namespace.

Record-Keeping Classes

• DtxManager. Maps xid to a DtxWorkRecord.
• DtxWorkRecord. Refers to work to be done under the transaction using a vector of DtxBuffer objects.

  How could this have multiple DtxBuffer objects associated?  When dtx-start is called with the join flag set, the subsequent work is added to a set of operations previously performed (perhaps on a different session). [Gordon]

• DtxBuffer. Per-xid list of operations requested under the transaction. The operations are derived from TxOp. [As above, each buffer contains the operations between one pair fo start/end calls. Where end has the suspend flag set and a subsequent start has the join flag set, a new buffer will be populated and associated with the xid - Gordon]
• TxPublish. Publish (enqueue) operation record. Has a message and list of Queues the message will be available on; message routing is done when the publish command is received although the actual delivery to the queue(s) happens when the transaction is prepared.
• TxAccept. Accept (dequeue) operation record. The point at which a dequeue is recognized depends on acceptance policy; it may be on delivery/ack or when message is explicitly accepted.

Operation Classes

• SessionAdapter. Handles operations on a session; has a SemanticState.
• SemanticState. Implements the handling of transactional commands start, publish, etc.
• RecoveryManagerImpl. Involved in recovering prepared distributed transactions. This is a target that the store module calls to rebuild the record-keeping objects above. The primary methods in transaction recovery are:
• recoverTransaction. Associate an xid with a TPCTransactionContext. Returns a RecoverableTransaction.
• RecoverableTransaction::enqueue, dequeue. Rebuilds the records of what message enqueue/dequeue operations have been prepared and may be committed or rolled back. [The current recovery of prepared transactions loses the original position of consumed messages in the queue, thus if the transaction is then rolled back, the messages may be requeued in the wrong place - Gordon].