### changeset 8465:95cfe3e46610

Update to docs of parallel array sort methods. Contributed-by: Chris Hegarty <chris.hegarty@oracle.com>
author psandoz Tue, 07 May 2013 16:17:05 +0200 403a34d53eae e014a447a0a2 src/share/classes/java/util/Arrays.java test/java/util/Arrays/ParallelSorting.java 2 files changed, 200 insertions(+), 130 deletions(-) [+]
line wrap: on
line diff
```--- a/src/share/classes/java/util/Arrays.java	Mon May 06 18:39:53 2013 +0200
+++ b/src/share/classes/java/util/Arrays.java	Tue May 07 16:17:05 2013 +0200
@@ -442,14 +442,18 @@
/**
* Sorts the specified array into ascending numerical order.
*
-     * <p>Implementation note: The sorting algorithm is a parallel sort-merge
-     * that breaks the array into sub-arrays that are themselves sorted and then
-     * merged. When the sub-array length reaches a minimum granularity (currently
-     * {@value #MIN_ARRAY_SORT_GRAN}) the sub-array is sorted using the appropriate
+     * @implNote The sorting algorithm is a parallel sort-merge that breaks the
+     * array into sub-arrays that are themselves sorted and then merged. When
+     * the sub-array length reaches a minimum granularity (currently {@link
+     * #MIN_ARRAY_SORT_GRAN}) the sub-array is sorted using the appropriate
* {@link Arrays#sort(byte[]) Arrays.sort} method. The algorithm
-     * requires a working space equal to the size of the original array.
+     * requires a working space equal to the size of the original array. The
+     * {@link java.util.concurrent.ForkJoinPool#commonPool() ForkJoin common
+     * pool} is used to execute any parallel tasks.
*
* @param a the array to be sorted
+     *
+     * @since 1.8
*/
public static void parallelSort(byte[] a) {
int n = a.length, p, g;
@@ -464,17 +468,19 @@
}

/**
-     * Sorts the specified array into ascending numerical order. The range
-     * to be sorted extends from the index {@code fromIndex}, inclusive, to
-     * the index {@code toIndex}, exclusive. If {@code fromIndex == toIndex},
-     * the range to be sorted is empty.
-     *
-     * <p>Implementation note: The sorting algorithm is a parallel sort-merge
-     * that breaks the array into sub-arrays that are themselves sorted and then
-     * merged. When the sub-array length reaches a minimum granularity (currently
-     * {@value #MIN_ARRAY_SORT_GRAN}) the sub-array is sorted using the appropriate
+     * Sorts the specified range of the array into ascending numerical order.
+     * The range to be sorted extends from the index {@code fromIndex},
+     * inclusive, to the index {@code toIndex}, exclusive. If
+     * {@code fromIndex == toIndex}, the range to be sorted is empty.
+     *
+     * @implNote The sorting algorithm is a parallel sort-merge that breaks the
+     * array into sub-arrays that are themselves sorted and then merged. When
+     * the sub-array length reaches a minimum granularity (currently {@link
+     * #MIN_ARRAY_SORT_GRAN}) the sub-array is sorted using the appropriate
* {@link Arrays#sort(byte[]) Arrays.sort} method. The algorithm
-     * requires a working space equal to the size of the original array.
+     * requires a working space equal to the size of the original array. The
+     * {@link java.util.concurrent.ForkJoinPool#commonPool() ForkJoin common
+     * pool} is used to execute any parallel tasks.
*
* @param a the array to be sorted
* @param fromIndex the index of the first element, inclusive, to be sorted
@@ -483,6 +489,8 @@
* @throws IllegalArgumentException if {@code fromIndex > toIndex}
* @throws ArrayIndexOutOfBoundsException
*     if {@code fromIndex < 0} or {@code toIndex > a.length}
+     *
+     * @since 1.8
*/
public static void parallelSort(byte[] a, int fromIndex, int toIndex) {
rangeCheck(a.length, fromIndex, toIndex);
@@ -500,14 +508,18 @@
/**
* Sorts the specified array into ascending numerical order.
*
-     * <p>Implementation note: The sorting algorithm is a parallel sort-merge
-     * that breaks the array into sub-arrays that are themselves sorted and then
-     * merged. When the sub-array length reaches a minimum granularity (currently
-     * {@value #MIN_ARRAY_SORT_GRAN}) the sub-array is sorted using the appropriate
+     * @implNote The sorting algorithm is a parallel sort-merge that breaks the
+     * array into sub-arrays that are themselves sorted and then merged. When
+     * the sub-array length reaches a minimum granularity (currently {@link
+     * #MIN_ARRAY_SORT_GRAN}) the sub-array is sorted using the appropriate
* {@link Arrays#sort(char[]) Arrays.sort} method. The algorithm
-     * requires a working space equal to the size of the original array.
+     * requires a working space equal to the size of the original array. The
+     * {@link java.util.concurrent.ForkJoinPool#commonPool() ForkJoin common
+     * pool} is used to execute any parallel tasks.
*
* @param a the array to be sorted
+     *
+     * @since 1.8
*/
public static void parallelSort(char[] a) {
int n = a.length, p, g;
@@ -522,17 +534,19 @@
}

/**
-     * Sorts the specified array into ascending numerical order. The range
-     * to be sorted extends from the index {@code fromIndex}, inclusive, to
-     * the index {@code toIndex}, exclusive. If {@code fromIndex == toIndex},
-     * the range to be sorted is empty.
-     *
-     * <p>Implementation note: The sorting algorithm is a parallel sort-merge
-     * that breaks the array into sub-arrays that are themselves sorted and then
-     * merged. When the sub-array length reaches a minimum granularity (currently
-     * {@value #MIN_ARRAY_SORT_GRAN}) the sub-array is sorted using the appropriate
+     * Sorts the specified range of the array into ascending numerical order.
+     * The range to be sorted extends from the index {@code fromIndex},
+     * inclusive, to the index {@code toIndex}, exclusive. If
+     * {@code fromIndex == toIndex}, the range to be sorted is empty.
+     *
+     * @implNote The sorting algorithm is a parallel sort-merge that breaks the
+     * array into sub-arrays that are themselves sorted and then merged. When
+     * the sub-array length reaches a minimum granularity (currently {@link
+     * #MIN_ARRAY_SORT_GRAN}) the sub-array is sorted using the appropriate
* {@link Arrays#sort(char[]) Arrays.sort} method. The algorithm
-     * requires a working space equal to the size of the original array.
+     * requires a working space equal to the size of the original array. The
+     * {@link java.util.concurrent.ForkJoinPool#commonPool() ForkJoin common
+     * pool} is used to execute any parallel tasks.
*
* @param a the array to be sorted
* @param fromIndex the index of the first element, inclusive, to be sorted
@@ -541,6 +555,8 @@
* @throws IllegalArgumentException if {@code fromIndex > toIndex}
* @throws ArrayIndexOutOfBoundsException
*     if {@code fromIndex < 0} or {@code toIndex > a.length}
+     *
+     * @since 1.8
*/
public static void parallelSort(char[] a, int fromIndex, int toIndex) {
rangeCheck(a.length, fromIndex, toIndex);
@@ -558,14 +574,18 @@
/**
* Sorts the specified array into ascending numerical order.
*
-     * <p>Implementation note: The sorting algorithm is a parallel sort-merge
-     * that breaks the array into sub-arrays that are themselves sorted and then
-     * merged. When the sub-array length reaches a minimum granularity (currently
-     * {@value #MIN_ARRAY_SORT_GRAN}) the sub-array is sorted using the appropriate
+     * @implNote The sorting algorithm is a parallel sort-merge that breaks the
+     * array into sub-arrays that are themselves sorted and then merged. When
+     * the sub-array length reaches a minimum granularity (currently {@link
+     * #MIN_ARRAY_SORT_GRAN}) the sub-array is sorted using the appropriate
* {@link Arrays#sort(short[]) Arrays.sort} method. The algorithm
-     * requires a working space equal to the size of the original array.
+     * requires a working space equal to the size of the original array. The
+     * {@link java.util.concurrent.ForkJoinPool#commonPool() ForkJoin common
+     * pool} is used to execute any parallel tasks.
*
* @param a the array to be sorted
+     *
+     * @since 1.8
*/
public static void parallelSort(short[] a) {
int n = a.length, p, g;
@@ -580,17 +600,19 @@
}

/**
-     * Sorts the specified array into ascending numerical order. The range
-     * to be sorted extends from the index {@code fromIndex}, inclusive, to
-     * the index {@code toIndex}, exclusive. If {@code fromIndex == toIndex},
-     * the range to be sorted is empty.
-     *
-     * <p>Implementation note: The sorting algorithm is a parallel sort-merge
-     * that breaks the array into sub-arrays that are themselves sorted and then
-     * merged. When the sub-array length reaches a minimum granularity (currently
-     * {@value #MIN_ARRAY_SORT_GRAN}) the sub-array is sorted using the appropriate
+     * Sorts the specified range of the array into ascending numerical order.
+     * The range to be sorted extends from the index {@code fromIndex},
+     * inclusive, to the index {@code toIndex}, exclusive. If
+     * {@code fromIndex == toIndex}, the range to be sorted is empty.
+     *
+     * @implNote The sorting algorithm is a parallel sort-merge that breaks the
+     * array into sub-arrays that are themselves sorted and then merged. When
+     * the sub-array length reaches a minimum granularity (currently {@link
+     * #MIN_ARRAY_SORT_GRAN}) the sub-array is sorted using the appropriate
* {@link Arrays#sort(short[]) Arrays.sort} method. The algorithm
-     * requires a working space equal to the size of the original array.
+     * requires a working space equal to the size of the original array. The
+     * {@link java.util.concurrent.ForkJoinPool#commonPool() ForkJoin common
+     * pool} is used to execute any parallel tasks.
*
* @param a the array to be sorted
* @param fromIndex the index of the first element, inclusive, to be sorted
@@ -599,6 +621,8 @@
* @throws IllegalArgumentException if {@code fromIndex > toIndex}
* @throws ArrayIndexOutOfBoundsException
*     if {@code fromIndex < 0} or {@code toIndex > a.length}
+     *
+     * @since 1.8
*/
public static void parallelSort(short[] a, int fromIndex, int toIndex) {
rangeCheck(a.length, fromIndex, toIndex);
@@ -616,14 +640,18 @@
/**
* Sorts the specified array into ascending numerical order.
*
-     * <p>Implementation note: The sorting algorithm is a parallel sort-merge
-     * that breaks the array into sub-arrays that are themselves sorted and then
-     * merged. When the sub-array length reaches a minimum granularity (currently
-     * {@value #MIN_ARRAY_SORT_GRAN}) the sub-array is sorted using the appropriate
+     * @implNote The sorting algorithm is a parallel sort-merge that breaks the
+     * array into sub-arrays that are themselves sorted and then merged. When
+     * the sub-array length reaches a minimum granularity (currently {@link
+     * #MIN_ARRAY_SORT_GRAN}) the sub-array is sorted using the appropriate
* {@link Arrays#sort(int[]) Arrays.sort} method. The algorithm
-     * requires a working space equal to the size of the original array.
+     * requires a working space equal to the size of the original array. The
+     * {@link java.util.concurrent.ForkJoinPool#commonPool() ForkJoin common
+     * pool} is used to execute any parallel tasks.
*
* @param a the array to be sorted
+     *
+     * @since 1.8
*/
public static void parallelSort(int[] a) {
int n = a.length, p, g;
@@ -638,17 +666,19 @@
}

/**
-     * Sorts the specified array into ascending numerical order. The range
-     * to be sorted extends from the index {@code fromIndex}, inclusive, to
-     * the index {@code toIndex}, exclusive. If {@code fromIndex == toIndex},
-     * the range to be sorted is empty.
-     *
-     * <p>Implementation note: The sorting algorithm is a parallel sort-merge
-     * that breaks the array into sub-arrays that are themselves sorted and then
-     * merged. When the sub-array length reaches a minimum granularity (currently
-     * {@value #MIN_ARRAY_SORT_GRAN}) the sub-array is sorted using the appropriate
+     * Sorts the specified range of the array into ascending numerical order.
+     * The range to be sorted extends from the index {@code fromIndex},
+     * inclusive, to the index {@code toIndex}, exclusive. If
+     * {@code fromIndex == toIndex}, the range to be sorted is empty.
+     *
+     * @implNote The sorting algorithm is a parallel sort-merge that breaks the
+     * array into sub-arrays that are themselves sorted and then merged. When
+     * the sub-array length reaches a minimum granularity (currently {@link
+     * #MIN_ARRAY_SORT_GRAN}) the sub-array is sorted using the appropriate
* {@link Arrays#sort(int[]) Arrays.sort} method. The algorithm
-     * requires a working space equal to the size of the original array.
+     * requires a working space equal to the size of the original array. The
+     * {@link java.util.concurrent.ForkJoinPool#commonPool() ForkJoin common
+     * pool} is used to execute any parallel tasks.
*
* @param a the array to be sorted
* @param fromIndex the index of the first element, inclusive, to be sorted
@@ -657,6 +687,8 @@
* @throws IllegalArgumentException if {@code fromIndex > toIndex}
* @throws ArrayIndexOutOfBoundsException
*     if {@code fromIndex < 0} or {@code toIndex > a.length}
+     *
+     * @since 1.8
*/
public static void parallelSort(int[] a, int fromIndex, int toIndex) {
rangeCheck(a.length, fromIndex, toIndex);
@@ -674,14 +706,18 @@
/**
* Sorts the specified array into ascending numerical order.
*
-     * <p>Implementation note: The sorting algorithm is a parallel sort-merge
-     * that breaks the array into sub-arrays that are themselves sorted and then
-     * merged. When the sub-array length reaches a minimum granularity (currently
-     * {@value #MIN_ARRAY_SORT_GRAN}) the sub-array is sorted using the appropriate
+     * @implNote The sorting algorithm is a parallel sort-merge that breaks the
+     * array into sub-arrays that are themselves sorted and then merged. When
+     * the sub-array length reaches a minimum granularity (currently {@link
+     * #MIN_ARRAY_SORT_GRAN}) the sub-array is sorted using the appropriate
* {@link Arrays#sort(long[]) Arrays.sort} method. The algorithm
-     * requires a working space equal to the size of the original array.
+     * requires a working space equal to the size of the original array. The
+     * {@link java.util.concurrent.ForkJoinPool#commonPool() ForkJoin common
+     * pool} is used to execute any parallel tasks.
*
* @param a the array to be sorted
+     *
+     * @since 1.8
*/
public static void parallelSort(long[] a) {
int n = a.length, p, g;
@@ -696,17 +732,19 @@
}

/**
-     * Sorts the specified array into ascending numerical order. The range
-     * to be sorted extends from the index {@code fromIndex}, inclusive, to
-     * the index {@code toIndex}, exclusive. If {@code fromIndex == toIndex},
-     * the range to be sorted is empty.
-     *
-     * <p>Implementation note: The sorting algorithm is a parallel sort-merge
-     * that breaks the array into sub-arrays that are themselves sorted and then
-     * merged. When the sub-array length reaches a minimum granularity (currently
-     * {@value #MIN_ARRAY_SORT_GRAN}) the sub-array is sorted using the appropriate
+     * Sorts the specified range of the array into ascending numerical order.
+     * The range to be sorted extends from the index {@code fromIndex},
+     * inclusive, to the index {@code toIndex}, exclusive. If
+     * {@code fromIndex == toIndex}, the range to be sorted is empty.
+     *
+     * @implNote The sorting algorithm is a parallel sort-merge that breaks the
+     * array into sub-arrays that are themselves sorted and then merged. When
+     * the sub-array length reaches a minimum granularity (currently {@link
+     * #MIN_ARRAY_SORT_GRAN}) the sub-array is sorted using the appropriate
* {@link Arrays#sort(long[]) Arrays.sort} method. The algorithm
-     * requires a working space equal to the size of the original array.
+     * requires a working space equal to the size of the original array. The
+     * {@link java.util.concurrent.ForkJoinPool#commonPool() ForkJoin common
+     * pool} is used to execute any parallel tasks.
*
* @param a the array to be sorted
* @param fromIndex the index of the first element, inclusive, to be sorted
@@ -715,6 +753,8 @@
* @throws IllegalArgumentException if {@code fromIndex > toIndex}
* @throws ArrayIndexOutOfBoundsException
*     if {@code fromIndex < 0} or {@code toIndex > a.length}
+     *
+     * @since 1.8
*/
public static void parallelSort(long[] a, int fromIndex, int toIndex) {
rangeCheck(a.length, fromIndex, toIndex);
@@ -740,14 +780,18 @@
* {@code 0.0f} and {@code Float.NaN} is considered greater than any
* other value and all {@code Float.NaN} values are considered equal.
*
-     * <p>Implementation note: The sorting algorithm is a parallel sort-merge
-     * that breaks the array into sub-arrays that are themselves sorted and then
-     * merged. When the sub-array length reaches a minimum granularity (currently
-     * {@value #MIN_ARRAY_SORT_GRAN}) the sub-array is sorted using the appropriate
+     * @implNote The sorting algorithm is a parallel sort-merge that breaks the
+     * array into sub-arrays that are themselves sorted and then merged. When
+     * the sub-array length reaches a minimum granularity (currently {@link
+     * #MIN_ARRAY_SORT_GRAN}) the sub-array is sorted using the appropriate
* {@link Arrays#sort(float[]) Arrays.sort} method. The algorithm
-     * requires a working space equal to the size of the original array.
+     * requires a working space equal to the size of the original array. The
+     * {@link java.util.concurrent.ForkJoinPool#commonPool() ForkJoin common
+     * pool} is used to execute any parallel tasks.
*
* @param a the array to be sorted
+     *
+     * @since 1.8
*/
public static void parallelSort(float[] a) {
int n = a.length, p, g;
@@ -762,10 +806,10 @@
}

/**
-     * Sorts the specified array into ascending numerical order. The range
-     * to be sorted extends from the index {@code fromIndex}, inclusive, to
-     * the index {@code toIndex}, exclusive. If {@code fromIndex == toIndex},
-     * the range to be sorted is empty.
+     * Sorts the specified range of the array into ascending numerical order.
+     * The range to be sorted extends from the index {@code fromIndex},
+     * inclusive, to the index {@code toIndex}, exclusive. If
+     * {@code fromIndex == toIndex}, the range to be sorted is empty.
*
* <p>The {@code <} relation does not provide a total order on all float
* values: {@code -0.0f == 0.0f} is {@code true} and a {@code Float.NaN}
@@ -775,12 +819,14 @@
* {@code 0.0f} and {@code Float.NaN} is considered greater than any
* other value and all {@code Float.NaN} values are considered equal.
*
-     * <p>Implementation note: The sorting algorithm is a parallel sort-merge
-     * that breaks the array into sub-arrays that are themselves sorted and then
-     * merged. When the sub-array length reaches a minimum granularity (currently
-     * {@value #MIN_ARRAY_SORT_GRAN}) the sub-array is sorted using the appropriate
+     * @implNote The sorting algorithm is a parallel sort-merge that breaks the
+     * array into sub-arrays that are themselves sorted and then merged. When
+     * the sub-array length reaches a minimum granularity (currently {@link
+     * #MIN_ARRAY_SORT_GRAN}) the sub-array is sorted using the appropriate
* {@link Arrays#sort(float[]) Arrays.sort} method. The algorithm
-     * requires a working space equal to the size of the original array.
+     * requires a working space equal to the size of the original array. The
+     * {@link java.util.concurrent.ForkJoinPool#commonPool() ForkJoin common
+     * pool} is used to execute any parallel tasks.
*
* @param a the array to be sorted
* @param fromIndex the index of the first element, inclusive, to be sorted
@@ -789,6 +835,8 @@
* @throws IllegalArgumentException if {@code fromIndex > toIndex}
* @throws ArrayIndexOutOfBoundsException
*     if {@code fromIndex < 0} or {@code toIndex > a.length}
+     *
+     * @since 1.8
*/
public static void parallelSort(float[] a, int fromIndex, int toIndex) {
rangeCheck(a.length, fromIndex, toIndex);
@@ -814,14 +862,18 @@
* {@code 0.0d} and {@code Double.NaN} is considered greater than any
* other value and all {@code Double.NaN} values are considered equal.
*
-     * <p>Implementation note: The sorting algorithm is a parallel sort-merge
-     * that breaks the array into sub-arrays that are themselves sorted and then
-     * merged. When the sub-array length reaches a minimum granularity (currently
-     * {@value #MIN_ARRAY_SORT_GRAN}) the sub-array is sorted using the appropriate
+     * @implNote The sorting algorithm is a parallel sort-merge that breaks the
+     * array into sub-arrays that are themselves sorted and then merged. When
+     * the sub-array length reaches a minimum granularity(currently {@link
+     * #MIN_ARRAY_SORT_GRAN}) the sub-array is sorted using the appropriate
* {@link Arrays#sort(double[]) Arrays.sort} method. The algorithm
-     * requires a working space equal to the size of the original array.
+     * requires a working space equal to the size of the original array. The
+     * {@link java.util.concurrent.ForkJoinPool#commonPool() ForkJoin common
+     * pool} is used to execute any parallel tasks.
*
* @param a the array to be sorted
+     *
+     * @since 1.8
*/
public static void parallelSort(double[] a) {
int n = a.length, p, g;
@@ -836,10 +888,10 @@
}

/**
-     * Sorts the specified array into ascending numerical order. The range
-     * to be sorted extends from the index {@code fromIndex}, inclusive, to
-     * the index {@code toIndex}, exclusive. If {@code fromIndex == toIndex},
-     * the range to be sorted is empty.
+     * Sorts the specified range of the array into ascending numerical order.
+     * The range to be sorted extends from the index {@code fromIndex},
+     * inclusive, to the index {@code toIndex}, exclusive. If
+     * {@code fromIndex == toIndex}, the range to be sorted is empty.
*
* <p>The {@code <} relation does not provide a total order on all double
* values: {@code -0.0d == 0.0d} is {@code true} and a {@code Double.NaN}
@@ -849,12 +901,14 @@
* {@code 0.0d} and {@code Double.NaN} is considered greater than any
* other value and all {@code Double.NaN} values are considered equal.
*
-     * <p>Implementation note: The sorting algorithm is a parallel sort-merge
-     * that breaks the array into sub-arrays that are themselves sorted and then
-     * merged. When the sub-array length reaches a minimum granularity (currently
-     * {@value #MIN_ARRAY_SORT_GRAN}) the sub-array is sorted using the appropriate
+     * @implNote The sorting algorithm is a parallel sort-merge that breaks the
+     * array into sub-arrays that are themselves sorted and then merged. When
+     * the sub-array length reaches a minimum granularity (currently {@link
+     * #MIN_ARRAY_SORT_GRAN}) the sub-array is sorted using the appropriate
* {@link Arrays#sort(double[]) Arrays.sort} method. The algorithm
-     * requires a working space equal to the size of the original array.
+     * requires a working space equal to the size of the original array. The
+     * {@link java.util.concurrent.ForkJoinPool#commonPool() ForkJoin common
+     * pool} is used to execute any parallel tasks.
*
* @param a the array to be sorted
* @param fromIndex the index of the first element, inclusive, to be sorted
@@ -863,6 +917,8 @@
* @throws IllegalArgumentException if {@code fromIndex > toIndex}
* @throws ArrayIndexOutOfBoundsException
*     if {@code fromIndex < 0} or {@code toIndex > a.length}
+     *
+     * @since 1.8
*/
public static void parallelSort(double[] a, int fromIndex, int toIndex) {
rangeCheck(a.length, fromIndex, toIndex);
@@ -889,12 +945,14 @@
* <p>This sort is guaranteed to be <i>stable</i>:  equal elements will
* not be reordered as a result of the sort.
*
-     * <p>Implementation note: The sorting algorithm is a parallel sort-merge
-     * that breaks the array into sub-arrays that are themselves sorted and then
-     * merged. When the sub-array length reaches a minimum granularity (currently
-     * {@value #MIN_ARRAY_SORT_GRAN}) the sub-array is sorted using the appropriate
+     * @implNote The sorting algorithm is a parallel sort-merge that breaks the
+     * array into sub-arrays that are themselves sorted and then merged. When
+     * the sub-array length reaches a minimum granularity (currently {@link
+     * #MIN_ARRAY_SORT_GRAN}) the sub-array is sorted using the appropriate
* {@link Arrays#sort(Object[]) Arrays.sort} method. The algorithm
-     * requires a working space equal to the size of the original array.
+     * requires a working space equal to the size of the original array. The
+     * {@link java.util.concurrent.ForkJoinPool#commonPool() ForkJoin common
+     * pool} is used to execute any parallel tasks.
*
* @param a the array to be sorted
*
@@ -903,6 +961,8 @@
* @throws IllegalArgumentException (optional) if the natural
*         ordering of the array elements is found to violate the
+     *
+     * @since 1.8
*/
@SuppressWarnings("unchecked")
public static <T extends Comparable<? super T>> void parallelSort(T[] a) {
@@ -934,15 +994,14 @@
* <p>This sort is guaranteed to be <i>stable</i>:  equal elements will
* not be reordered as a result of the sort.
*
-     * This method will cause initialization of the
-     * default {@code ForkJoinPool} if necessary.
-     *
-     * <p>Implementation note: The sorting algorithm is a parallel sort-merge
-     * that breaks the array into sub-arrays that are themselves sorted and then
-     * merged. When the sub-array length reaches a minimum granularity (currently
-     * {@value #MIN_ARRAY_SORT_GRAN}) the sub-array is sorted using the appropriate
+     * @implNote The sorting algorithm is a parallel sort-merge that breaks the
+     * array into sub-arrays that are themselves sorted and then merged. When
+     * the sub-array length reaches a minimum granularity (currently {@link
+     * #MIN_ARRAY_SORT_GRAN}) the sub-array is sorted using the appropriate
* {@link Arrays#sort(Object[]) Arrays.sort} method. The algorithm
-     * requires a working space equal to the size of the original array.
+     * requires a working space equal to the size of the original array. The
+     * {@link java.util.concurrent.ForkJoinPool#commonPool() ForkJoin common
+     * pool} is used to execute any parallel tasks.
*
* @param a the array to be sorted
* @param fromIndex the index of the first element (inclusive) to be
@@ -956,6 +1015,8 @@
* @throws ClassCastException if the array contains elements that are
*         not <i>mutually comparable</i> (for example, strings and
*         integers).
+     *
+     * @since 1.8
*/
@SuppressWarnings("unchecked")
public static <T extends Comparable<? super T>>
@@ -983,12 +1044,14 @@
* <p>This sort is guaranteed to be <i>stable</i>:  equal elements will
* not be reordered as a result of the sort.
*
-     * <p>Implementation note: The sorting algorithm is a parallel sort-merge
-     * that breaks the array into sub-arrays that are themselves sorted and then
-     * merged. When the sub-array length reaches a minimum granularity (currently
-     * {@value #MIN_ARRAY_SORT_GRAN}) the sub-array is sorted using the appropriate
-     * {@link Arrays#sort(Object[], java.util.Comparator) Arrays.sort} method. The algorithm
-     * requires a working space equal to the size of the original array.
+     * @implNote The sorting algorithm is a parallel sort-merge that breaks the
+     * array into sub-arrays that are themselves sorted and then merged. When
+     * the sub-array length reaches a minimum granularity (currently {@link
+     * #MIN_ARRAY_SORT_GRAN}) the sub-array is sorted using the appropriate
+     * {@link Arrays#sort(Object[], java.util.Comparator) Arrays.sort} method.
+     * The algorithm requires a working space equal to the size of the original
+     * array. The {@link java.util.concurrent.ForkJoinPool#commonPool() ForkJoin
+     * common pool} is used to execute any parallel tasks.
*
* @param a the array to be sorted
* @param cmp the comparator to determine the order of the array.  A
@@ -998,6 +1061,8 @@
*         not <i>mutually comparable</i> using the specified comparator
* @throws IllegalArgumentException (optional) if the comparator is
*         found to violate the {@link java.util.Comparator} contract
+     *
+     * @since 1.8
*/
@SuppressWarnings("unchecked")
public static <T> void parallelSort(T[] a, Comparator<? super T> cmp) {
@@ -1028,12 +1093,15 @@
* <p>This sort is guaranteed to be <i>stable</i>:  equal elements will
* not be reordered as a result of the sort.
*
-     * <p>Implementation note: The sorting algorithm is a parallel sort-merge
-     * that breaks the array into sub-arrays that are themselves sorted and then
-     * merged. When the sub-array length reaches a minimum granularity (currently
-     * {@value #MIN_ARRAY_SORT_GRAN}) the sub-array is sorted using the appropriate
-     * {@link Arrays#sort(Object[], int, int, java.util.Comparator) Arrays.sort} method. The algorithm
-     * requires a working space equal to the size of the original array.
+     * @implNote The sorting algorithm is a parallel sort-merge that breaks the
+     * array into sub-arrays that are themselves sorted and then merged. When
+     * the sub-array length reaches a minimum granularity (currently {@link
+     * #MIN_ARRAY_SORT_GRAN}) the sub-array is sorted using the appropriate
+     * {@link Arrays#sort(Object[], int, int, java.util.Comparator) Arrays.sort}
+     * method. The algorithm requires a working space equal to the size of the
+     * original array. The {@link
+     * java.util.concurrent.ForkJoinPool#commonPool() ForkJoin common pool} is
+     * used to execute any parallel tasks.
*
* @param a the array to be sorted
* @param fromIndex the index of the first element (inclusive) to be
@@ -1050,6 +1118,8 @@
* @throws ClassCastException if the array contains elements that are
*         not <i>mutually comparable</i> (for example, strings and
*         integers).
+     *
+     * @since 1.8
*/
@SuppressWarnings("unchecked")
public static <T> void parallelSort(T[] a, int fromIndex, int toIndex,```
```--- a/test/java/util/Arrays/ParallelSorting.java	Mon May 06 18:39:53 2013 +0200
+++ b/test/java/util/Arrays/ParallelSorting.java	Tue May 07 16:17:05 2013 +0200
@@ -50,11 +50,11 @@

// Array lengths used in a long run (default)
private static final int[] LONG_RUN_LENGTHS = {
-        1, 2, 3, 5, 8, 13, 21, 34, 55, 100, 1000, 10000, 100000, 1000000 };
+        1000, 10000, 100000, 1000000 };

// Array lengths used in a short run
private static final int[] SHORT_RUN_LENGTHS = {
-        1, 2, 3, 21, 55, 1000, 10000 };
+        5000, 9000, 10000, 12000 };

// Random initial values used in a long run (default)
private static final long[] LONG_RUN_RANDOMS = { 666, 0xC0FFEE, 999 };```