1 package kotlinx.coroutines
2
3 internal expect val DEBUG: Boolean
4 internal expect val Any.hexAddress: String
5 internal expect val Any.classSimpleName: String
assertnull6 internal expect fun assert(value: () -> Boolean)
7
8 /**
9 * Throwable which can be cloned during stacktrace recovery in a class-specific way.
10 * For additional information about stacktrace recovery see [STACKTRACE_RECOVERY_PROPERTY_NAME]
11 *
12 * Example of usage:
13 * ```
14 * class BadResponseCodeException(val responseCode: Int) : Exception(), CopyableThrowable<BadResponseCodeException> {
15 *
16 * override fun createCopy(): BadResponseCodeException {
17 * val result = BadResponseCodeException(responseCode)
18 * result.initCause(this)
19 * return result
20 * }
21 * ```
22 *
23 * Copy mechanism is used only on JVM, but it might be convenient to implement it in common exceptions,
24 * so on JVM their stacktraces will be properly recovered.
25 */
26 @ExperimentalCoroutinesApi // Since 1.2.0, no ETA on stability
27 public interface CopyableThrowable<T> where T : Throwable, T : CopyableThrowable<T> {
28
29 /**
30 * Creates a copy of the current instance.
31 *
32 * For better debuggability, it is recommended to use original exception as [cause][Throwable.cause] of the resulting one.
33 * Stacktrace of copied exception will be overwritten by stacktrace recovery machinery by [Throwable.setStackTrace] call.
34 * An exception can opt-out of copying by returning `null` from this function.
35 * Suppressed exceptions of the original exception should not be copied in order to avoid circular exceptions.
36 *
37 * This function is allowed to create a copy with a modified [message][Throwable.message], but it should be noted
38 * that the copy can be later recovered as well and message modification code should handle this situation correctly
39 * (e.g. by also storing the original message and checking it) to produce a human-readable result.
40 */
41 public fun createCopy(): T?
42 }
43