The classes in the package java.util.concurrent use atomic methods to update their internal state in a thread-safe way. In the following, you will see how to write and use such atomic methods to create thread-safe classes.

Atomic methods

A method is atomic if it is "all or nothing". If a thread reads the data the thread can only see the state before or after the execution of the atomic method, no intermediate state. After the atomic method was executed successfully the changes are visible to all threads. The atomic method only modifies data of its own object without side effects.
Here are some examples of atomic methods:

Writing atomic methods

The easiest way to implement atomic methods is to use synchronized blocks. For example, the backport for AtomicInteger for JDKs prior to version 1.5 uses synchronized blocks and volatile fields:

package edu.emory.mathcs.backport.java.util.concurrent.atomic;
public class AtomicInteger extends Number implements java.io.Serializable {
  private volatile int value;
  public final int get() {
        return value;
    }
    public final synchronized void set(int newValue) {
        value = newValue;
    }
    public final synchronized int addAndGet(int delta) {
        return value += delta;
    }
}

To write lock-free atomic methods you can use atomic operations of the CPU. In JAVA atomic operations can be accessed using sun.misc.Unsafe like in the implementation of AtomicInteger below. Or you can use the classes of the java.util.concurrent.atomic package, which provides atomic operations for each field type.

package java.util.concurrent.atomic;
import sun.misc.Unsafe;
public class AtomicInteger extends Number implements java.io.Serializable {
 private static final Unsafe unsafe = Unsafe.getUnsafe();
 private static final long valueOffset;
    static {
        try {
            valueOffset = unsafe.objectFieldOffset
                (AtomicInteger.class.getDeclaredField("value"));
        } catch (Exception ex) { throw new Error(ex); }
    }
    private volatile int value;
    public final int get() {
        return value;
    }
    public final void set(int newValue) {
        value = newValue;
    }
   public final int addAndGet(int delta) {
        return unsafe.getAndAddInt(this, valueOffset, delta) + delta;
    }
}

Using atomic methods

To see how to use atomic methods let us update our AtomicInteger from two threads. We can simulate this using the following two methods. Calling AtomicInteger sequential:

public void testSetAndGetSequential() throws Exception
	{
		AtomicInteger atomicInteger= new AtomicInteger(0);
		int threadA = atomicInteger.get();
		atomicInteger.set(threadA + 5);
		int threadB = atomicInteger.get();
		atomicInteger.set(threadB + 5);
		assertEquals(   atomicInteger.get() , 10  );
	}

and calling AtomicInteger in parallel:

	public void testSetAndGetParallel() throws Exception
	{
		AtomicInteger atomicInteger= new AtomicInteger(0);
		int threadA = atomicInteger.get();
		int threadB = atomicInteger.get();
		atomicInteger.set(threadA + 5);
		atomicInteger.set(threadB + 5);
		assertEquals(   atomicInteger.get() , 5  );
	}

Each method simulates a different thread interleaving. As we can see the use of get and set leads for a specific thread interleaving to an incorrect result. To update the AtomicInteger correctly we need to use a method which combines the set and get operation in an atomic method, the addAndGet method. Now the result is independent of the thread interleaving:

	public void testUpdate() throws Exception
	{
		AtomicInteger atomicInteger= new AtomicInteger(0);
		atomicInteger.addAndGet(5); // Thread A
		atomicInteger.addAndGet(5); // Thread B
		assertEquals(   atomicInteger.get() , 10  );
	}

Care must be taken if we want to use callback functions inside atomic methods like in the compute method of ConcurrentHashMap. Those callback methods should not modify the same object, as in the test below. The following usage leads to a deadlock. To test this we need a multi-threaded unit test. This junit test uses concurrent-junit to run the test in parallel. The ConcurrentTestRunner runs each test method in parallel by 4 threads.

import java.util.concurrent.ConcurrentHashMap;
import java.util.function.BiFunction;
import org.junit.Test;
import org.junit.runner.RunWith;
import com.anarsoft.vmlens.concurrent.junit.ConcurrentTestRunner;
@RunWith(ConcurrentTestRunner.class)
public class TestConcurrentHashMapCompute {
	private final ConcurrentHashMap<Integer,Integer> map = new ConcurrentHashMap<Integer,Integer>();
	public TestConcurrentHashMapCompute()
	{
		map.put(1, 1);
		map.put(2, 2);	
	}
	@Test
	public void update12()
	{
		map.compute( 1 ,   			
				new BiFunction<Integer,Integer,Integer>()
				{
					public Integer apply(Integer k, Integer v) {		
						map.put( 2 , 1);
						return v;
					}
				}
				);
	}
	@Test
	public void update21()
	{
              map.compute( 2 ,   			
				new BiFunction<Integer,Integer,Integer>()
				{
					public Integer apply(Integer k, Integer v) {		
						map.put( 1 , 1);
						return v;
					}
				}
				);
	}
}

If we run the test we see the following deadlocks. The trace was generated by vmlens.com:

- deadlock: Monitor@java.util.concurrent.ConcurrentHashMap.putVal()<->Monitor@java.util.concurrent.ConcurrentHashMap.putVal()
  parent2Child:
    thread: Thread-4
    stack:
      - java.util.concurrent.ConcurrentHashMap.putVal <<Monitor@java.util.concurrent.ConcurrentHashMap.putVal()>>
      - java.util.concurrent.ConcurrentHashMap.put
      - com.anarsoft.vmlens.concurrent.example.TestConcurrentHashMapCompute$2.apply
      - com.anarsoft.vmlens.concurrent.example.TestConcurrentHashMapCompute$2.apply
      - java.util.concurrent.ConcurrentHashMap.compute <<Monitor@java.util.concurrent.ConcurrentHashMap.putVal()>>
      - com.anarsoft.vmlens.concurrent.example.TestConcurrentHashMapCompute.update21
  child2Parent:
    thread: Thread-1
    stack:
      - java.util.concurrent.ConcurrentHashMap.putVal <<Monitor@java.util.concurrent.ConcurrentHashMap.putVal()>>
      - java.util.concurrent.ConcurrentHashMap.put
      - com.anarsoft.vmlens.concurrent.example.TestConcurrentHashMapCompute$1.apply
      - com.anarsoft.vmlens.concurrent.example.TestConcurrentHashMapCompute$1.apply
      - java.util.concurrent.ConcurrentHashMap.compute <<Monitor@java.util.concurrent.ConcurrentHashMap.putVal()>>
      - com.anarsoft.vmlens.concurrent.example.TestConcurrentHashMapCompute.update12

Conclusion

Atomic methods let you use classes in a thread-safe way without knowing the implementation details. To test a specific thread interleaving we can simply order the calls accordingly. Callback functions inside atomic methods should not modify the same object since this might lead to deadlocks.