1 files changed, 122 insertions, 0 deletions
diff --git a/kotlinx-coroutines-core/jvm/src/Debug.kt b/kotlinx-coroutines-core/jvm/src/Debug.kt
new file mode 100644
index 00000000..98a1c1ea
--- /dev/null
+++ b/kotlinx-coroutines-core/jvm/src/Debug.kt
@@ -0,0 +1,122 @@
+/*
+ * Copyright 2016-2019 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+// Need InlineOnly for efficient bytecode on Android
+@file:Suppress("INVISIBLE_REFERENCE", "INVISIBLE_MEMBER")
+
+package kotlinx.coroutines
+
+import kotlinx.coroutines.internal.*
+import java.util.concurrent.atomic.*
+import kotlin.internal.InlineOnly
+
+/**
+ * Name of the property that controls coroutine debugging.
+ *
+ * ### Debugging facilities
+ *
+ * In debug mode every coroutine is assigned a unique consecutive identifier.
+ * Every thread that executes a coroutine has its name modified to include the name and identifier of
+ * the currently running coroutine.
+ *
+ * Enable debugging facilities with "`kotlinx.coroutines.debug`" ([DEBUG_PROPERTY_NAME]) system property,
+ * use the following values:
+ *
+ * * "`auto`" (default mode, [DEBUG_PROPERTY_VALUE_AUTO]) -- enabled when assertions are enabled with "`-ea`" JVM option.
+ * * "`on`" ([DEBUG_PROPERTY_VALUE_ON]) or empty string -- enabled.
+ * * "`off`" ([DEBUG_PROPERTY_VALUE_OFF]) -- disabled.
+ *
+ * Coroutine name can be explicitly assigned using [CoroutineName] context element.
+ * The string "coroutine" is used as a default name.
+ *
+ * Debugging facilities are implemented by [newCoroutineContext][CoroutineScope.newCoroutineContext] function that
+ * is used in all coroutine builders to create context of a new coroutine.
+ */
+public const val DEBUG_PROPERTY_NAME = "kotlinx.coroutines.debug"
+
+/**
+ * Name of the boolean property that controls stacktrace recovery (enabled by default) on JVM.
+ * Stacktrace recovery is enabled if both debug and stacktrace recovery modes are enabled.
+ *
+ * Stacktrace recovery mode wraps every exception into the exception of the same type with original exception
+ * as cause, but with stacktrace of the current coroutine.
+ * Exception is instantiated using reflection by using no-arg, cause or cause and message constructor.
+ *
+ * This mechanism is currently supported for channels, [async], [launch], [coroutineScope], [supervisorScope]
+ * and [withContext] builders.
+ */
+internal const val STACKTRACE_RECOVERY_PROPERTY_NAME = "kotlinx.coroutines.stacktrace.recovery"
+
+/**
+ * Throwable which can be cloned during stacktrace recovery in a class-specific way.
+ * For additional information about stacktrace recovery see [STACKTRACE_RECOVERY_PROPERTY_NAME]
+ *
+ * Example of usage:
+ * ```
+ * class BadResponseCodeException(val responseCode: Int) : Exception(), CopyableThrowable<BadResponseCodeException> {
+ *
+ *  override fun createCopy(): BadResponseCodeException {
+ *    val result = BadResponseCodeException(responseCode)
+ *    result.initCause(this)
+ *    return result
+ *  }
+ * ```
+ */
+@ExperimentalCoroutinesApi
+public interface CopyableThrowable<T> where T : Throwable, T : CopyableThrowable<T> {
+
+    /**
+     * Creates a copy of the current instance.
+     * For better debuggability, it is recommended to use original exception as [cause][Throwable.cause] of the resulting one.
+     * Stacktrace of copied exception will be overwritten by stacktrace recovery machinery by [Throwable.setStackTrace] call.
+     * An exception can opt-out of copying by returning `null` from this function.
+     */
+    public fun createCopy(): T?
+}
+
+/**
+ * Automatic debug configuration value for [DEBUG_PROPERTY_NAME].
+ */
+public const val DEBUG_PROPERTY_VALUE_AUTO = "auto"
+
+/**
+ * Debug turned on value for [DEBUG_PROPERTY_NAME].
+ */
+public const val DEBUG_PROPERTY_VALUE_ON = "on"
+
+/**
+ * Debug turned on value for [DEBUG_PROPERTY_NAME].
+ */
+public const val DEBUG_PROPERTY_VALUE_OFF = "off"
+
+// @JvmField: Don't use JvmField here to enable R8 optimizations via "assumenosideeffects"
+internal val ASSERTIONS_ENABLED = CoroutineId::class.java.desiredAssertionStatus()
+
+// @JvmField: Don't use JvmField here to enable R8 optimizations via "assumenosideeffects"
+internal actual val DEBUG = systemProp(DEBUG_PROPERTY_NAME).let { value ->
+    when (value) {
+        DEBUG_PROPERTY_VALUE_AUTO, null -> ASSERTIONS_ENABLED
+        DEBUG_PROPERTY_VALUE_ON, "" -> true
+        DEBUG_PROPERTY_VALUE_OFF -> false
+        else -> error("System property '$DEBUG_PROPERTY_NAME' has unrecognized value '$value'")
+    }
+}
+
+// Note: stack-trace recovery is enabled only in debug mode
+// @JvmField: Don't use JvmField here to enable R8 optimizations via "assumenosideeffects"
+internal actual val RECOVER_STACK_TRACES =
+    DEBUG && systemProp(STACKTRACE_RECOVERY_PROPERTY_NAME, true)
+
+// It is used only in debug mode
+internal val COROUTINE_ID = AtomicLong(0)
+
+// for tests only
+internal fun resetCoroutineId() {
+    COROUTINE_ID.set(0)
+}
+
+@InlineOnly
+internal actual inline fun assert(value: () -> Boolean) {
+    if (ASSERTIONS_ENABLED && !value()) throw AssertionError()
+}