Clarify the meaning of "success" of a Future

[GoogleCodeExporter]

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 

   * 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.

Original issue reported on code.google.com by cpov...@google.com on 17 Oct 2014 at 6:12

[GoogleCodeExporter]

This issue has been migrated to GitHub.

It can be found at https://github.com/google/guava/issues/<issue id>

Original comment by cgdecker@google.com on 1 Nov 2014 at 4:08

• Added labels: MigratedToGitHub

[GoogleCodeExporter]

Original comment by cgdecker@google.com on 1 Nov 2014 at 4:17

• Changed state: Migrated

[GoogleCodeExporter]

Original comment by cgdecker@google.com on 3 Nov 2014 at 9:07

• Added labels: Restrict-AddIssueComment-Commit