What's the difference between a failed job and a job that has completed exceptionally?

Question

The docs seem to be saying they're the same. Is that a correct interpretation?

A coroutine job is said to complete exceptionally when its body throws an exception; a CompletableJob is completed exceptionally by calling CompletableJob.completeExceptionally. An exceptionally completed job is cancelled and the corresponding exception becomes the cancellation cause of the job.

Normal cancellation of a job is distinguished from its failure by the type of this exception that caused its cancellation. A coroutine that threw CancellationException is considered to be cancelled normally. If a cancellation cause is a different exception type, then the job is considered to have failed. When a job has failed, then its parent gets cancelled with the exception of the same type, thus ensuring transparency in delegating parts of the job to its children.

Answer 1

What I understood about the documentation is the following things :

• You have 2 types of jobs
  • Ones created by a launch that are Coroutine Jobs
    • Behavior of that jobs : when the code block given as parameter of launch is done, the job is complete
  • Ones created by the Job constructors that are CompletableJob
    • Behavior of that Job : complete when complete method is called

And now about the tricky part is about the end before completion of a job

Normal cancellation

• a job is cancelled (the documentation says normal cancellation)
  • implies that
    • the job execution continue until the next suspension
    • all children continue until the next suspension (and then move to the completed state)
    • and when all that done the job move to the cancelled state
    • Parent job receives the given exception and can managed it with invokeOnCompletion
    • the parent is not affected by his children normal cancellations (it is not completed and not cancelled)
  • we can can cancel a job
    • for a CompletableJob : call completeExceptionnally with a parameter that extends CancellationException or a CancellationException object
    • for a Coroutine Job : call cancel that waits a CancellationException parameter
    • Or we can also throw a CancellationException (but the job is immediately cancelled, code until the next suspension is not executed)

https://pl.kotl.in/HpSW-5Jgd?theme=darcula

Failure

• a job failed means that all the treatments attached to it failed
  • children, parents, cousins move to the Cancelling state
  • we can fail a job
    • for a CompletableJob : call completeExceptionnally with a parameter that NOT extends CancellationException
    • throw an exception that NOT extends CancellationException

https://pl.kotl.in/VzV1md3Wc

Answer

Then about your question :

• a failed job is the job had an exception that was not a CancellationException (second case)
• a completed exceptionally job is the job that has been failed or has been cancelled (can be the first or the second case)

https://pl.kotl.in/miTSI972L

Hope this helps :)