New integration: AndroidX Lifecycle

binary-compatibility-validator/build.gradle

@@ -22,6 +22,7 @@ dependencies {
     testArtifacts project(':kotlinx-coroutines-jdk8')
     testArtifacts project(':kotlinx-coroutines-slf4j')
     testArtifacts project(path: ':kotlinx-coroutines-play-services', configuration: 'default')
+    testArtifacts project(path: ':kotlinx-coroutines-androidx-lifecycle', configuration: 'default')
 
     testArtifacts project(':kotlinx-coroutines-android')
     testArtifacts project(':kotlinx-coroutines-javafx')

binary-compatibility-validator/reference-public-api/kotlinx-coroutines-androidx-lifecycle.txt

@@ -0,0 +1,12 @@
+public final class kotlinx/coroutines/androidx/lifecycle/LifecycleDefaultScopesKt {
+	public static final fun getCoroutineScope (Landroidx/lifecycle/Lifecycle;)Lkotlinx/coroutines/CoroutineScope;
+	public static final fun getCoroutineScope (Landroidx/lifecycle/LifecycleOwner;)Lkotlinx/coroutines/CoroutineScope;
+	public static final fun getJob (Landroidx/lifecycle/Lifecycle;)Lkotlinx/coroutines/Job;
+}
+
+public final class kotlinx/coroutines/androidx/lifecycle/LifecycleKt {
+	public static final fun createJob (Landroidx/lifecycle/Lifecycle;Landroidx/lifecycle/Lifecycle$State;)Lkotlinx/coroutines/Job;
+	public static synthetic fun createJob$default (Landroidx/lifecycle/Lifecycle;Landroidx/lifecycle/Lifecycle$State;ILjava/lang/Object;)Lkotlinx/coroutines/Job;
+	public static final fun createScope (Landroidx/lifecycle/Lifecycle;Landroidx/lifecycle/Lifecycle$State;)Lkotlinx/coroutines/CoroutineScope;
+}
+

integration/README.md

@@ -8,7 +8,8 @@ Module name below corresponds to the artifact name in Maven/Gradle.
 * [kotlinx-coroutines-jdk8](kotlinx-coroutines-jdk8/README.md) -- integration with JDK8 `CompletableFuture` (Android API level 24).
 * [kotlinx-coroutines-guava](kotlinx-coroutines-guava/README.md) -- integration with Guava [ListenableFuture](https://github.com/google/guava/wiki/ListenableFutureExplained).
 * [kotlinx-coroutines-slf4j](kotlinx-coroutines-slf4j/README.md) -- integration with SLF4J [MDC](https://logback.qos.ch/manual/mdc.html).
-* [kotlinx-coroutines-play-services](kotlinx-coroutines-play-services) -- integration with Google Play Services [Tasks API](https://developers.google.com/android/guides/tasks). |
+* [kotlinx-coroutines-play-services](kotlinx-coroutines-play-services) -- integration with Google Play Services [Tasks API](https://developers.google.com/android/guides/tasks).
+* [kotlinx-coroutines-androidx-lifecycle](kotlinx-coroutines-androidx-lifecycle) -- integration with AndroidX [Lifecycle](https://developer.android.com/reference/kotlin/androidx/lifecycle/Lifecycle) and [LifecycleOwner](https://developer.android.com/reference/kotlin/androidx/lifecycle/LifecycleOwner).
 
 ## Contributing
 

integration/kotlinx-coroutines-androidx-lifecycle/README.md

@@ -0,0 +1,59 @@
+# Module kotlinx-coroutines-androidx-lifecycle
+
+Integration with AndroidX [Lifecycle](
+https://developer.android.com/reference/kotlin/androidx/lifecycle/Lifecycle
+) and [LifecycleOwner](
+https://developer.android.com/reference/kotlin/androidx/lifecycle/LifecycleOwner
+).
+
+Extension properties:
+
+| **Name** | **Description**
+| -------- | ---------------
+| [Lifecycle.coroutineScope][lifecycleScope] | A scope that dispatches on Android Main thread and is active until the Lifecycle is destroyed.
+| [LifecycleOwner.coroutineScope][lifecycleOwnerScope] | A scope that dispatches on Android Main thread and is active until the LifecycleOwner is destroyed.
+| [Lifecycle.job][lifecycleJob] | A job that is cancelled when the Lifecycle is destroyed.
+
+Extension functions:
+
+| **Name** | **Description**
+| -------- | ---------------
+| [Lifecycle.createJob][lifecycleCreateJob] | A job that is active while the state is at least the passed one.
+| [Lifecycle.createScope][lifecycleCreateScope] | A scope that dispatches on Android Main thread and is active while the state is at least the passed one.
+
+## Example
+
+```kotlin
+class MainActivity : AppCompatActivity() {
+
+    override fun onCreate(savedInstanceState: Bundle?) {
+        super.onCreate(savedInstanceState)
+        lifecycle.coroutineScope.launch {
+            someSuspendFunction()
+            someOtherSuspendFunction()
+            someCancellableSuspendFunction()
+        }
+    }
+
+    override fun onStart() {
+        super.onStart()
+        val startedScope = lifecycle.createScope(activeWhile = Lifecycle.State.STARTED)
+        startedScope.launch {
+            aCancellableSuspendFunction()
+            yetAnotherCancellableSuspendFunction()
+        }
+        startedScope.aMethodThatWillLaunchSomeCoroutines()
+    }
+}
+```
+
+# Package kotlinx.coroutines.androidx.lifecycle
+
+Integration with AndroidX [Lifecycle](https://developer.android.com/reference/kotlin/androidx/lifecycle/Lifecycle)
+and [LifecycleOwner](https://developer.android.com/reference/kotlin/androidx/lifecycle/LifecycleOwner).
+
+<!--- MODULE kotlinx-coroutines-core -->
+<!--- INDEX kotlinx.coroutines -->
+<!--- MODULE kotlinx-coroutines-androidx-lifecycle -->
+<!--- INDEX kotlinx.coroutines.androidx.lifecycle -->
+<!--- END -->

integration/kotlinx-coroutines-androidx-lifecycle/build.gradle

@@ -0,0 +1,92 @@
+import java.nio.file.Files
+import java.nio.file.NoSuchFileException
+import java.util.zip.ZipEntry
+import java.util.zip.ZipFile
+
+/*
+ * Copyright 2016-2018 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+ext.androidx_lifecycle_version = '2.0.0'
+
+repositories {
+    google()
+}
+
+def attr = Attribute.of("artifactType", String.class)
+configurations {
+    aar {
+        attributes { attribute(attr, ArtifactTypeDefinition.JAR_TYPE) }
+        sourceSets.main.compileClasspath += it
+        sourceSets.test.compileClasspath += it
+        sourceSets.test.runtimeClasspath += it
+    }
+    aarTest {
+        attributes { attribute(attr, ArtifactTypeDefinition.JAR_TYPE) }
+        sourceSets.test.compileClasspath += it
+        sourceSets.test.runtimeClasspath += it
+    }
+}
+
+sourceSets {
+    test {
+        resources.srcDirs = ["test/resources"]
+    }
+}
+
+dependencies {
+    registerTransform {
+        from.attribute(attr, "aar")
+        to.attribute(attr, "jar")
+        artifactTransform(ExtractJars.class)
+    }
+    aar("androidx.lifecycle:lifecycle-common:$androidx_lifecycle_version")
+    aarTest("androidx.lifecycle:lifecycle-runtime:$androidx_lifecycle_version")
+    api project(":kotlinx-coroutines-android")
+}
+
+tasks.withType(dokka.getClass()) {
+    externalDocumentationLink {
+        url = new URL("https://developer.android.com/reference/androidx/")
+    }
+}
+
+class ExtractJars extends ArtifactTransform {
+    @Override
+    List<File> transform(File input) {
+        unzip(input)
+
+        List<File> jars = new ArrayList<>()
+        outputDirectory.traverse(nameFilter: ~/.*\.jar/) { jars += it }
+
+        return jars
+    }
+
+    private void unzip(File zipFile) {
+        ZipFile zip
+        try {
+            zip = new ZipFile(zipFile)
+            for (entry in zip.entries()) {
+                unzipEntryTo(zip, entry)
+            }
+        } finally {
+            if (zip != null) zip.close()
+        }
+    }
+
+    private void unzipEntryTo(ZipFile zip, ZipEntry entry) {
+        File output = new File(outputDirectory, entry.name)
+        if (entry.isDirectory()) {
+            output.mkdirs()
+        } else {
+            InputStream stream
+            try {
+                stream = zip.getInputStream(entry)
+                Files.copy(stream, output.toPath())
+            } catch (NoSuchFileException ignored) {
+            } finally {
+                if (stream != null) stream.close()
+            }
+        }
+    }
+}

integration/kotlinx-coroutines-androidx-lifecycle/src/Lifecycle.kt

@@ -0,0 +1,49 @@
+package kotlinx.coroutines.androidx.lifecycle
+
+import androidx.lifecycle.GenericLifecycleObserver
+import androidx.lifecycle.Lifecycle
+import androidx.lifecycle.Lifecycle.State.INITIALIZED
+import androidx.lifecycle.LifecycleOwner
+import kotlinx.coroutines.*
+
+/**
+ * Returns a [CoroutineScope] that uses [Dispatchers.Main] by default, and that will be cancelled as
+ * soon as this [Lifecycle] [currentState][Lifecycle.getCurrentState] is no longer
+ * [at least][Lifecycle.State.isAtLeast] the passed [activeWhile] state.
+ *
+ * **Beware**: if the current state is lower than the passed [activeWhile] state, you'll get an
+ * already cancelled scope.
+ */
+fun Lifecycle.createScope(activeWhile: Lifecycle.State): CoroutineScope {
+    return CoroutineScope(createJob(activeWhile) + Dispatchers.Main)
+}
+
+/**
+ * Creates a [SupervisorJob] that will be cancelled as soon as this [Lifecycle]
+ * [currentState][Lifecycle.getCurrentState] is no longer [at least][Lifecycle.State.isAtLeast] the
+ * passed [activeWhile] state.
+ *
+ * **Beware**: if the current state is lower than the passed [activeWhile] state, you'll get an
+ * already cancelled job.
+ */
+fun Lifecycle.createJob(activeWhile: Lifecycle.State = INITIALIZED): Job {
+    require(activeWhile != Lifecycle.State.DESTROYED) {
+        "DESTROYED is a terminal state that is forbidden for createJob(…), to avoid leaks."
+    }
+    return SupervisorJob().also { job ->
+        when (currentState) {
+            Lifecycle.State.DESTROYED -> job.cancel() // Fast path if already destroyed
+            else -> GlobalScope.launch(Dispatchers.Main) { // State is usually synced on next loop,
+                // this allows to use STARTED from onStart in Activities for example.
+                addObserver(object : GenericLifecycleObserver {
+                    override fun onStateChanged(source: LifecycleOwner?, event: Lifecycle.Event) {
+                        if (!currentState.isAtLeast(activeWhile)) {
+                            removeObserver(this)
+                            job.cancel()
+                        }
+                    }
+                })
+            }
+        }
+    }
+}

integration/kotlinx-coroutines-androidx-lifecycle/src/LifecycleDefaultScopes.kt

@@ -0,0 +1,52 @@
+package kotlinx.coroutines.androidx.lifecycle
+
+import androidx.lifecycle.Lifecycle
+import androidx.lifecycle.LifecycleOwner
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.Job
+import kotlinx.coroutines.SupervisorJob
+import java.util.concurrent.ConcurrentHashMap
+
+/**
+ * Returns a [CoroutineScope] that uses [Dispatchers.Main] by default, and that is cancelled when
+ * the [Lifecycle] reaches [Lifecycle.State.DESTROYED] state.
+ *
+ * Note that this value is cached until the Lifecycle reaches the destroyed state.
+ */
+val Lifecycle.coroutineScope: CoroutineScope
+    get() = cachedLifecycleCoroutineScopes[this] ?: job.let { job ->
+        val newScope = CoroutineScope(job + Dispatchers.Main)
+        if (job.isActive) {
+            cachedLifecycleCoroutineScopes[this] = newScope
+            job.invokeOnCompletion { _ -> cachedLifecycleCoroutineScopes -= this }
+        }
+        newScope
+    }
+
+/**
+ * Calls [Lifecycle.coroutineScope] for the [Lifecycle] of this [LifecycleOwner].
+ *
+ * This is an inline property, just there for convenient usage from any [LifecycleOwner],
+ * like FragmentActivity, AppCompatActivity, Fragment and LifecycleService.
+ */
+inline val LifecycleOwner.coroutineScope get() = lifecycle.coroutineScope
+
+/**
+ * Returns a [SupervisorJob] that will be cancelled as soon as the [Lifecycle] reaches
+ * [Lifecycle.State.DESTROYED] state.
+ *
+ * Note that this value is cached until the Lifecycle reaches the destroyed state.
+ *
+ * You can use this job for custom [CoroutineScope]s, or as a parent [Job].
+ */
+val Lifecycle.job: Job
+    get() = cachedLifecycleJobs[this] ?: createJob().also {
+        if (it.isActive) {
+            cachedLifecycleJobs[this] = it
+            it.invokeOnCompletion { _ -> cachedLifecycleJobs -= this }
+        }
+    }
+
+private val cachedLifecycleJobs = ConcurrentHashMap<Lifecycle, Job>()
+private val cachedLifecycleCoroutineScopes = ConcurrentHashMap<Lifecycle, CoroutineScope>()