Programming the Kernel Transaction Manager (KTM) API

The Kernel Transaction Manager (KTM)
provides a simple API for developers to create, query, commit and abort
transactions.  Various Windows resource managers such as the Transactional
File System (TxF) can be managed with KTM transactions.

The Windows Kernel
Transaction Manager
(KTM) is a transaction manager that is part of the
Windows operating system, and provides transactional services to code executing
in both kernel mode and user mode. 

There are two
distinct clients for the KTM API
resource managers that use the KTM to determine when to commit and
rollback changes to the resource they manage based on the result of a
transaction, and transaction-initiating applications that use the KTM to
ensure that the resource mangers that they interact with are left in a
consistent state.  The focus of this article is transaction-initiating
applications
.

The basis for much of
the API is the transaction handle, which is returned by the
CreateTransaction function and passed into various KTM functions like
CommitTransaction and RollbackTransaction.  In addition to creating a
transaction, an application can retrieve a handle to an existing transaction by
using the OpenTransaction function, which takes a transaction ID in the form of
a GUID.  The transaction ID for a particular transaction handle can be
retrieved via the GetTransactionId function.

Once a transaction
handle has been created or opened, it can be passed to any KTM-aware resource
manager so that operations against the resource are managed as part of the
transaction.  It is the job of the resource manager to monitor the state
of the transaction, and in the event where the transaction is not committed,
the resource manager is responsible for rolling back any changes that were made
within the scope of the transaction.

The KTM follows
normal transaction semantics in that transaction participants (i.e. executing
code that has a transaction handle open) can vote on the outcome of a
transaction by calling CommitTransaction or RollbackTransaction prior to
calling CloseHandle.  A transaction will be rolled back if any participant
calls RollbackTransaction prior to the transaction being committed or all
transaction handles are closed with no participant calling
CommitTransaction.  CommitTransaction can be called at any time while the
transaction is still active, and once a participant has completed their
required operations within the transaction scope, they should call
CommitTransaction unless they have detected an error and need to call
RollbackTransaction.

The current state of
a transaction can be queried by calling GetTransactionInformation, with the
possible outcomes of the returned TRANSACTION_OUTCOME parameter being
TransactionOutcomeUndetermined, TransactionOutcomeCommitted and
TransactionOutcomeAborted.  A description can be associated with a
transaction using the SetTransactionInformation function, which also allows a
timeout for a transaction to be specified.

For most
applications, taking advantage of the KTM will be a simple matter of creating a
transaction, using the transaction handle when interacting with a resource
manager, committing the transaction when interactions with the resource manager
are complete, and optionally tracking the final outcome of the
transaction.  The code below demonstrates this simple pattern:

HANDLE hTransaction = CreateTransaction(NULL, 0, 0, 0, 0, INFINITE,
  L"Demo Transaction");

//interact with resource manager here, passing hTransaction to all functions as required.

BOOL transCommitResult = CommitTransaction(hTransaction);

//optional
DWORD transactionOutcome;
BOOL transInformatioResult = GetTransactionInformation(hTransaction, &transactionOutcome, NULL, NULL, NULL, 0, NULL);
BOOL transactionGood = transactionOutcome == TRANSACTION_OUTCOME::TransactionOutcomeCommitted;


CloseHandle(hTransaction);
hTransaction = NULL;

The Windows KTM
provides a simple yet complete API for consistently managing transactions that
span one or more resource managers.  By allowing multiple operations
against multiple resources to be managed within the scope of a single
transaction, data consistency can be guaranteed.

More by Author

Must Read