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.



Related Articles

Comments

  • There are no comments yet. Be the first to comment!

Leave a Comment
  • Your email address will not be published. All fields are required.

Top White Papers and Webcasts

  • Live Event Date: December 11, 2014 @ 1:00 p.m. ET / 10:00 a.m. PT Market pressures to move more quickly and develop innovative applications are forcing organizations to rethink how they develop and release applications. The combination of public clouds and physical back-end infrastructures are a means to get applications out faster. However, these hybrid solutions complicate DevOps adoption, with application delivery pipelines that span across complex hybrid cloud and non-cloud environments. Check out this …

  • Due to internal controls and regulations, the amount of long term archival data is increasing every year. Since magnetic tape does not need to be periodically operated or connected to a power source, there will be no data loss because of performance degradation due to the drive actuator. Read this white paper to learn about a series of tests that determined magnetic tape is a reliable long-term storage solution for up to 30 years.

Most Popular Programming Stories

More for Developers

RSS Feeds