--- jsr166/src/test/tck/AtomicLongArrayTest.java	2003/09/14 20:42:40	1.3
+++ jsr166/src/test/tck/AtomicLongArrayTest.java	2003/12/27 19:26:43	1.6
@@ -1,8 +1,9 @@
 /*
- * Written by members of JCP JSR-166 Expert Group and released to the
- * public domain. Use, modify, and redistribute this code in any way
- * without acknowledgement. Other contributors include Andrew Wright,
- * Jeffrey Hayes, Pat Fischer, Mike Judd.
+ * Written by Doug Lea with assistance from members of JCP JSR-166
+ * Expert Group and released to the public domain, as explained at
+ * http://creativecommons.org/licenses/publicdomain
+ * Other contributors include Andrew Wright, Jeffrey Hayes, 
+ * Pat Fisher, Mike Judd. 
  */
 
 import junit.framework.*;
@@ -17,12 +18,41 @@ public class AtomicLongArrayTest extends
         return new TestSuite(AtomicLongArrayTest.class);
     }
 
+    /**
+     * constructor creates array of given size with all elements zero
+     */
     public void testConstructor(){
         AtomicLongArray ai = new AtomicLongArray(SIZE);
         for (int i = 0; i < SIZE; ++i) 
             assertEquals(0,ai.get(i));
     }
 
+    /**
+     * get and set for out of bound indices throw IndexOutOfBoundsException
+     */
+    public void testIndexing(){
+        AtomicLongArray ai = new AtomicLongArray(SIZE);
+        try {
+            ai.get(SIZE);
+        } catch(IndexOutOfBoundsException success){
+        }
+        try {
+            ai.get(-1);
+        } catch(IndexOutOfBoundsException success){
+        }
+        try {
+            ai.set(SIZE, 0);
+        } catch(IndexOutOfBoundsException success){
+        }
+        try {
+            ai.set(-1, 0);
+        } catch(IndexOutOfBoundsException success){
+        }
+    }
+
+    /**
+     * get returns the last value set at index
+     */
     public void testGetSet(){
         AtomicLongArray ai = new AtomicLongArray(SIZE); 
         for (int i = 0; i < SIZE; ++i) {
@@ -35,6 +65,9 @@ public class AtomicLongArrayTest extends
         }
     }
 
+    /**
+     * compareAndSet succeeds in changing value if equal to expected else fails
+     */
     public void testCompareAndSet(){
         AtomicLongArray ai = new AtomicLongArray(SIZE); 
         for (int i = 0; i < SIZE; ++i) {
@@ -49,6 +82,33 @@ public class AtomicLongArrayTest extends
         }
     }
 
+    /**
+     * compareAndSet in one thread enables another waiting for value
+     * to succeed
+     */
+    public void testCompareAndSetInMultipleThreads() {
+        final AtomicLongArray a = new AtomicLongArray(1);
+        a.set(0, 1);
+        Thread t = new Thread(new Runnable() {
+                public void run() {
+                    while(!a.compareAndSet(0, 2, 3)) Thread.yield();
+                }});
+        try {
+            t.start();
+            assertTrue(a.compareAndSet(0, 1, 2));
+            t.join(LONG_DELAY_MS);
+            assertFalse(t.isAlive());
+            assertEquals(a.get(0), 3);
+        }
+        catch(Exception e) {
+            unexpectedException();
+        }
+    }
+
+    /**
+     * repeated weakCompareAndSet succeeds in changing value when equal
+     * to expected 
+     */
     public void testWeakCompareAndSet(){
         AtomicLongArray ai = new AtomicLongArray(SIZE); 
         for (int i = 0; i < SIZE; ++i) {
@@ -61,6 +121,9 @@ public class AtomicLongArrayTest extends
         }
     }
 
+    /**
+     *  getAndSet returns previous value and sets to given value at given index
+     */
     public void testGetAndSet(){
         AtomicLongArray ai = new AtomicLongArray(SIZE); 
         for (int i = 0; i < SIZE; ++i) {
@@ -71,6 +134,9 @@ public class AtomicLongArrayTest extends
         }
     }
 
+    /**
+     *  getAndAdd returns previous value and adds given value
+     */
     public void testGetAndAdd(){
         AtomicLongArray ai = new AtomicLongArray(SIZE); 
         for (int i = 0; i < SIZE; ++i) {
@@ -82,6 +148,9 @@ public class AtomicLongArrayTest extends
         }
     }
 
+    /**
+     * getAndDecrement returns previous value and decrements
+     */
     public void testGetAndDecrement(){
         AtomicLongArray ai = new AtomicLongArray(SIZE); 
         for (int i = 0; i < SIZE; ++i) {
@@ -92,6 +161,9 @@ public class AtomicLongArrayTest extends
         }
     }
 
+    /**
+     * getAndIncrement returns previous value and increments
+     */
     public void testGetAndIncrement(){
         AtomicLongArray ai = new AtomicLongArray(SIZE); 
         for (int i = 0; i < SIZE; ++i) {
@@ -106,6 +178,9 @@ public class AtomicLongArrayTest extends
         }
     }
 
+    /**
+     *  addAndGet adds given value to current, and returns current value
+     */
     public void testAddAndGet() {
         AtomicLongArray ai = new AtomicLongArray(SIZE); 
         for (int i = 0; i < SIZE; ++i) {
@@ -117,6 +192,9 @@ public class AtomicLongArrayTest extends
         }
     }
 
+    /**
+     * decrementAndGet decrements and returns current value
+     */
     public void testDecrementAndGet(){
         AtomicLongArray ai = new AtomicLongArray(SIZE); 
         for (int i = 0; i < SIZE; ++i) {
@@ -128,6 +206,9 @@ public class AtomicLongArrayTest extends
         }
     }
 
+    /**
+     * incrementAndGet increments and returns current value
+     */
     public void testIncrementAndGet() {
         AtomicLongArray ai = new AtomicLongArray(SIZE); 
         for (int i = 0; i < SIZE; ++i) {
@@ -166,6 +247,10 @@ public class AtomicLongArrayTest extends
         }
     }
 
+    /**
+     * Multiple threads using same array of counters successfully
+     * update a number of times equal to total count
+     */
     public void testCountingInMultipleThreads() {
         try {
             final AtomicLongArray ai = new AtomicLongArray(SIZE); 
@@ -182,10 +267,13 @@ public class AtomicLongArrayTest extends
             assertEquals(c1.counts+c2.counts, SIZE * COUNTDOWN);
         }
         catch(InterruptedException ie) {
-            fail("unexpected exception");
+            unexpectedException();
         }
     }
 
+    /**
+     * a deserialized serialized array holds same values
+     */
     public void testSerialization() {
         AtomicLongArray l = new AtomicLongArray(SIZE); 
         for (int i = 0; i < SIZE; ++i) 
@@ -204,8 +292,7 @@ public class AtomicLongArrayTest extends
                 assertEquals(l.get(i), r.get(i));
             }
         } catch(Exception e){
-            e.printStackTrace();
-            fail("unexpected exception");
+            unexpectedException();
         }
     }