future-cancelled? docstring - is future dead or only perhaps-dead?

Description

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.

Environment

None

Activity

Show:
import
February 6, 2019, 10:03 AM

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.

Alex Miller
February 2, 2019, 4:32 PM

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.

Declined
Your pinned fields
Click on the next to a field label to start pinning.

Assignee

Unassigned

Reporter

import

Priority

Minor

Affects versions