future-cancelled? docstring - is future dead or only perhaps-dead?
The future-cancelled? docstring says only, "Returns true if future f is cancelled". In combination with the docstring of future-cancel, which says only "Cancels the future, if possible", it isn't clear what is meant by future-cancelled?. Does it mean merely that cancellation was requested (via future-cancel) or that cancellation was actually achieved (the fn either had not begun and was removed from the schedule, or was cut short while running)? Looking at the source code (.isCancelled f) and consulting the Javadoc, I am still not absolutely certain, but I lean toward the latter: actually cut short or removed from the schedule. Would it also be true of Clojure-CLR? The docstring should be clearer about what Clojure guarantees.
Comment made by: pbwolf
Currently, the two docstrings use "cancel" to mean two different things, creating the impression that future-cancelled? reflects the state of the future'd work instead of the state of the future:
Cancels the future, if possible.
clearly means "cancel" applies to the future'd work, because cancellation might not happen. On the other hand, with that interpretation
Returns true if future f is cancelled
means that the work did not complete or will be skipped.
The contradiction could be resolved by clarifying the future-cancelled? docstring to refer to whether cancellation had been requested, e.g., future-cancel had been called.
It means that cancellation was requested. There is no safe way in Java to forcibly terminate the work on a background thread, so it's not possible to make any guarantees. I don't think there's anything more that's useful that we can say in the docstring.