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.