1 package kotlinx.coroutines 2 3 /** 4 * A job that can be completed using [complete()] function. 5 * It is returned by [Job()][Job] and [SupervisorJob()][SupervisorJob] constructor functions. 6 * 7 * All functions on this interface are **thread-safe** and can 8 * be safely invoked from concurrent coroutines without external synchronization. 9 * 10 * **The `CompletableJob` interface is not stable for inheritance in 3rd party libraries**, 11 * as new methods might be added to this interface in the future, but is stable for use. 12 */ 13 public interface CompletableJob : Job { 14 /** 15 * Completes this job. The result is `true` if this job was completed as a result of this invocation and 16 * `false` otherwise (if it was already completed). 17 * 18 * Subsequent invocations of this function have no effect and always produce `false`. 19 * 20 * This function transitions this job into _completed_ state if it was not completed or cancelled yet. 21 * However, that if this job has children, then it transitions into _completing_ state and becomes _complete_ 22 * once all its children are [complete][isCompleted]. See [Job] for details. 23 */ completenull24 public fun complete(): Boolean 25 26 /** 27 * Completes this job exceptionally with a given [exception]. The result is `true` if this job was 28 * completed as a result of this invocation and `false` otherwise (if it was already completed). 29 * [exception] parameter is used as an additional debug information that is not handled by any exception handlers. 30 * 31 * Subsequent invocations of this function have no effect and always produce `false`. 32 * 33 * This function transitions this job into _cancelled_ state if it was not completed or cancelled yet. 34 * However, that if this job has children, then it transitions into _cancelling_ state and becomes _cancelled_ 35 * once all its children are [complete][isCompleted]. See [Job] for details. 36 * 37 * Its responsibility of the caller to properly handle and report the given [exception], all job's children will receive 38 * a [CancellationException] with the [exception] as a cause for the sake of diagnostic. 39 */ 40 public fun completeExceptionally(exception: Throwable): Boolean 41 } 42