STM Guide

This book describes the STM feature that is available for use with Narayana

In this chapter we shall look at the Software Transactional Memory (STM) implementation that ships as part of Narayana. We won't go into the theoretical details behind STM as they would take up an entire book and there are sufficint resources available for the interested reader to find out themselves. But suffice it to say that STM offers an approach to developing transactional applications in a highly concurrent environment with some of the same characteristics of ACID transactions. Typically though, the Durability property is relaxed (removed) within STM implementations.

The Narayana STM implementation builds on the Transactional Objects for Java (TXOJ) framework which has offered building blocks for the construction of transactional objects via inheritence. The interested reader should look at the text on TXOJ within the ArjunaCore documentation for more in depth details. However, within TXOJ an application class can inherit from the LockManager class to obtain persistence (D) and concurrency (I), whilst at the same time having the flexibility to change some of these capabilities. For example, an object could be volatile, i.e., no durability, and yet still maintain the other transactional properties.

If you look at the abilities that TXOJ offers to developers then it shares many aspects with STM. However, the downside is that developers need to modify their classes through class inheritence (something which is not always possible), add suitable extension methods (for saving and restoring state), set locks etc. None of this is entirely unreasonable, but it represents a barrier to some and hence is one of the reasons we decided to provide a separate STM implementation.

public interface Atomic
{
   public void incr (int value) throws Exception;
   public void set (int value) throws Exception;
   public int get () throws Exception;
}

public class ExampleInteger implements Atomic
{   
   public int get () throws Exception
   {
       return state;
   }

   public void set (int value) throws Exception
   {
       state = value;
   }

   public void incr (int value) throws Exception
   {
       state += value;
   }

   private int state;
}

@Transactional
public interface Atomic
{
   public void incr (int value) throws Exception;
   public void set (int value) throws Exception;
   public int get () throws Exception;
}

public class ExampleInteger implements Atomic
{   
   @WriteLock
   public int get () throws Exception
   {
       return state;
   }

   @WriteLock
   public void set (int value) throws Exception
   {
       state = value;
   }

   @ReadLock
   public void incr (int value) throws Exception
   {
       state += value;
   }

   private int state;
}

Container<Atomic> theContainer = new Container<Atomic>();    ExampleInteger basic = new ExampleInteger();       
Atomic obj = theContainer.create(basic);
AtomicAction a = new AtomicAction();

a.begin();                

obj.set(1234);                

a.commit();        

if (obj.get() == 1234)
   System.out.println("State changed ok!");
else
   System.out.println("State not changed!");                
a = new AtomicAction();        

a.begin();        

obj.change(1);                

a.abort();        

if (obj.get() == 1234)
   System.out.println("State reverted to 1234!");
else
   System.out.println("State is wrong!");

TestContainer<Sample> theContainer = new TestContainer<Sample>();
SampleLockable tester = new SampleLockable();
Sample proxy = theContainer.enlist(tester);

public enum TYPE { RECOVERABLE, PERSISTENT };

public enum MODEL { SHARED, EXCLUSIVE };

Sample1 obj1 = theContainer.create(new Sample1Imple(10));

Uid id = theContainer.getIdentifier(obj1)

public synchronized T clone (T member, T proxy)

Sample1 obj2 = theContainer.clone(new Sample1Imple(), obj1);

public synchronized T clone (T member, Uid id)

Sample1 obj2 = theContainer.clone(new Sample1Imple(), theContainer.getIdentifier(obj1));

public void save_state (OutputObjectState os) throws IOException

public void restore_state (InputObjectState os) throws IOException

public class DummyImple implements Dummy
{
        public DummyImple ()
        {
            _isNotState = false;
            _saved = 1234;
        }

        @ReadLock
        public int getInt ()
        {
            return _saved;
        }

        @WriteLock
        public void setInt (int value)
        {
            _saved = value;
        }

        @ReadLock
        public boolean getBoolean ()
        {
            return _isNotState;
        }                

        @WriteLock
        public void setBoolean (boolean value)
        {
            _isNotState = value;
        }

        @SaveState
        public void save_state (OutputObjectState os) throws IOException
        {
           os.packInt(_saved);
        }

        @RestoreState
        public void restore_state (InputObjectState os) throws IOException
        {
            _saved = os.unpackInt();
        }

        public int _saved;
        public boolean _isNotState;
}

@Transactional
@Optimistic
public class SampleLockable implements Sample
{
   public SampleLockable (int init)
   {
      _isState = init;
   }

   @ReadLock
   public int value ()
   {
      return _isState;
   }

   @WriteLock
   public void increment ()
   {
      _isState++;
   }

   @WriteLock
   public void decrement ()
   {
      _isState--;
   }

   @State
   private int _isState;
}

Container theContainer = new Container();
Sample obj1 = theContainer.create(new SampleLockable(10));
Sample obj2 = theContainer.clone(new SampleLockable(10),obj1);

@Transactional
public interface Sample    
{
       public void increment ();
       public void decrement ();

       public int value ();
}

public class MyExample implements Sample    
{
        public MyExample ()
        {
            this(0);
        }        

        public MyExample (int init)
        {
            _isState = init;
        }

        @ReadLock
        public int value ()
        {
            return _isState;
        }

        @WriteLock
        public void increment ()
        {
            _isState++;
        }

        @WriteLock
        public void decrement ()
        {
            _isState--;
        }

        private int _isState;
}

MyExample ex = new MyExample(10);        
Container<Sample> theContainer = new Container<Sample>();    Sample obj1 = theContainer.create(ex);        
AtomicAction act = new AtomicAction();

act.begin();                

obj1.increment();                

act.commit();