immediate

Returns dispatcher that executes coroutines immediately when it is already in the right context (e.g. current looper is the same as this handler's looper) without an additional re-dispatch.

Immediate dispatcher is safe from stack overflows and in case of nested invocations forms event-loop similar to Dispatchers.Unconfined. The event loop is an advanced topic and its implications can be found in Dispatchers.Unconfined documentation. The formed event-loop is shared with Unconfined and other immediate dispatchers, potentially overlapping tasks between them.

Example of usage:

suspend fun updateUiElement(val text: String) {
  /*
   * If it is known that updateUiElement can be invoked both from the Main thread and from other threads,
   * `immediate` dispatcher is used as a performance optimization to avoid unnecessary dispatch.
   *
   * In that case, when `updateUiElement` is invoked from the Main thread, `uiElement.text` will be
   * invoked immediately without any dispatching, otherwise, the `Dispatchers.Main` dispatch cycle will be triggered.
   */
  withContext(Dispatchers.Main.immediate) {
    uiElement.text = text
  }
  // Do context-independent logic such as logging
}

Method may throw UnsupportedOperationException if immediate dispatching is not supported by current dispatcher, please refer to specific dispatcher documentation.

Dispatchers.Main supports immediate execution for Android, JavaFx and Swing platforms.