1 /* 2 * Copyright 2016-2020 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. 3 */ 4 @file:Suppress("DEPRECATION_ERROR") 5 6 package kotlinx.coroutines 7 8 import kotlinx.coroutines.selects.* 9 import kotlin.coroutines.* 10 11 /** 12 * A non-cancelable job that is always [active][Job.isActive]. It is designed for [withContext] function 13 * to prevent cancellation of code blocks that need to be executed without cancellation. 14 * 15 * Use it like this: 16 * ``` 17 * withContext(NonCancellable) { 18 * // this code will not be cancelled 19 * } 20 * ``` 21 */ 22 public object NonCancellable : AbstractCoroutineContextElement(Job), Job { 23 /** 24 * Always returns `true`. 25 * @suppress **This an internal API and should not be used from general code.** 26 */ 27 @InternalCoroutinesApi 28 override val isActive: Boolean get() = true 29 30 /** 31 * Always returns `false`. 32 * @suppress **This an internal API and should not be used from general code.** 33 */ 34 @InternalCoroutinesApi 35 override val isCompleted: Boolean get() = false 36 37 /** 38 * Always returns `false`. 39 * @suppress **This an internal API and should not be used from general code.** 40 */ 41 @InternalCoroutinesApi 42 override val isCancelled: Boolean get() = false 43 44 /** 45 * Always returns `false`. 46 * @suppress **This an internal API and should not be used from general code.** 47 */ 48 @InternalCoroutinesApi startnull49 override fun start(): Boolean = false 50 51 /** 52 * Always throws [UnsupportedOperationException]. 53 * @suppress **This an internal API and should not be used from general code.** 54 */ 55 @InternalCoroutinesApi 56 override suspend fun join() { 57 throw UnsupportedOperationException("This job is always active") 58 } 59 60 /** 61 * Always throws [UnsupportedOperationException]. 62 * @suppress **This an internal API and should not be used from general code.** 63 */ 64 override val onJoin: SelectClause0 65 get() = throw UnsupportedOperationException("This job is always active") 66 67 /** 68 * Always throws [IllegalStateException]. 69 * @suppress **This an internal API and should not be used from general code.** 70 */ 71 @InternalCoroutinesApi getCancellationExceptionnull72 override fun getCancellationException(): CancellationException = throw IllegalStateException("This job is always active") 73 74 /** 75 * @suppress **This an internal API and should not be used from general code.** 76 */ 77 @Suppress("OverridingDeprecatedMember") 78 @InternalCoroutinesApi 79 override fun invokeOnCompletion(handler: CompletionHandler): DisposableHandle = 80 NonDisposableHandle 81 82 /** 83 * Always returns no-op handle. 84 * @suppress **This an internal API and should not be used from general code.** 85 */ 86 @InternalCoroutinesApi 87 override fun invokeOnCompletion(onCancelling: Boolean, invokeImmediately: Boolean, handler: CompletionHandler): DisposableHandle = 88 NonDisposableHandle 89 90 /** 91 * Does nothing. 92 * @suppress **This an internal API and should not be used from general code.** 93 */ 94 @InternalCoroutinesApi 95 override fun cancel(cause: CancellationException?) {} 96 97 /** 98 * Always returns `false`. 99 * @suppress This method has bad semantics when cause is not a [CancellationException]. Use [cancel]. 100 */ 101 @Deprecated(level = DeprecationLevel.HIDDEN, message = "Since 1.2.0, binary compatibility with versions <= 1.1.x") cancelnull102 override fun cancel(cause: Throwable?): Boolean = false // never handles exceptions 103 104 /** 105 * Always returns [emptySequence]. 106 * @suppress **This an internal API and should not be used from general code.** 107 */ 108 @InternalCoroutinesApi 109 override val children: Sequence<Job> 110 get() = emptySequence() 111 112 /** 113 * Always returns [NonDisposableHandle] and does not do anything. 114 * @suppress **This an internal API and should not be used from general code.** 115 */ 116 @InternalCoroutinesApi 117 override fun attachChild(child: ChildJob): ChildHandle = NonDisposableHandle 118 119 /** @suppress */ 120 override fun toString(): String { 121 return "NonCancellable" 122 } 123 } 124