Add section about Android in debug agent readme
diff --git a/docs/debugging.md b/docs/debugging.md
index d3010c9..3424bca 100644
--- a/docs/debugging.md
+++ b/docs/debugging.md
@@ -17,6 +17,7 @@
and debug agent.
## Debug mode
+
The first debugging feature of `kotlinx.coroutines` is debug mode.
It can be enabled either by setting system property [DEBUG_PROPERTY_NAME] or by running Java with enabled assertions (`-ea` flag).
The latter is helpful to have debug mode enabled by default in unit tests.
@@ -26,6 +27,7 @@
Overhead of this feature is negligible and it can be safely turned on by default to simplify logging and diagnostic.
## Stacktrace recovery
+
Stacktrace recovery is another useful feature of debug mode. It is enabled by default in the debug mode,
but can be separately disabled by setting `kotlinx.coroutines.stacktrace.recovery` system property to `false`.
@@ -41,6 +43,7 @@
The only downside of this approach is losing referential transparency of the exception.
### Stacktrace recovery machinery
+
This section explains the inner mechanism of stacktrace recovery and can be skipped.
When an exception is rethrown between coroutines (e.g. through `withContext` or `Deferred.await` boundary), stacktrace recovery
@@ -54,6 +57,7 @@
3) Otherwise, one of the public exception's constructor is invoked reflectively with optional an `initCause` call.
## Debug agent
+
[kotlinx-coroutines-debug](../kotlinx-coroutines-debug) module provides one of the most powerful debug capabilities in `kotlinx.coroutines`.
This is a separate module with a JVM agent that keeps track of all alive coroutines, introspect and dump them similar to thread dump command,
@@ -61,7 +65,23 @@
The full tutorial of how to use debug agent can be found in a corresponding [readme](../kotlinx-coroutines-debug/README.md).
+### Debug agent and Android
+Unfortunately, Android runtime does not support Instrument API necessary for `kotlinx-coroutines-debug` to function, triggering `java.lang.NoClassDefFoundError: Failed resolution of: Ljava/lang/management/ManagementFactory;`.
+
+Nevertheless, it will be possible to support debug agent on Android as soon as [GradleAspectJ-Android](https://github.com/Archinamon/android-gradle-aspectj) will support androin-gradle 3.3
+
+<!---
+Make an exception googlable
+java.lang.NoClassDefFoundError: Failed resolution of: Ljava/lang/management/ManagementFactory;
+ at kotlinx.coroutines.repackaged.net.bytebuddy.agent.ByteBuddyAgent$ProcessProvider$ForCurrentVm$ForLegacyVm.resolve(ByteBuddyAgent.java:1055)
+ at kotlinx.coroutines.repackaged.net.bytebuddy.agent.ByteBuddyAgent$ProcessProvider$ForCurrentVm.resolve(ByteBuddyAgent.java:1038)
+ at kotlinx.coroutines.repackaged.net.bytebuddy.agent.ByteBuddyAgent.install(ByteBuddyAgent.java:374)
+ at kotlinx.coroutines.repackaged.net.bytebuddy.agent.ByteBuddyAgent.install(ByteBuddyAgent.java:342)
+ at kotlinx.coroutines.repackaged.net.bytebuddy.agent.ByteBuddyAgent.install(ByteBuddyAgent.java:328)
+ at kotlinx.coroutines.debug.internal.DebugProbesImpl.install(DebugProbesImpl.kt:39)
+ at kotlinx.coroutines.debug.DebugProbes.install(DebugProbes.kt:49)
+-->
<!--- MODULE kotlinx-coroutines-core -->
<!--- INDEX kotlinx.coroutines -->