Huh. I had assumed that "success" was the usual name for this, but I can't find it anywhere in the Future docs. The closest term used there is "completed normally," used in contrast to "an exception" and "cancellation": http://docs.oracle.com/javase/8/docs/api/java/util/concurrent/Future.html#isDone-- But other parts of the doc seem to consider there to be only two cases, "completed normally" and "cancelled," suggesting that "an exception" is a kind of "completed normally."
It would be super-confusing for "success" to mean anything other than "completed without throwing", so the meaning of "success" is relatively obvous. But it would be better if docs like in FutureCallback replaced
Invoked with the result of the {@code Future} computation when it is
successful.
with
Invoked with the result of the {@code Future} computation when it completes
normally.
or even more pedantically
Invoked with the result of the {@code Future} computation if and when it completes normally (that is, without throwing an exception).
I'm still conflicted about this, given that "completed normally" is slightly ambiguous. Perhaps we could define "success" in our package-info and link to that? But mostly I'm just having trouble prioritizing this above other issues.
From an internal discussion:
Huh. I had assumed that "success" was the usual name for this, but I can't find it anywhere in the Future docs. The closest term used there is "completed normally," used in contrast to "an exception" and "cancellation": http://docs.oracle.com/javase/8/docs/api/java/util/concurrent/Future.html#isDone-- But other parts of the doc seem to consider there to be only two cases, "completed normally" and "cancelled," suggesting that "an exception" is a kind of "completed normally."
The word "success" is used throughout http://docs.oracle.com/javase/8/docs/api/java/util/concurrent/FutureTask.html
It would be super-confusing for "success" to mean anything other than "completed without throwing", so the meaning of "success" is relatively obvous. But it would be better if docs like in FutureCallback replaced
with
or even more pedantically
I'm still conflicted about this, given that "completed normally" is slightly ambiguous. Perhaps we could define "success" in our package-info and link to that? But mostly I'm just having trouble prioritizing this above other issues.
relevance: 1