<lambda>null1 // Need InlineOnly for efficient bytecode on Android
2 @file:Suppress("INVISIBLE_REFERENCE", "INVISIBLE_MEMBER")
3
4 package kotlinx.coroutines
5
6 import kotlinx.coroutines.internal.*
7 import java.util.concurrent.atomic.*
8 import kotlin.internal.InlineOnly
9
10 /**
11 * Name of the property that controls coroutine debugging.
12 *
13 * ### Debugging facilities
14 *
15 * In debug mode every coroutine is assigned a unique consecutive identifier.
16 * Every thread that executes a coroutine has its name modified to include the name and identifier of
17 * the currently running coroutine.
18 *
19 * Enable debugging facilities with "`kotlinx.coroutines.debug`" ([DEBUG_PROPERTY_NAME]) system property,
20 * use the following values:
21 *
22 * - "`auto`" (default mode, [DEBUG_PROPERTY_VALUE_AUTO]) -- enabled when assertions are enabled with "`-ea`" JVM option.
23 * - "`on`" ([DEBUG_PROPERTY_VALUE_ON]) or empty string -- enabled.
24 * - "`off`" ([DEBUG_PROPERTY_VALUE_OFF]) -- disabled.
25 *
26 * Coroutine name can be explicitly assigned using [CoroutineName] context element.
27 * The string "coroutine" is used as a default name.
28 *
29 * Debugging facilities are implemented by [newCoroutineContext][CoroutineScope.newCoroutineContext] function that
30 * is used in all coroutine builders to create context of a new coroutine.
31 */
32 public const val DEBUG_PROPERTY_NAME: String = "kotlinx.coroutines.debug"
33
34 /**
35 * Name of the boolean property that controls stacktrace recovery (enabled by default) on JVM.
36 * Stacktrace recovery is enabled if both debug and stacktrace recovery modes are enabled.
37 *
38 * Stacktrace recovery mode wraps every exception into the exception of the same type with original exception
39 * as cause, but with stacktrace of the current coroutine.
40 * Exception is instantiated using reflection by using no-arg, cause or cause and message constructor.
41 *
42 * This mechanism is currently supported for channels, [async], [launch], [coroutineScope], [supervisorScope]
43 * and [withContext] builders.
44 */
45 internal const val STACKTRACE_RECOVERY_PROPERTY_NAME = "kotlinx.coroutines.stacktrace.recovery"
46
47 /**
48 * Automatic debug configuration value for [DEBUG_PROPERTY_NAME].
49 */
50 public const val DEBUG_PROPERTY_VALUE_AUTO: String = "auto"
51
52 /**
53 * Debug turned on value for [DEBUG_PROPERTY_NAME].
54 */
55 public const val DEBUG_PROPERTY_VALUE_ON: String = "on"
56
57 /**
58 * Debug turned off value for [DEBUG_PROPERTY_NAME].
59 */
60 public const val DEBUG_PROPERTY_VALUE_OFF: String = "off"
61
62 // @JvmField: Don't use JvmField here to enable R8 optimizations via "assumenosideeffects"
63 internal val ASSERTIONS_ENABLED = CoroutineId::class.java.desiredAssertionStatus()
64
65 // @JvmField: Don't use JvmField here to enable R8 optimizations via "assumenosideeffects"
66 internal actual val DEBUG = systemProp(DEBUG_PROPERTY_NAME).let { value ->
67 when (value) {
68 DEBUG_PROPERTY_VALUE_AUTO, null -> ASSERTIONS_ENABLED
69 DEBUG_PROPERTY_VALUE_ON, "" -> true
70 DEBUG_PROPERTY_VALUE_OFF -> false
71 else -> error("System property '$DEBUG_PROPERTY_NAME' has unrecognized value '$value'")
72 }
73 }
74
75 // Note: stack-trace recovery is enabled only in debug mode
76 // @JvmField: Don't use JvmField here to enable R8 optimizations via "assumenosideeffects"
77 @PublishedApi
78 internal actual val RECOVER_STACK_TRACES: Boolean =
79 DEBUG && systemProp(STACKTRACE_RECOVERY_PROPERTY_NAME, true)
80
81 // It is used only in debug mode
82 internal val COROUTINE_ID = AtomicLong(0)
83
84 // for tests only
resetCoroutineIdnull85 internal fun resetCoroutineId() {
86 COROUTINE_ID.set(0)
87 }
88
89 @InlineOnly
assertnull90 internal actual inline fun assert(value: () -> Boolean) {
91 if (ASSERTIONS_ENABLED && !value()) throw AssertionError()
92 }
93