Transaction Notifications

Article
12/15/2021

KTM provides a notification queue for each resource manager. KTM delivers notifications to a resource manager by putting them in the resource manager's queue.

A resource manager can retrieve notifications from its queue either synchronously or asynchronously.

To retrieve notifications synchronously, the resource manager can repeatedly call ZwGetNotificationResourceManager.
To receive notifications asynchronously, the resource manager can call TmEnableCallbacks to set up a callback routine. KTM calls the callback routine every time that it puts a notification in the resource manager's queue.

When a resource manager calls ZwCreateEnlistment to create an enlistment for a transaction, the resource manager specifies the types of notifications that it should receive. Resource managers receive only notifications that they register to receive.

The notification constants are defined in Ktmtypes.h. Notification constant names have a format of TRANSACTION_NOTIFY_Xxx.

The rest of this topic lists all the notification constants that Ktmtypes.h defines and divides them into three groups:

Notifications that resource managers can receive
Notifications that superior transaction managers can receive
Notification constants that are defined but currently not used

Notifications for Resource Managers

All resource managers must register to receive TRANSACTION_NOTIFY_PREPREPARE, TRANSACTION_NOTIFY_PREPARE, and TRANSACTION_NOTIFY_COMMIT notifications, even if they subsequently call ZwReadOnlyEnlistment to mark an enlistment as read-only.

Resource managers can support TRANSACTION_NOTIFY_SINGLE_PHASE_COMMIT, but they must also support the multi-phase pre-prepare, prepare, and commit notifications.

The following list contains all the notifications that resource managers can receive:

TRANSACTION_NOTIFY_PREPREPARE
When sent: A client calls ZwCommitTransaction and no resource manager supports single-phase commit, or if a superior transaction manager calls ZwPrePrepareEnlistment.

Received by: Resource managers.

Recipient's required action: Perform pre-prepare operations and then call ZwPrePrepareComplete. (For more information about pre-prepare operations, see Handling Commit Operations.)

Restrictions: The resource manager must also support TRANSACTION_NOTIFY_PREPARE and TRANSACTION_NOTIFY_COMMIT.

TRANSACTION_NOTIFY_PREPARE
When sent: After TRANSACTION_NOTIFY_PREPREPARE if a client calls ZwCommitTransaction and no resource manager supports single-phase commit, or if a superior transaction manager calls ZwPrepareEnlistment.

Received by: Resource managers.

Recipient's required action: Perform prepare operations and then call ZwPrepareComplete. (For more information about prepare operations, see Handling Commit Operations.)

Restrictions: The resource manager must also support TRANSACTION_NOTIFY_PREPREPARE and TRANSACTION_NOTIFY_COMMIT.

TRANSACTION_NOTIFY_COMMIT
When sent: After TRANSACTION_NOTIFY_PREPARE if a client calls ZwCommitTransaction and no resource manager supports single-phase commit, or if a superior transaction manager calls ZwCommitEnlistment.

Received by: Resource managers.

Recipient's required action: Perform commit operations and then call ZwCommitComplete. (For more information about commit operations, see Handling Commit Operations.)

Restrictions: The resource manager must also support TRANSACTION_NOTIFY_PREPREPARE and TRANSACTION_NOTIFY_PREPARE.

TRANSACTION_NOTIFY_SINGLE_PHASE_COMMIT
When sent: A client calls ZwCommitTransaction and a resource manager supports single-phase commit operations.

Received by: Resource managers.

Recipient's required action: Either commit the transaction or call ZwSinglePhaseReject. (For more information about single-phase commit operations, see Handling Commit Operations.)

Restrictions: The resource manager must also support TRANSACTION_NOTIFY_PREPREPARE, TRANSACTION_NOTIFY_PREPARE, and TRANSACTION_NOTIFY_COMMIT.

TRANSACTION_NOTIFY_ROLLBACK
When sent: A client calls ZwRollbackTransaction, a superior transaction manager calls ZwRollbackEnlistment, or KTM detects an error (such as a failed write to the log stream).

Received by: Both resource managers and superior transaction managers.

Recipient's required action: Perform any operations that are needed to roll back the transaction's data, and then call ZwRollbackComplete. (For more information about rollback operations, see Handling Rollback Operations.)

Restrictions: All resource managers and superior transaction managers must support TRANSACTION_NOTIFY_ROLLBACK.

TRANSACTION_NOTIFY_RECOVER
When sent: A resource manager calls ZwRecoverResourceManager.

Received by: Resource managers.

Recipient's required action: The resource manager must call ZwRecoverEnlistment. (For more information about recovery operations, see Handling Recovery Operations.)

Restrictions: None.

TRANSACTION_NOTIFY_LAST_RECOVER
When sent: After KTM has sent the last TRANSACTION_NOTIFY_RECOVER for a resource manager's enlistments.

Received by: Resource managers.

Recipient's required action: End the recovery operation. (For more information about recovery operations, see Handling Recovery Operations.)

Restrictions: None.

TRANSACTION_NOTIFY_INDOUBT
When sent: After a resource manager calls ZwRecoverEnlistment, if KTM cannot determine whether the transaction should be committed or rolled back (typically because the TPS has a superior transaction manager that is unavailable).

Received by: Resource managers.

Recipient's required action: Do nothing until KTM sends TRANSACTION_NOTIFY_COMMIT or TRANSACTION_NOTIFY_ROLLBACK.

Restrictions: None.

TRANSACTION_NOTIFY_RM_DISCONNECTED
When sent: The resource manager that is handling a single-phase commit operation closes the enlistment handle without indicating that it has committed or rolled back the transaction.

Received by: Resource managers and superior transaction managers that have enlistments for the transaction.

Recipient's required action: Transaction-specific cleanup operations. Typically, this notification is useful to read-only resource managers.

Restrictions: None.

Notifications for Superior Transaction Managers

Superior transaction managers can receive the following notifications:

TRANSACTION_NOTIFY_ROLLBACK
See earlier description.

TRANSACTION_NOTIFY_RM_DISCONNECTED
See earlier description.

TRANSACTION_NOTIFY_PREPREPARE_COMPLETE
When sent: After all resource managers have received TRANSACTION_NOTIFY_PREPREPARE and responded by calling ZwPrePrepareComplete.