dispatch-android-lifecycle/dispatch.android.lifecycle/DispatchLifecycleScope/launchOnStart

launchOnStart

fun launchOnStart(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.STARTED.

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.STARTED.

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.launchOnStart(minimumStatePolicy = CANCEL) {
          viewModel.someFlow.collect {
            channel.send("$it")
          }
        }
      }
    }

    val fragment = SomeFragment()

    history.add("starting")
    fragment.start()

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

    // stopping the lifecycle cancels the existing Job
    history.add("stopping")
    fragment.stop()

    // starting the lifecycle does not create a new Job

    history shouldBe listOf(
      "starting",
      "0",
      "1",
      "2",
      "stopping"
    )
  } 
   //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.launchOnStart {
          viewModel.someFlow.collect {
            channel.send("$it")
          }
        }
      }
    }

    val fragment = SomeFragment()

    history.add("starting")
    fragment.start()

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

    // stopping the lifecycle cancels the existing Job
    history.add("stopping")
    fragment.stop()

    // starting the lifecycle creates a new Job
    history.add("starting")
    fragment.start()

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

    history.add("stopping")
    fragment.stop()

    history shouldBe listOf(
      "starting",
      "0",
      "1",
      "2",
      "stopping",
      "starting",
      "0",
      "1",
      "2",
      "stopping"
    )
  } 
   //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.

block

the action to be performed

Sources

androidJvm source