Deprecate and remove Job.cancel(cause)

Job.cancel(any exception) is a cumbersome API:

• It has unclear semantics (especially after #333 fix, when cancel(cause) can return true more than once for the sake of exception handling)
• It shares a given exception between multiple coroutines which can mutate it
• It doesn’t provide any significant value from the user-facing API standpoint, because cancel can return false, forcing a user to handle an exception on the callsite anyway

As for implementation, it complicates Job exception handling a lot and has a lot of maintenance burden as opposed to Job.cancel() or Job.cancel(message: String)

We can remove cancel(cause) from public API and move it to attachChild machinery (e.g. by introducing ParentHandle instead of DisposableHandle). It should make parent-child communication (-> cancellation and exception handling) much simpler and open a door for state machine optimizations.

If someone has a use-case which cannot be reasonably implemented without cancellation with a custom exception, let’s discuss it here.

[qwwdfsad]

After discussion with @LouisCAD I’ve found at least one use-case which is hard to workaround: external callback-based API working as parent/owner of the job.

An example may be found here. In this example, CameraDevice (CameraDevice.StateCallback) actually owns the job and cancels it any (asynchronous) error occurred with that error. And it’s essential for a user to get this error on completion.await(), otherwise troubleshooting may be cumbersome.

Workaround without cancel(cause) requires to create one more Deferred and pass it as parent of the completion, but it makes code less readable

[qwwdfsad]

@elizarov note that completion is deferred returned by async call, it’s not a CompletableDeferred instance and has no completeWithException.

IMO having complete* family on Deferred is a bad idea as we have seen in CompletableFuture API