RFR doclint issues in j.u.concurrent
Chris Hegarty
chris.hegarty at oracle.com
Thu Jul 25 09:12:49 UTC 2013
These changes are already committed in the jsr166 CVS, this is a request
to pull them into jdk8.
With these changes all but CompletableFuture are doclint warning free.
There is a separate effort to overhaul CF, which will address the warnings.
diff -r fd1b5adcfdf0
src/share/classes/java/util/concurrent/AbstractExecutorService.java
---
a/src/share/classes/java/util/concurrent/AbstractExecutorService.java
Wed Jul 24 22:52:01 2013 +0100
+++
b/src/share/classes/java/util/concurrent/AbstractExecutorService.java
Thu Jul 25 10:04:28 2013 +0100
@@ -76,6 +76,7 @@ public abstract class AbstractExecutorSe
*
* @param runnable the runnable task being wrapped
* @param value the default value for the returned future
+ * @param <T> the type of the given value
* @return a {@code RunnableFuture} which, when run, will run the
* underlying runnable and which, as a {@code Future}, will yield
* the given value as its result and provide for cancellation of
@@ -90,6 +91,7 @@ public abstract class AbstractExecutorSe
* Returns a {@code RunnableFuture} for the given callable task.
*
* @param callable the callable task being wrapped
+ * @param <T> the type of the callable's result
* @return a {@code RunnableFuture} which, when run, will call the
* underlying callable and which, as a {@code Future}, will yield
* the callable's result as its result and provide for
diff -r fd1b5adcfdf0
src/share/classes/java/util/concurrent/ExecutorService.java
--- a/src/share/classes/java/util/concurrent/ExecutorService.java
Wed Jul 24 22:52:01 2013 +0100
+++ b/src/share/classes/java/util/concurrent/ExecutorService.java
Thu Jul 25 10:04:28 2013 +0100
@@ -227,6 +227,7 @@ public interface ExecutorService extends
* {@link Callable} form so they can be submitted.
*
* @param task the task to submit
+ * @param <T> the type of the task's result
* @return a Future representing pending completion of the task
* @throws RejectedExecutionException if the task cannot be
* scheduled for execution
@@ -241,6 +242,7 @@ public interface ExecutorService extends
*
* @param task the task to submit
* @param result the result to return
+ * @param <T> the type of the result
* @return a Future representing pending completion of the task
* @throws RejectedExecutionException if the task cannot be
* scheduled for execution
@@ -272,6 +274,7 @@ public interface ExecutorService extends
* collection is modified while this operation is in progress.
*
* @param tasks the collection of tasks
+ * @param <T> the type of the values returned from the tasks
* @return a list of Futures representing the tasks, in the same
* sequential order as produced by the iterator for the
* given task list, each of which has completed
@@ -299,6 +302,7 @@ public interface ExecutorService extends
* @param tasks the collection of tasks
* @param timeout the maximum time to wait
* @param unit the time unit of the timeout argument
+ * @param <T> the type of the values returned from the tasks
* @return a list of Futures representing the tasks, in the same
* sequential order as produced by the iterator for the
* given task list. If the operation did not time out,
@@ -324,6 +328,7 @@ public interface ExecutorService extends
* collection is modified while this operation is in progress.
*
* @param tasks the collection of tasks
+ * @param <T> the type of the values returned from the tasks
* @return the result returned by one of the tasks
* @throws InterruptedException if interrupted while waiting
* @throws NullPointerException if tasks or any element task
@@ -348,6 +353,7 @@ public interface ExecutorService extends
* @param tasks the collection of tasks
* @param timeout the maximum time to wait
* @param unit the time unit of the timeout argument
+ * @param <T> the type of the values returned from the tasks
* @return the result returned by one of the tasks
* @throws InterruptedException if interrupted while waiting
* @throws NullPointerException if tasks, or unit, or any element
diff -r fd1b5adcfdf0 src/share/classes/java/util/concurrent/Executors.java
--- a/src/share/classes/java/util/concurrent/Executors.java Wed Jul
24 22:52:01 2013 +0100
+++ b/src/share/classes/java/util/concurrent/Executors.java Thu Jul
25 10:04:28 2013 +0100
@@ -397,6 +397,7 @@ public class Executors {
* {@code Callable} to an otherwise resultless action.
* @param task the task to run
* @param result the result to return
+ * @param <T> the type of the result
* @return a callable object
* @throws NullPointerException if task null
*/
@@ -458,6 +459,7 @@ public class Executors {
* action; or if not possible, throw an associated {@link
* AccessControlException}.
* @param callable the underlying task
+ * @param <T> the type of the callable's result
* @return a callable object
* @throws NullPointerException if callable null
*/
@@ -480,6 +482,7 @@ public class Executors {
* AccessControlException}.
*
* @param callable the underlying task
+ * @param <T> the type of the callable's result
* @return a callable object
* @throws NullPointerException if callable null
* @throws AccessControlException if the current access control
diff -r fd1b5adcfdf0
src/share/classes/java/util/concurrent/ForkJoinPool.java
--- a/src/share/classes/java/util/concurrent/ForkJoinPool.java Wed Jul
24 22:52:01 2013 +0100
+++ b/src/share/classes/java/util/concurrent/ForkJoinPool.java Thu Jul
25 10:04:28 2013 +0100
@@ -561,8 +561,8 @@ public class ForkJoinPool extends Abstra
* Returns a new worker thread operating in the given pool.
*
* @param pool the pool this thread works in
+ * @return the new worker thread
* @throws NullPointerException if the pool is null
- * @return the new worker thread
*/
public ForkJoinWorkerThread newThread(ForkJoinPool pool);
}
@@ -2497,6 +2497,7 @@ public class ForkJoinPool extends Abstra
* minimally only the latter.
*
* @param task the task
+ * @param <T> the type of the task's result
* @return the task's result
* @throws NullPointerException if the task is null
* @throws RejectedExecutionException if the task cannot be
@@ -2545,6 +2546,7 @@ public class ForkJoinPool extends Abstra
* Submits a ForkJoinTask for execution.
*
* @param task the task to submit
+ * @param <T> the type of the task's result
* @return the task
* @throws NullPointerException if the task is null
* @throws RejectedExecutionException if the task cannot be
diff -r fd1b5adcfdf0
src/share/classes/java/util/concurrent/ForkJoinTask.java
--- a/src/share/classes/java/util/concurrent/ForkJoinTask.java Wed Jul
24 22:52:01 2013 +0100
+++ b/src/share/classes/java/util/concurrent/ForkJoinTask.java Thu Jul
25 10:04:28 2013 +0100
@@ -810,6 +810,7 @@ public abstract class ForkJoinTask<V> im
* unprocessed.
*
* @param tasks the collection of tasks
+ * @param <T> the type of the values returned from the tasks
* @return the tasks argument, to simplify usage
* @throws NullPointerException if tasks or any element are null
*/
@@ -1472,6 +1473,7 @@ public abstract class ForkJoinTask<V> im
*
* @param runnable the runnable action
* @param result the result upon completion
+ * @param <T> the type of the result
* @return the task
*/
public static <T> ForkJoinTask<T> adapt(Runnable runnable, T result) {
@@ -1485,6 +1487,7 @@ public abstract class ForkJoinTask<V> im
* encountered into {@code RuntimeException}.
*
* @param callable the callable action
+ * @param <T> the type of the callable's result
* @return the task
*/
public static <T> ForkJoinTask<T> adapt(Callable<? extends T>
callable) {
@@ -1498,6 +1501,8 @@ public abstract class ForkJoinTask<V> im
/**
* Saves this task to a stream (that is, serializes it).
*
+ * @param s the stream
+ * @throws java.io.IOException if an I/O error occurs
* @serialData the current run status and the exception thrown
* during execution, or {@code null} if none
*/
@@ -1509,6 +1514,10 @@ public abstract class ForkJoinTask<V> im
/**
* Reconstitutes this task from a stream (that is, deserializes it).
+ * @param s the stream
+ * @throws ClassNotFoundException if the class of a serialized object
+ * could not be found
+ * @throws java.io.IOException if an I/O error occurs
*/
private void readObject(java.io.ObjectInputStream s)
throws java.io.IOException, ClassNotFoundException {
diff -r fd1b5adcfdf0
src/share/classes/java/util/concurrent/ScheduledExecutorService.java
---
a/src/share/classes/java/util/concurrent/ScheduledExecutorService.java
Wed Jul 24 22:52:01 2013 +0100
+++
b/src/share/classes/java/util/concurrent/ScheduledExecutorService.java
Thu Jul 25 10:04:28 2013 +0100
@@ -117,6 +117,7 @@ public interface ScheduledExecutorServic
* @param callable the function to execute
* @param delay the time from now to delay execution
* @param unit the time unit of the delay parameter
+ * @param <V> the type of the callable's result
* @return a ScheduledFuture that can be used to extract result or
cancel
* @throws RejectedExecutionException if the task cannot be
* scheduled for execution
diff -r fd1b5adcfdf0
src/share/classes/java/util/concurrent/ScheduledThreadPoolExecutor.java
---
a/src/share/classes/java/util/concurrent/ScheduledThreadPoolExecutor.java
Wed Jul 24 22:52:01 2013 +0100
+++
b/src/share/classes/java/util/concurrent/ScheduledThreadPoolExecutor.java
Thu Jul 25 10:04:28 2013 +0100
@@ -392,6 +392,7 @@ public class ScheduledThreadPoolExecutor
*
* @param runnable the submitted Runnable
* @param task the task created to execute the runnable
+ * @param <V> the type of the task's result
* @return a task that can execute the runnable
* @since 1.6
*/
@@ -408,6 +409,7 @@ public class ScheduledThreadPoolExecutor
*
* @param callable the submitted Callable
* @param task the task created to execute the callable
+ * @param <V> the type of the task's result
* @return a task that can execute the callable
* @since 1.6
*/
diff -r fd1b5adcfdf0 src/share/classes/java/util/concurrent/TimeUnit.java
--- a/src/share/classes/java/util/concurrent/TimeUnit.java Wed Jul
24 22:52:01 2013 +0100
+++ b/src/share/classes/java/util/concurrent/TimeUnit.java Thu Jul
25 10:04:28 2013 +0100
@@ -69,6 +69,9 @@ package java.util.concurrent;
* @author Doug Lea
*/
public enum TimeUnit {
+ /**
+ * Time unit representing one thousandth of a microsecond
+ */
NANOSECONDS {
public long toNanos(long d) { return d; }
public long toMicros(long d) { return d/(C1/C0); }
@@ -80,6 +83,10 @@ public enum TimeUnit {
public long convert(long d, TimeUnit u) { return u.toNanos(d); }
int excessNanos(long d, long m) { return (int)(d - (m*C2)); }
},
+
+ /**
+ * Time unit representing one thousandth of a millisecond
+ */
MICROSECONDS {
public long toNanos(long d) { return x(d, C1/C0, MAX/(C1/C0)); }
public long toMicros(long d) { return d; }
@@ -91,6 +98,10 @@ public enum TimeUnit {
public long convert(long d, TimeUnit u) { return u.toMicros(d); }
int excessNanos(long d, long m) { return (int)((d*C1) - (m*C2)); }
},
+
+ /**
+ * Time unit representing one thousandth of a second
+ */
MILLISECONDS {
public long toNanos(long d) { return x(d, C2/C0, MAX/(C2/C0)); }
public long toMicros(long d) { return x(d, C2/C1, MAX/(C2/C1)); }
@@ -102,6 +113,10 @@ public enum TimeUnit {
public long convert(long d, TimeUnit u) { return u.toMillis(d); }
int excessNanos(long d, long m) { return 0; }
},
+
+ /**
+ * Time unit representing one second
+ */
SECONDS {
public long toNanos(long d) { return x(d, C3/C0, MAX/(C3/C0)); }
public long toMicros(long d) { return x(d, C3/C1, MAX/(C3/C1)); }
@@ -113,6 +128,10 @@ public enum TimeUnit {
public long convert(long d, TimeUnit u) { return u.toSeconds(d); }
int excessNanos(long d, long m) { return 0; }
},
+
+ /**
+ * Time unit representing sixty seconds
+ */
MINUTES {
public long toNanos(long d) { return x(d, C4/C0, MAX/(C4/C0)); }
public long toMicros(long d) { return x(d, C4/C1, MAX/(C4/C1)); }
@@ -124,6 +143,10 @@ public enum TimeUnit {
public long convert(long d, TimeUnit u) { return u.toMinutes(d); }
int excessNanos(long d, long m) { return 0; }
},
+
+ /**
+ * Time unit representing sixty minutes
+ */
HOURS {
public long toNanos(long d) { return x(d, C5/C0, MAX/(C5/C0)); }
public long toMicros(long d) { return x(d, C5/C1, MAX/(C5/C1)); }
@@ -135,6 +158,10 @@ public enum TimeUnit {
public long convert(long d, TimeUnit u) { return u.toHours(d); }
int excessNanos(long d, long m) { return 0; }
},
+
+ /**
+ * Time unit representing twenty four hours
+ */
DAYS {
public long toNanos(long d) { return x(d, C6/C0, MAX/(C6/C0)); }
public long toMicros(long d) { return x(d, C6/C1, MAX/(C6/C1)); }
-Chris.
More information about the core-libs-dev
mailing list