Loading...
Searching...
No Matches
14. Transactions

# 14.1 General Ideas

StarPU's transactions enable the cancellation of a sequence of already submitted tasks based on a just-in-time decision. The purpose of this mechanism is typically for iterative applications to submit tasks for the next iteration ahead of time while leaving some iteration loop criterion (e.g. convergence) to be evaluated just before the first task of the next iteration is about to be scheduled. Such a sequence of collectively cancelable tasks is called a transaction epoch.

# 14.2 Usage

Some examples illustrating the usage of StarPU's transactions are available in the directory `examples/transactions`.

## 14.2.1 Epoch Cancellation

If the start criterion of an epoch evaluates to `False`, all the tasks for that next epoch are canceled. Thus, StarPU's transactions let applications avoid the use of synchronization barriers commonly found between the task submission sequences of subsequent iterations, and avoid breaking the flow of dependencies in the process. Moreover, while the kernel functions of canceled transaction tasks are not executed, their dependencies are still honored in the proper order.

## 14.2.2 Transactions Enabled Codelets

Codelets for tasks being part of a transaction should set their `nbuffers` field to STARPU_VARIABLE_NBUFFERS.

## 14.2.3 Transaction Creation

A `struct starpu_transaction` opaque object is created using the starpu_transaction_open() function, specifying a transaction start criterion callback and some user argument to be passed to that callback upon the first call. The start criterion callback should return `True` (e.g. `!0` ) if the next transaction epoch should proceed, or `False` (e.g. `0` ) if the tasks belonging to that next epoch should be canceled. `starpu_transaction_open()` submits an internal task to mark the beginning of the transaction. If submitting that internal task fails with ENODEV, `starpu_transaction_open()` will return `NULL`.

## 14.2.4 Transaction Tasks

Tasks governed by the same transaction object should be passed that transaction object either through the ``.transaction field of starpu_task structures, using the STARPU_TRANSACTION argument of starpu_task_insert().

## 14.2.5 Epoch Transition

The transition from one transaction epoch to the next is expressed using the starpu_transaction_next_epoch function to which the `starpu_transaction` object and a user argument are passed. Upon a call to that function, the start criterion callback is evaluated on users argument to decide whether the next epoch should proceed or be canceled.

## 14.2.6 Transaction Closing

The last epoch should be ended through a call to starpu_transaction_close().

# 14.3 Known limitations

Support for transactions is experimental.
StarPU's transactions are currently not compatible with StarPU-MPI distributed sessions.