Skip to content

Commit 73b456b

Browse files
elizarovelizarov
committed
Added clarification on deprecation version in code, better CE messages
1 parent d293639 commit 73b456b

File tree

15 files changed

+33
-25
lines changed

15 files changed

+33
-25
lines changed

‎integration/kotlinx-coroutines-jdk8/src/future/Future.kt

+1-1
Original file line numberDiff line numberDiff line change
@@ -73,7 +73,7 @@ public fun <T> Deferred<T>.asCompletableFuture(): CompletableFuture<T> {
7373
val future = CompletableFuture<T>()
7474
future.whenComplete { _, exception ->
7575
cancel(exception?.let {
76-
it as? CancellationException ?: CancellationException("Future failed", it)
76+
it as? CancellationException ?: CancellationException("CompletableFuture was completed exceptionally", it)
7777
})
7878
}
7979
invokeOnCompletion {

‎kotlinx-coroutines-core/common/src/Job.kt

+9-9
Original file line numberDiff line numberDiff line change
@@ -166,13 +166,13 @@ public interface Job : CoroutineContext.Element {
166166
/**
167167
* @suppress This method implements old version of JVM ABI. Use [cancel].
168168
*/
169-
@Deprecated(level = DeprecationLevel.HIDDEN, message = "Binary compatibility only")
169+
@Deprecated(level = DeprecationLevel.HIDDEN, message = "Since 1.2.0, binary compatibility with versions <= 1.1.x")
170170
public fun cancel() = cancel(null)
171171

172172
/**
173173
* @suppress This method has bad semantics when cause is not a [CancellationException]. Use [cancel].
174174
*/
175-
@Deprecated(level = DeprecationLevel.HIDDEN, message = "Binary compatibility only")
175+
@Deprecated(level = DeprecationLevel.HIDDEN, message = "Since 1.2.0, binary compatibility with versions <= 1.1.x")
176176
public fun cancel(cause: Throwable? = null): Boolean
177177

178178
// ------------ parent-child ------------
@@ -358,7 +358,7 @@ public fun Job(parent: Job? = null): CompletableJob = JobImpl(parent)
358358

359359
/** @suppress Binary compatibility only */
360360
@Suppress("FunctionName")
361-
@Deprecated(level = DeprecationLevel.HIDDEN, message = "Binary compatibility")
361+
@Deprecated(level = DeprecationLevel.HIDDEN, message = "Since 1.2.0, binary compatibility with versions <= 1.1.x")
362362
@JvmName("Job")
363363
public fun Job0(parent: Job? = null): Job = Job(parent)
364364

@@ -488,13 +488,13 @@ public fun Job.cancelChildren(cause: CancellationException? = null) {
488488
/**
489489
* @suppress This method implements old version of JVM ABI. Use [cancel].
490490
*/
491-
@Deprecated(level = DeprecationLevel.HIDDEN, message = "Binary compatibility")
491+
@Deprecated(level = DeprecationLevel.HIDDEN, message = "Since 1.2.0, binary compatibility with versions <= 1.1.x")
492492
public fun Job.cancelChildren() = cancelChildren(null)
493493

494494
/**
495495
* @suppress This method has bad semantics when cause is not a [CancellationException]. Use [Job.cancelChildren].
496496
*/
497-
@Deprecated(level = DeprecationLevel.HIDDEN, message = "Binary compatibility")
497+
@Deprecated(level = DeprecationLevel.HIDDEN, message = "Since 1.2.0, binary compatibility with versions <= 1.1.x")
498498
public fun Job.cancelChildren(cause: Throwable? = null) {
499499
children.forEach { (it as? JobSupport)?.cancelInternal(cause) }
500500
}
@@ -531,13 +531,13 @@ public fun CoroutineContext.cancel(cause: CancellationException? = null) {
531531
/**
532532
* @suppress This method implements old version of JVM ABI. Use [CoroutineContext.cancel].
533533
*/
534-
@Deprecated(level = DeprecationLevel.HIDDEN, message = "Binary compatibility")
534+
@Deprecated(level = DeprecationLevel.HIDDEN, message = "Since 1.2.0, binary compatibility with versions <= 1.1.x")
535535
public fun CoroutineContext.cancel() = cancel(null)
536536

537537
/**
538538
* @suppress This method has bad semantics when cause is not a [CancellationException]. Use [CoroutineContext.cancel].
539539
*/
540-
@Deprecated(level = DeprecationLevel.HIDDEN, message = "Binary compatibility")
540+
@Deprecated(level = DeprecationLevel.HIDDEN, message = "Since 1.2.0, binary compatibility with versions <= 1.1.x")
541541
public fun CoroutineContext.cancel(cause: Throwable? = null): Boolean =
542542
@Suppress("DEPRECATION")
543543
(this[Job] as? JobSupport)?.cancelInternal(cause) ?: false
@@ -554,13 +554,13 @@ public fun CoroutineContext.cancelChildren(cause: CancellationException? = null)
554554
/**
555555
* @suppress This method implements old version of JVM ABI. Use [CoroutineContext.cancelChildren].
556556
*/
557-
@Deprecated(level = DeprecationLevel.HIDDEN, message = "Binary compatibility")
557+
@Deprecated(level = DeprecationLevel.HIDDEN, message = "Since 1.2.0, binary compatibility with versions <= 1.1.x")
558558
public fun CoroutineContext.cancelChildren() = cancelChildren(null)
559559

560560
/**
561561
* @suppress This method has bad semantics when cause is not a [CancellationException]. Use [CoroutineContext.cancelChildren].
562562
*/
563-
@Deprecated(level = DeprecationLevel.HIDDEN, message = "Binary compatibility")
563+
@Deprecated(level = DeprecationLevel.HIDDEN, message = "Since 1.2.0, binary compatibility with versions <= 1.1.x")
564564
public fun CoroutineContext.cancelChildren(cause: Throwable? = null) {
565565
this[Job]?.children?.forEach { (it as? JobSupport)?.cancelInternal(cause) }
566566
}

‎kotlinx-coroutines-core/common/src/JobSupport.kt

+2-2
Original file line numberDiff line numberDiff line change
@@ -573,12 +573,12 @@ public open class JobSupport constructor(active: Boolean) : Job, ChildJob, Paren
573573

574574
// HIDDEN in Job interface. Invoked only by legacy compiled code.
575575
// external cancel with (optional) cause, never invoked implicitly from internal machinery
576-
@Deprecated(level = DeprecationLevel.HIDDEN, message = "Binary compatibility only")
576+
@Deprecated(level = DeprecationLevel.HIDDEN, message = "Added since 1.2.0 for binary compatibility with versions <= 1.1.x")
577577
public override fun cancel(cause: Throwable?): Boolean =
578578
cancelInternal(cause)
579579

580580
// It is overridden in channel-linked implementation
581-
// Note: Boolean result is used only in DEPRECATED functions
581+
// Note: Boolean result is used only in HIDDEN DEPRECATED functions that were public in versions <= 1.1.x
582582
public open fun cancelInternal(cause: Throwable?): Boolean =
583583
cancelImpl(cause) && handlesException
584584

‎kotlinx-coroutines-core/common/src/NonCancellable.kt

+1-1
Original file line numberDiff line numberDiff line change
@@ -98,7 +98,7 @@ public object NonCancellable : AbstractCoroutineContextElement(Job), Job {
9898
* Always returns `false`.
9999
* @suppress This method has bad semantics when cause is not a [CancellationException]. Use [cancel].
100100
*/
101-
@Deprecated(level = DeprecationLevel.HIDDEN, message = "Binary compatibility only")
101+
@Deprecated(level = DeprecationLevel.HIDDEN, message = "Since 1.2.0, binary compatibility with versions <= 1.1.x")
102102
override fun cancel(cause: Throwable?): Boolean = false // never handles exceptions
103103

104104
/**

‎kotlinx-coroutines-core/common/src/Supervisor.kt

+1-1
Original file line numberDiff line numberDiff line change
@@ -33,7 +33,7 @@ public fun SupervisorJob(parent: Job? = null) : CompletableJob = SupervisorJobIm
3333

3434
/** @suppress Binary compatibility only */
3535
@Suppress("FunctionName")
36-
@Deprecated(level = DeprecationLevel.HIDDEN, message = "Binary compatibility")
36+
@Deprecated(level = DeprecationLevel.HIDDEN, message = "Since 1.2.0, binary compatibility with versions <= 1.1.x")
3737
@JvmName("SupervisorJob")
3838
public fun SupervisorJob0(parent: Job? = null) : Job = SupervisorJob(parent)
3939

‎kotlinx-coroutines-core/common/src/channels/AbstractChannel.kt

+1-1
Original file line numberDiff line numberDiff line change
@@ -655,7 +655,7 @@ internal abstract class AbstractChannel<E> : AbstractSendChannel<E>(), Channel<E
655655
return if (result === POLL_FAILED) null else receiveOrNullResult(result)
656656
}
657657

658-
@Deprecated(level = DeprecationLevel.HIDDEN, message = "Binary compatibility only")
658+
@Deprecated(level = DeprecationLevel.HIDDEN, message = "Since 1.2.0, binary compatibility with versions <= 1.1.x")
659659
final override fun cancel(cause: Throwable?): Boolean =
660660
cancelInternal(cause)
661661

‎kotlinx-coroutines-core/common/src/channels/ArrayBroadcastChannel.kt

+1-1
Original file line numberDiff line numberDiff line change
@@ -67,7 +67,7 @@ internal class ArrayBroadcastChannel<E>(
6767
return true
6868
}
6969

70-
@Deprecated(level = DeprecationLevel.HIDDEN, message = "Binary compatibility only")
70+
@Deprecated(level = DeprecationLevel.HIDDEN, message = "Since 1.2.0, binary compatibility with versions <= 1.1.x")
7171
override fun cancel(cause: Throwable?): Boolean =
7272
cancelInternal(cause)
7373

‎kotlinx-coroutines-core/common/src/channels/Broadcast.kt

+1-1
Original file line numberDiff line numberDiff line change
@@ -95,7 +95,7 @@ private open class BroadcastCoroutine<E>(
9595
override val channel: SendChannel<E>
9696
get() = this
9797

98-
@Deprecated(level = DeprecationLevel.HIDDEN, message = "Binary compatibility only")
98+
@Deprecated(level = DeprecationLevel.HIDDEN, message = "Since 1.2.0, binary compatibility with versions <= 1.1.x")
9999
final override fun cancel(cause: Throwable?): Boolean =
100100
cancelInternal(cause)
101101

‎kotlinx-coroutines-core/common/src/channels/Channel.kt

+2-2
Original file line numberDiff line numberDiff line change
@@ -257,13 +257,13 @@ public interface ReceiveChannel<out E> {
257257
/**
258258
* @suppress This method implements old version of JVM ABI. Use [cancel].
259259
*/
260-
@Deprecated(level = DeprecationLevel.HIDDEN, message = "Binary compatibility only")
260+
@Deprecated(level = DeprecationLevel.HIDDEN, message = "Since 1.2.0, binary compatibility with versions <= 1.1.x")
261261
public fun cancel() = cancel(null)
262262

263263
/**
264264
* @suppress This method has bad semantics when cause is not a [CancellationException]. Use [cancel].
265265
*/
266-
@Deprecated(level = DeprecationLevel.HIDDEN, message = "Binary compatibility only")
266+
@Deprecated(level = DeprecationLevel.HIDDEN, message = "Since 1.2.0, binary compatibility with versions <= 1.1.x")
267267
public fun cancel(cause: Throwable? = null): Boolean
268268
}
269269

‎kotlinx-coroutines-core/common/src/channels/ChannelCoroutine.kt

+1-1
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@ internal open class ChannelCoroutine<E>(
1919
cancelInternal(null)
2020
}
2121

22-
@Deprecated(level = DeprecationLevel.HIDDEN, message = "Binary compatibility only")
22+
@Deprecated(level = DeprecationLevel.HIDDEN, message = "Since 1.2.0, binary compatibility with versions <= 1.1.x")
2323
final override fun cancel(cause: Throwable?): Boolean =
2424
cancelInternal(cause)
2525

‎kotlinx-coroutines-core/common/src/channels/Channels.common.kt

+1-1
Original file line numberDiff line numberDiff line change
@@ -67,7 +67,7 @@ public fun ReceiveChannel<*>.consumes(): CompletionHandler = { cause: Throwable?
6767
@PublishedApi
6868
internal fun ReceiveChannel<*>.cancelConsumed(cause: Throwable?) {
6969
cancel(cause?.let {
70-
it as? CancellationException ?: CancellationException("Consumed", it)
70+
it as? CancellationException ?: CancellationException("Channel was consumed, consumer had failed", it)
7171
})
7272
}
7373

‎kotlinx-coroutines-core/common/src/channels/ConflatedBroadcastChannel.kt

+1-1
Original file line numberDiff line numberDiff line change
@@ -204,7 +204,7 @@ public class ConflatedBroadcastChannel<E>() : BroadcastChannel<E> {
204204
/**
205205
* @suppress This method has bad semantics when cause is not a [CancellationException]. Use [cancel].
206206
*/
207-
@Deprecated(level = DeprecationLevel.HIDDEN, message = "Binary compatibility only")
207+
@Deprecated(level = DeprecationLevel.HIDDEN, message = "Since 1.2.0, binary compatibility with versions <= 1.1.x")
208208
public override fun cancel(cause: Throwable?): Boolean = close(cause)
209209

210210
/**

‎kotlinx-coroutines-core/common/test/channels/TestChannelKind.kt

+1-1
Original file line numberDiff line numberDiff line change
@@ -64,7 +64,7 @@ private class ChannelViaBroadcast<E>(
6464
override fun cancel(cause: CancellationException?) = sub.cancel(cause)
6565

6666
// implementing hidden method anyway, so can cast to an internal class
67-
@Deprecated(level = DeprecationLevel.HIDDEN, message = "Binary compatibility only")
67+
@Deprecated(level = DeprecationLevel.HIDDEN, message = "Since 1.2.0, binary compatibility with versions <= 1.1.x")
6868
override fun cancel(cause: Throwable?): Boolean = (sub as AbstractChannel).cancelInternal(cause)
6969

7070
override val onReceive: SelectClause1<E>

‎kotlinx-coroutines-core/js/src/Exceptions.kt

+5-1
Original file line numberDiff line numberDiff line change
@@ -55,7 +55,11 @@ internal fun IllegalStateException(message: String, cause: Throwable?) =
5555
IllegalStateException(message.withCause(cause))
5656

5757
private fun String?.withCause(cause: Throwable?) =
58-
if (cause == null) this else "$this; caused by $cause"
58+
when {
59+
cause == null -> this
60+
this == null -> "caused by $cause"
61+
else -> "$this; caused by $cause"
62+
}
5963

6064
@Suppress("NOTHING_TO_INLINE")
6165
internal actual inline fun Throwable.addSuppressedThrowable(other: Throwable) { /* empty */ }

‎kotlinx-coroutines-core/native/src/Exceptions.kt

+5-1
Original file line numberDiff line numberDiff line change
@@ -55,7 +55,11 @@ internal fun IllegalStateException(message: String, cause: Throwable?) =
5555
IllegalStateException(message.withCause(cause))
5656

5757
private fun String?.withCause(cause: Throwable?) =
58-
if (cause == null) this else "$this; caused by $cause"
58+
when {
59+
cause == null -> this
60+
this == null -> "caused by $cause"
61+
else -> "$this; caused by $cause"
62+
}
5963

6064
@Suppress("NOTHING_TO_INLINE")
6165
internal actual inline fun Throwable.addSuppressedThrowable(other: Throwable) { /* empty */ }

0 commit comments

Comments
 (0)