dispatch-android-lifecycle/dispatch.android.lifecycle/DispatchLifecycleScope/launchOnCreate

launchOnCreate

fun launchOnCreate(context: CoroutineContext = EmptyCoroutineContext, minimumStatePolicy: DispatchLifecycleScope.MinimumStatePolicy = MinimumStatePolicy.RESTART_EVERY, block: suspend CoroutineScope.() -> Unit): Job

Lifecycle-aware function for launching a coroutine any time the Lifecycle.State is at least Lifecycle.State.CREATED.

block is executed using the receiver CoroutineScope's Job as a parent, but always executes using Dispatchers.Main as its CoroutineDispatcher.

Execution of block is cancelled when the receiver CoroutineScope is cancelled, or when lifecycle's Lifecycle.State drops below Lifecycle.State.CREATED.

Samples

import dispatch.android.lifecycle.DispatchLifecycleScope
import dispatch.android.lifecycle.DispatchLifecycleScope.MinimumStatePolicy.CANCEL
import dispatch.android.lifecycle.dispatchLifecycleScope
import dispatch.core.DispatcherProvider
import dispatch.core.launchMain
import dispatch.internal.test.Sample5
import dispatch.internal.test.android.LiveDataTest
import dispatch.test.CoroutineTest
import io.kotest.matchers.shouldBe
import kotlinx.coroutines.CoroutineScope
import kotlinx.coroutines.ExperimentalCoroutinesApi
import kotlinx.coroutines.Job
import kotlinx.coroutines.channels.Channel
import kotlinx.coroutines.flow.collect
import kotlinx.coroutines.flow.flow
import kotlinx.coroutines.runBlocking
fun main() { 
   //sampleStart 
   runBlocking {

    val channel = Channel<String>()
    val history = mutableListOf<String>()

    class SomeViewModel {
      val someFlow = flow {
        repeat(100) {
          emit(it)
        }
      }
    }

    class SomeFragment : Fragment() {

      val viewModel = SomeViewModel()

      init {

        dispatchLifecycleScope.launchOnCreate(minimumStatePolicy = CANCEL) {
          viewModel.someFlow.collect {
            channel.send("$it")
          }
        }
      }
    }

    val fragment = SomeFragment()

    history.add("creating")
    fragment.create()

    repeat(3) {
      history.add(channel.receive())
    }

    // destroying the lifecycle cancels the lifecycleScope
    history.add("destroying")
    fragment.destroy()

    history shouldBe listOf(
      "creating",
      "0",
      "1",
      "2",
      "destroying"
    )
  } 
   //sampleEnd
}

import dispatch.android.lifecycle.DispatchLifecycleScope
import dispatch.android.lifecycle.DispatchLifecycleScope.MinimumStatePolicy.CANCEL
import dispatch.android.lifecycle.dispatchLifecycleScope
import dispatch.core.DispatcherProvider
import dispatch.core.launchMain
import dispatch.internal.test.Sample5
import dispatch.internal.test.android.LiveDataTest
import dispatch.test.CoroutineTest
import io.kotest.matchers.shouldBe
import kotlinx.coroutines.CoroutineScope
import kotlinx.coroutines.ExperimentalCoroutinesApi
import kotlinx.coroutines.Job
import kotlinx.coroutines.channels.Channel
import kotlinx.coroutines.flow.collect
import kotlinx.coroutines.flow.flow
import kotlinx.coroutines.runBlocking
fun main() { 
   //sampleStart 
   runBlocking {

    val channel = Channel<String>()
    val history = mutableListOf<String>()

    class SomeViewModel {
      val someFlow = flow {
        repeat(100) {
          emit(it)
        }
      }
    }

    class SomeFragment : Fragment() {

      val viewModel = SomeViewModel()

      init {

        dispatchLifecycleScope.launchOnCreate {
          viewModel.someFlow.collect {
            channel.send("$it")
          }
        }
      }
    }

    val fragment = SomeFragment()

    history.add("creating")
    fragment.create()

    repeat(3) {
      history.add(channel.receive())
    }

    // destroying the lifecycle cancels the lifecycleScope
    history.add("destroying")
    fragment.destroy()

    history shouldBe listOf(
      "creating",
      "0",
      "1",
      "2",
      "destroying"
    )
  } 
   //sampleEnd
}

Parameters

context

optional - additional to CoroutineScope.coroutineContext context of the coroutine.

minimumStatePolicy

optional - the way this Job will behave when passing below the minimum state or re-entering. Uses MinimumStatePolicy.RESTART_EVERY by default. Note that for a normal Lifecycle, there is no returning from below a CREATED state, so the minimumStatePolicy is largely irrelevant.

block

the action to be performed

Sources

androidJvm source