Improve documentation, make MainScope experimental, cleanup leftovers
diff --git a/binary-compatibility-validator/resources/api.properties b/binary-compatibility-validator/resources/api.properties
index c0128c5..3c41251 100644
--- a/binary-compatibility-validator/resources/api.properties
+++ b/binary-compatibility-validator/resources/api.properties
@@ -2,7 +2,7 @@
# Copyright 2016-2018 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
#
-module.roots=core integration native reactive ui test
+module.roots=core integration native reactive ui test debug
module.marker=build.gradle
module.ignore=kotlinx-coroutines-rx-example stdlib-stubs
diff --git a/common/kotlinx-coroutines-core-common/src/CoroutineScope.kt b/common/kotlinx-coroutines-core-common/src/CoroutineScope.kt
index a8ef7a7..3256015 100644
--- a/common/kotlinx-coroutines-core-common/src/CoroutineScope.kt
+++ b/common/kotlinx-coroutines-core-common/src/CoroutineScope.kt
@@ -94,6 +94,7 @@
* `val scope = MainScope() + CoroutineName("MyActivity")`.
*/
@Suppress("FunctionName")
+@ExperimentalCoroutinesApi // Experimental since 1.1.0, tentatively until 1.2.0
public fun MainScope(): CoroutineScope = ContextScope(SupervisorJob() + Dispatchers.Main)
/**
@@ -137,7 +138,7 @@
*
* ```
*/
-object GlobalScope : CoroutineScope {
+public object GlobalScope : CoroutineScope {
/**
* Returns [EmptyCoroutineContext].
*/
diff --git a/core/kotlinx-coroutines-core/resources/META-INF/proguard/coroutines.pro b/core/kotlinx-coroutines-core/resources/META-INF/proguard/coroutines.pro
index 479ad68..86108f3 100644
--- a/core/kotlinx-coroutines-core/resources/META-INF/proguard/coroutines.pro
+++ b/core/kotlinx-coroutines-core/resources/META-INF/proguard/coroutines.pro
@@ -1,7 +1,6 @@
# ServiceLoader support
-keepnames class kotlinx.coroutines.internal.MainDispatcherFactory {}
-keepnames class kotlinx.coroutines.CoroutineExceptionHandler {}
--keepnames class kotlinx.coroutines.test.internal.InjectableDispatcherFactory {}
# Most of volatile fields are updated with AFU and should not be mangled
-keepclassmembernames class kotlinx.** {
diff --git a/core/kotlinx-coroutines-core/src/internal/MainDispatchers.kt b/core/kotlinx-coroutines-core/src/internal/MainDispatchers.kt
index 9524b05..951053d 100644
--- a/core/kotlinx-coroutines-core/src/internal/MainDispatchers.kt
+++ b/core/kotlinx-coroutines-core/src/internal/MainDispatchers.kt
@@ -28,6 +28,8 @@
* If anything goes wrong while trying to create main dispatcher (class not found,
* initialization failed, etc), then replace the main dispatcher with a special
* stub that throws an error message on any attempt to actually use it.
+ *
+ * @suppress internal API
*/
@InternalCoroutinesApi
public fun MainDispatcherFactory.tryCreateDispatcher(factories: List<MainDispatcherFactory>): MainCoroutineDispatcher =
diff --git a/core/kotlinx-coroutines-core/src/internal/ProbesSupport.kt b/core/kotlinx-coroutines-core/src/internal/ProbesSupport.kt
index f3c548e..baa9682 100644
--- a/core/kotlinx-coroutines-core/src/internal/ProbesSupport.kt
+++ b/core/kotlinx-coroutines-core/src/internal/ProbesSupport.kt
@@ -8,4 +8,4 @@
import kotlin.coroutines.*
import kotlin.coroutines.jvm.internal.probeCoroutineCreated as probe
-internal actual inline fun <T> probeCoroutineCreated(completion: Continuation<T>): Continuation<T> = probe(completion)
\ No newline at end of file
+internal actual inline fun <T> probeCoroutineCreated(completion: Continuation<T>): Continuation<T> = probe(completion)
diff --git a/core/kotlinx-coroutines-debug/README.md b/core/kotlinx-coroutines-debug/README.md
index c83792b..c5f1f6a 100644
--- a/core/kotlinx-coroutines-debug/README.md
+++ b/core/kotlinx-coroutines-debug/README.md
@@ -4,19 +4,28 @@
### Overview
-This module provides a debug JVM agent which allows to track and trace existing coroutines.
+This module provides a debug JVM agent that allows to track and trace existing coroutines.
The main entry point to debug facilities is [DebugProbes] API.
-Call to [DebugProbes.install] installs debug agent via ByteBuddy and starts to spy on coroutines when they are created, suspended or resumed.
+Call to [DebugProbes.install] installs debug agent via ByteBuddy and starts spying on coroutines when they are created, suspended and resumed.
After that, you can use [DebugProbes.dumpCoroutines] to print all active (suspended or running) coroutines, including their state, creation and
suspension stacktraces.
Additionally, it is possible to process the list of such coroutines via [DebugProbes.dumpCoroutinesState] or dump isolated parts
-of coroutines hierarchy referenced by a [Job] instance using [DebugProbes.printScope] or [DebugProbes.printJob].
+of coroutines hierarchy referenced by a [Job] or [CoroutineScope] instances using [DebugProbes.printJob] and [DebugProbes.printScope] respectively.
+
+### Using in your project
+
+Add `kotlinx-coroutines-debug` to your project test dependencies:
+```
+dependencies {
+ testImplementation 'org.jetbrains.kotlinx:kotlinx-coroutines-debug:1.1.0-alpha'
+}
+```
### Using as JVM agent
It is possible to use this module as a standalone JVM agent to enable debug probes on the application startup.
-You can run your application with an additional argument: `-javaagent:kotlinx-coroutines-debug-1.0.1.jar`.
+You can run your application with an additional argument: `-javaagent:kotlinx-coroutines-debug-1.1.0-alpha.jar`.
Additionally, on Linux and Mac OS X you can use `kill -5 $pid` command in order to force your application to print all alive coroutines.
@@ -110,6 +119,7 @@
<!--- MODULE kotlinx-coroutines-core -->
<!--- INDEX kotlinx.coroutines -->
[Job]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-job/index.html
+[CoroutineScope]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-coroutine-scope/index.html
<!--- MODULE kotlinx-coroutines-debug -->
<!--- INDEX kotlinx.coroutines.debug -->
[DebugProbes]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-debug/kotlinx.coroutines.debug/-debug-probes/index.html
diff --git a/core/kotlinx-coroutines-test/README.md b/core/kotlinx-coroutines-test/README.md
index aef19eb..aa70f2f 100644
--- a/core/kotlinx-coroutines-test/README.md
+++ b/core/kotlinx-coroutines-test/README.md
@@ -7,7 +7,7 @@
Add `kotlinx-coroutines-test` to your project test dependencies:
```
dependencies {
- testImplementation 'org.jetbrains.kotlinx:kotlinx-coroutines-test:1.0.1'
+ testImplementation 'org.jetbrains.kotlinx:kotlinx-coroutines-test:1.1.0-alpha'
}
```
diff --git a/native/kotlinx-coroutines-core-native/src/internal/ProbesSupport.kt b/native/kotlinx-coroutines-core-native/src/internal/ProbesSupport.kt
index c2daab5..81b6476 100644
--- a/native/kotlinx-coroutines-core-native/src/internal/ProbesSupport.kt
+++ b/native/kotlinx-coroutines-core-native/src/internal/ProbesSupport.kt
@@ -7,4 +7,4 @@
import kotlin.coroutines.*
@Suppress("NOTHING_TO_INLINE")
-internal actual inline fun <T> probeCoroutineCreated(completion: Continuation<T>): Continuation<T> = completion
\ No newline at end of file
+internal actual inline fun <T> probeCoroutineCreated(completion: Continuation<T>): Continuation<T> = completion