The picotm Programming Interface

This section provides information for users of picotm. It explains the concept of transactions and how to run a transaction with picotm. More...

Files
file	picotm-error.h
	Contains struct picotm_error and helper functions.
file	picotm.h
	Main header file for picotm.

Detailed Description

Properties of a Transaction

The transaction concept is a powerful metaphor for implementing concurrent and fault-tolerant software. A transaction system provides two services to it's users. These are

• concurrency control (i.e., thread-safe access to shared resources), and
• error handling.

Writing Transactions

Each transactions contains at least the statements

1. picotm_begin,
2. picotm_commit, and
3. picotm_end

in this exact order. In the source code, this looks like this

void
func()
{
     // non-transactional code

     int x = 0;

     picotm_begin
         // transactional code
     picotm_commit
     picotm_end

     // more non-transactional code
}

Transactional operations are invoked between picotm_begin and picotm_commit. This is called the transaction's execution phase. Operations listed in the execution phase are subject to speculative execution. This means that an operation might be executed, but it's effects are not be permanent until the transaction commits.

The transaction performs a commit when the user invokes picotm_commit. This is called the commit phase. It is completely implemented by picotm. No intervention by the user is required.

Upon entering the commit phase, picotm validates the consistency of all resources that the transaction uses. If validation succeeds, the transaction's effects are applied to become permanent. The program then continuous with the next operation after picotm_end. If validation fails, the transaction's effects are reverted and the transaction restarts from picotm_begin. The roll-back is transparent to the program.

If an operation fails, picotm provides error handling for it's operations. Error handling consists of

• error detection, and
• error recovery.

Error detection is completely implemented by picotm an it's module. When picotm invokes an operation it tests for reported errors. No intervention by the user is required.

Error recovery is partially provided by picotm. For picotm, it is possible to recover from some errors. For example, if a write operation to a file temporarily fails, picotm can retry.

Some errors require special program logic to recover. For example, if the program runs out of memory, it might free up memory by invoking a garbage collector. This cannot generally be implemented by picotm, as it depends on program-specific constraints. This is called the recovery phase.

Error-recovery code is located between picotm_commit and picotm_end. If picotm detects an error that is cannot recover from, it rolls back the transaction's effects and jumps to the first instruction after picotm_commit. The program now has the chance of performing error recovery and, if successful, restart the transaction by calling picotm_restart().