Using Software Transactional Memory in Quarkus

Quarkus supports the Software Transactional Memory (STM) implementation provided by the Narayana open source project. Narayana STM allows a program to group object accesses into a transaction such that other transactions either see all of the changes at once or they see none of them.

STM offers an approach to developing transactional applications in a highly concurrent environment with some of the same characteristics of ACID (Atomicity, Consistency, Isolation and Durability) transactions.

To use Narayana STM you must define which objects you would like to be transactional using java annotations. Please refer to the Narayana STM manual and the STM annotations guide for more details.

There is also a fully worked example in the quickstarts which you may access by cloning the Git repository: git clone, or by downloading an archive. Look for the software-transactional-memory-quickstart example.

Setting it up

To use the extension include it as a dependency in your application pom:

    <!-- STM extension -->

Now you may use the STM library just like you would normally use it. But briefly, the process is:

Defining Transactional Objects

Transactional objects must implement an interface. Add the org.jboss.stm.annotations.Transactional annotation to the interfaces that you wish to be managed by a transactional container. For example

public interface FlightService {
    int getNumberOfBookings();
    void makeBooking(String details);

Unless specified using other annotations, all public methods of implementations of this object will be assumed to modify the state of the object. Please refer to the Narayana guide for details of how to exert finer grained control over the transactional behaviour of objects that implement interfaces marked with the @Transactional annotation.

Creating STM objects

The STM library needs to be told which objects it should be managing by providing a container for the transactional memory. The default container (org.jboss.stm.Container) provides support for volatile objects that cannot be shared between JVMs (although other constructors do allow for other models):

    import org.jboss.stm.Container;


    Container<FlightService> container = new Container<>(); (1)
    FlightServiceImpl instance = new FlightServiceImpl(); (2)
    FlightService flightServiceProxy = container.create(instance); (3)
1 You need to tell each Container about the type of objects for which it will be responsible. In this example it will be instances that implement the FlightService interface.
2 Then you create an instance that implements FlightService. You cannot use it directly at this stage because its operations aren’t being monitored by the Container.
3 To obtain a managed instance, pass the instance to the container to obtain a reference through which you will be able perform transactional operations. This reference can be used safely from multiple threads (provided that each thread uses it in a transaction context - see the next section.

Defining transaction boundaries

STM objects must be accessed within a transaction (otherwise they will behave just like any other java object). You can define the transaction boundary in two ways:

Declarative approach

The easiest, but less flexible, way to define your transaction boundaries is to place an @NestedTopLevel or @Nested annotation on the interface. Then when a method of your transactional object is invoked a new transaction will be created for the duration of the method call.

API approach

The more flexible approach is to manually start a transaction before accessing methods of transactional objects:

AtomicAction aa = new AtomicAction(); (1)

aa.begin(); (2)
    try {
        flightService.makeBooking("BA123 ...");
        taxiService.makeBooking("East Coast Taxis ..."); (3)
    } catch (Exception e) {
        aa.abort(); (6)
1 An object for manually controlling transaction boundaries (AtomicAction and many other useful classes are included in the extension). Refer to the javadoc for more detail.
2 Programmatically begin a transaction.
3 Notice that object updates can be composed which means that updates to multiple objects can be committed together as a single action. [Note that it is also possible to begin nested transactions so that you can perform speculative work which may then be abandoned without abandoning other work performed by the outer transaction].
4 Since the transaction has not yet been committed the changes made by the flight and taxi services are not visible outside of the transaction.
5 Since the commit was successful the changes made by the flight and taxi services are now visible to other threads. Note that other transactions that relied on the old state may or may not now incur conflicts when they commit (the STM library provides a number of features for managing conflicting behaviour and these are covered in the Narayana STM manual).
6 Programmatically decide to abort the transaction which means that the changes made by the flight and taxi services are discarded.

Concurrency behaviour

The goal of STM is to simplify object reads and writes from multiple threads. Threads are responsible for starting their own transactions before accessing a transactional object. The STM library will safely manage any conflicts between these threads. For example, if the access mode is pessimistic (the default), and a thread enters a transactional method then other threads may be blocked until the first thread leaves the method. This blocking behaviour may be modified using suitable STM annotations. Optimistic concurrency is also supported: in this mode conflicts are checked only at commit time and a thread may be forced to abort if another thread has made conflicting updates.

Remark: sharing a transaction between multiple threads is possible but is currently an advanced use case only and the Narayana documentation should be consulted if this behaviour is required. In particular, STM does not yet support the features described in the Context Propagation guide.