~ review updates and more docs on debugging effect

Author: elizarov

README.md

@@ -165,10 +165,7 @@ threads are handled by Android runtime.
 #### R8 and ProGuard
 
 R8 and ProGuard rules are bundled into the [`kotlinx-coroutines-android`](ui/kotlinx-coroutines-android) module.
-For best results it is recommended to use a recent version of R8.
-R8 is a replacement for ProGuard in Android ecosystem, it is enabled by default since Android gradle plugin 3.4.0
-(3.3.0-beta also had it enabled). The upcoming AGP 4.0.0 has never R8 and additional rules enable
-more optimizations, producing smaller binary size. 
+For more details see ["Optimization" section for Android](ui/kotlinx-coroutines-android/README.md#optimization). 
 
 ### JS
 

docs/debugging.md

@@ -8,11 +8,12 @@
   * [Stacktrace recovery machinery](#stacktrace-recovery-machinery)
 * [Debug agent](#debug-agent)
   * [Debug agent and Android](#debug-agent-and-android)
+* [Android optimization](#android-optimization)
 
 <!--- END_TOC -->
 
-
 ## Debugging coroutines
+
 Debugging asynchronous programs is challenging, because multiple concurrent coroutines are typically working at the same time.
 To help with that, `kotlinx.coroutines` comes with additional features for debugging: debug mode, stacktrace recovery 
 and debug agent.
@@ -87,6 +88,14 @@ java.lang.NoClassDefFoundError: Failed resolution of: Ljava/lang/management/Mana
         at kotlinx.coroutines.debug.DebugProbes.install(DebugProbes.kt:49)
 -->
 
+## Android optimization
+
+In optimized (release) builds with R8 version 1.6.0 or later both 
+[Debugging mode](../../docs/debugging.md#debug-mode) and 
+[Stacktrace recovery](../../docs/debugging.md#stacktrace-recovery) 
+are permanently turned off. 
+For more details see ["Optimization" section for Android](../ui/kotlinx-coroutines-android/README.md#optimization). 
+
 <!--- MODULE kotlinx-coroutines-core -->
 <!--- INDEX kotlinx.coroutines -->
 [DEBUG_PROPERTY_NAME]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-d-e-b-u-g_-p-r-o-p-e-r-t-y_-n-a-m-e.html

kotlinx-coroutines-core/jvm/src/internal/MainDispatchers.kt

@@ -65,7 +65,7 @@ public fun MainCoroutineDispatcher.isMissing(): Boolean = this is MissingMainCor
 
 // R8 optimization hook, not const on purpose to enable R8 optimizations via "assumenosideeffects"
 @Suppress("MayBeConstant")
-val SUPPORT_MISSING = true
+private val SUPPORT_MISSING = true
 
 @Suppress("ConstantConditionIf")
 private fun createMissingDispatcher(cause: Throwable? = null, errorHint: String? = null) =

ui/kotlinx-coroutines-android/README.md

@@ -5,6 +5,23 @@ Provides `Dispatchers.Main` context for Android applications.
 Read [Guide to UI programming with coroutines](https://github.com/Kotlin/kotlinx.coroutines/blob/master/ui/coroutines-guide-ui.md)
 for tutorial on this module.
 
+# Optimization
+
+R8 and ProGuard rules are bundled into this module. 
+R8 is a replacement for ProGuard in Android ecosystem, it is enabled by default since Android gradle plugin 3.4.0
+(3.3.0-beta also had it enabled). 
+For best results it is recommended to use a recent version of R8, which produces a smaller binary.
+
+When optimizations are enabled with R8 version 1.6.0 or later
+the following debugging features are permanently turned off to reduce the size of the resulting binary:
+
+* [Debugging mode](../../docs/debugging.md#debug-mode)
+* [Stacktrace recovery](../../docs/debugging.md#stacktrace-recovery)
+* The internal assertions in the library are also permanently removed.
+
+You can examine the corresponding rules in this 
+[`coroutines.pro`](resources/META-INF/com.android.tools/r8-from-1.6.0/coroutines.pro) file.
+
 # Package kotlinx.coroutines.android
 
 Provides `Dispatchers.Main` context for Android applications.

ui/kotlinx-coroutines-android/src/AndroidExceptionPreHandler.kt

@@ -21,7 +21,7 @@ internal class AndroidExceptionPreHandler :
     private fun preHandler(): Method? {
         val current = _preHandler
         if (current !== this) return current as Method?
-        val declared =try {
+        val declared = try {
             Thread::class.java.getDeclaredMethod("getUncaughtExceptionPreHandler").takeIf {
                 Modifier.isPublic(it.modifiers) && Modifier.isStatic(it.modifiers)
             }

ui/kotlinx-coroutines-android/testdata/r8-test-rules.pro

@@ -7,8 +7,8 @@
 -checkdiscard class kotlinx.coroutines.DebugKt
 -checkdiscard class kotlinx.coroutines.internal.StackTraceRecoveryKt
 
-# Real android projects do not keep this class, but somehow it is kept in this test (R& bug)
+# Real android projects do not keep this class, but somehow it is kept in this test (R8 bug)
 # -checkdiscard class kotlinx.coroutines.internal.MissingMainCoroutineDispatcher
 
-# Should not keep this class, but it is still there (R& bug)
+# Should not keep this class, but it is still there (R8 bug)
 #-checkdiscard class kotlinx.coroutines.CoroutineId