Using Software Transactional Memory in Quarkus

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

STM offers an approach to developing transactional applications in a highly concurrentenvironment 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 javaannotations. Please refer to the Narayana STM manualand the STM annotations guide for more details.

There is also a fully worked example in the quickstarts which you may access by cloning theGit repository: git clone https://github.com/quarkusio/quarkus-quickstarts.git, 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:

  1. <dependencies>
  2.     <!-- STM extension -->
  3.     <dependency>
  4.       <groupId>io.quarkus</groupId>
  5.       <artifactId>quarkus-narayana-stm</artifactId>
  6.       <version>${quarkus.version}</version>
  7.     </dependency>
  8. </dependencies>

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 theinterfaces that you wish to be managed by a transactional container. For example

  1. @Transactional
  2. public interface FlightService {
  3.     int getNumberOfBookings();
  4.     void makeBooking(String details);
  5. }

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 implementinterfaces 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):

  1.     import org.jboss.stm.Container;
  3.     ...
  5.     Container<FlightService> container = new Container<>(); (1)
  6.     FlightServiceImpl instance = new FlightServiceImpl(); (2)
  7.     FlightService flightServiceProxy = container.create(instance); (3)
1You need to tell each Container about the type of objects for which it will be responsible. In this exampleit will be instances that implement the FlightService interface.
2Then you create an instance that implements FlightService. You cannot use it directly at this stage becauseits operations aren’t being monitored by the Container.
3To obtain a managed instance, pass the instance to the container to obtain a reference through which youwill 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:

  1. AtomicAction aa = new AtomicAction(); (1)
  3. aa.begin(); (2)
  4. {
  5.     try {
  6.         flightService.makeBooking("BA123 ...");
  7.         taxiService.makeBooking("East Coast Taxis ..."); (3)
  8.         (4)
  9.         aa.commit();
  10.         (5)
  11.     } catch (Exception e) {
  12.         aa.abort(); (6)
  13.     }
  14. }
1An object for manually controlling transaction boundaries (AtomicAction and many other usefulclasses are included in the extension).Refer to the javadoc for more detail.
2Programmatically begin a transaction.
3Notice 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 abandonedwithout abandoning other work performed by the outer transaction].
4Since the transaction has not yet been committed the changes made by the flight and taxi services are not visible outside of the transaction.
5Since 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 libraryprovides a number of features for managing conflicting behaviour and these are covered in the Narayana STM manual).
6Programmatically 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 accessinga transactional object. The STM library will safely manage any conflicts betweenthese threads. For example, if the access mode is pessimistic (the default),and a thread enters a transactional method then other threads may be blockeduntil the first thread leaves the method. This blocking behaviour may be modifiedusing suitable STM annotations. Optimistic concurrency is also supported: inthis mode conflicts are checked only at commit time and a thread may be forcedto abort if another thread has made conflicting updates.

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