IssueTracker

This is an inherently unsafe thing to ask for (which is why we have no built in support for this use case), but to explain why, I'll need to go into a lot of detail with what 'running suspend code when a lifecycle state is at least X' implies.

Namely: What behavior do you want to have if the Lifecycle falls below your chosen Lifecycle.State while your suspending work is running?

The way the when APIs worked is that the work was paused - when you hit a suspension point, your code just wouldn't run anymore. This is purposefully not supported anymore (as it could leave things hanging for a very long time if for instance the user hit the Home button).

So the only other options are (ignoring the case when the Lifecycle is DESTROYED and the whole coroutine scope is cancelled):

1. Let the suspending code continue to run to completion.

This has the benefit that the entire block runs atomically - i.e., it wouldn't be cancelled half way through.

That approach looks like:

lifecycleScope.launch {
  // Suspend until you are STARTED
  withStarted { }
  // Run your code that happens after you become STARTED here
  doYourOneTimeWork()
  // Note: your code will continue to run even if the Lifecycle falls below STARTED
}

This type of code comes with the assumption that your one time work does not depend on staying above your state, but that's not something a library could know. For example, if you run a FragmentTransaction after your suspending work, the state might be saved prior to that call happening.

2. Cancel the suspending code and restart it when you come back above that state.

This is exactly the contract for repeatOnLifecycle - re-running the block every time you go back above the given State. However, there's no way for a library to know if it is safe for you to re-run the entire block or if you need to checkpoint more often.

In the naive case, where you can run the entire block multiple times until it actually completes successfully, this is just tracking a isComplete flag:

lifecycleScope.launch {
  var isComplete = false
  repeatOnLifecycle(Lifecycle.State.STARTED) {
    if (!isComplete) {
      // Do your work here. It will be canceled if the Lifecycle
      // goes down while it is running
      doYourOneTimeWork()
      // Then mark the work as complete
      isComplete = true
    }
  }
}

Of course, the 'it is safe to rerun the entire block if it gets canceled half way through' is a really big assumption.

3. Cancel the suspending code and don't restart it

This is similar to the previous one, but uses a finally block to set the isComplete flag no matter if the work was cancelled or not.

lifecycleScope.launch {
  var isComplete = false
  repeatOnLifecycle(Lifecycle.State.STARTED) {
    if (!isComplete) {
      try {
        // Do your work here. It will be canceled if the Lifecycle
        // goes down while it is running
        doYourOneTimeWork()
      } finally {
        // By marking the work as complete in the finally block,
        // we never restart the block just leaving it potentially
        // half complete.
        isComplete = true
      }
    }
  }
}

I'm struggling to find a valid use case where you want to leave the work only partially finished, so I mostly include this for completeness.

I hope this gives a little more background on this problem space and why only we have the APIs we have - ideally, you'd avoid all of these cases entirely by not trying to run one-time suspending code when a lifecycle state is at least X.

Thanks for the detailed response! I think my majority use cases fall into either 1 or 3, i.e. if user initiated an action and then closed the activity/fragment, I would like the action (as a suspend block) to also get cancelled upon lifecycle reaching destroyed. I guess in fact for use case 3, I really just need lifecycleScope.launch without even needing repeatOnLifecycle. (In fact, it sounds like launchWhenCreated acts identically as launch...)

In examples 2 and 3 wouldn't repeatOnLifecycle continue to be executed every time the lifecycle state gets to STARTED, even after isComplete has been set to true? Is there no way to tell the repeatOnLifecycle function that it can stop repeating?

Re comment#4 - you can certainly cancel the Job that is returned by launch to cancel the whole code block if you want. Obviously that only works well if you are doing a naive all or nothing approach and not something where you are check-pointing at multiple points in your suspending block.