diff --git a/decompose/src/commonMain/kotlin/com/arkivanov/decompose/router/children/ChildrenFactory.kt b/decompose/src/commonMain/kotlin/com/arkivanov/decompose/router/children/ChildrenFactory.kt index 07f9d164a..1f000a0f5 100644 --- a/decompose/src/commonMain/kotlin/com/arkivanov/decompose/router/children/ChildrenFactory.kt +++ b/decompose/src/commonMain/kotlin/com/arkivanov/decompose/router/children/ChildrenFactory.kt @@ -19,6 +19,8 @@ import kotlinx.serialization.Serializable * A convenience method for the main [children] method. Allows having `Serializable` navigation state [N], * so it's automatically saved and restored. This method can be used if the custom save/restore logic * is not required. + * + * **It is strongly recommended to call this method on the Main thread.** */ fun , C : Any, T : Any, E : Any, N : NavState, S : Any> Ctx.children( source: NavigationSource, @@ -74,6 +76,8 @@ fun , C : Any, T : Any, E : Any, N : NavState * calculates diffs between the old list of [ChildNavState] and the new one, and manipulates child * components as needed. * + * **It is strongly recommended to call this method on the Main thread.** + * * @param C a type of component configurations. * @param T a type of components. * @param E a type of navigation events. diff --git a/decompose/src/commonMain/kotlin/com/arkivanov/decompose/router/pages/ChildPagesFactory.kt b/decompose/src/commonMain/kotlin/com/arkivanov/decompose/router/pages/ChildPagesFactory.kt index 84fee183a..ad480cb3d 100644 --- a/decompose/src/commonMain/kotlin/com/arkivanov/decompose/router/pages/ChildPagesFactory.kt +++ b/decompose/src/commonMain/kotlin/com/arkivanov/decompose/router/pages/ChildPagesFactory.kt @@ -1,6 +1,5 @@ package com.arkivanov.decompose.router.pages -import com.arkivanov.decompose.ComponentContext import com.arkivanov.decompose.ExperimentalDecomposeApi import com.arkivanov.decompose.GenericComponentContext import com.arkivanov.decompose.router.children.ChildNavState @@ -19,6 +18,8 @@ import kotlinx.serialization.Serializable * Initializes and manages a list of components with one selected (active) component. * The list can be empty. * + * **It is strongly recommended to call this method on the Main thread.** + * * @param source a source of navigation events. * @param serializer an optional [KSerializer] to be used for serializing and deserializing configurations. * If `null` then the navigation state will not be preserved. @@ -85,6 +86,8 @@ private class SerializablePages( * Initializes and manages a list of components with one selected (active) component. * The list can be empty. * + * **It is strongly recommended to call this method on the Main thread.** + * * @param source a source of navigation events. * @param initialPages an initial state of Child Pages that should be set * if there is no saved state. See [Pages] for more information. diff --git a/decompose/src/commonMain/kotlin/com/arkivanov/decompose/router/slot/ChildSlotFactory.kt b/decompose/src/commonMain/kotlin/com/arkivanov/decompose/router/slot/ChildSlotFactory.kt index 102d6331e..28eb423af 100644 --- a/decompose/src/commonMain/kotlin/com/arkivanov/decompose/router/slot/ChildSlotFactory.kt +++ b/decompose/src/commonMain/kotlin/com/arkivanov/decompose/router/slot/ChildSlotFactory.kt @@ -16,6 +16,8 @@ import kotlinx.serialization.KSerializer * Initializes and manages a slot for one child component. * The child component can be either active or dismissed (destroyed). * + * **It is strongly recommended to call this method on the Main thread.** + * * @param source a source of navigation events. * @param serializer an optional [KSerializer] to be used for serializing and deserializing configurations. * If `null` then the navigation state will not be preserved. @@ -61,6 +63,8 @@ fun , C : Any, T : Any> Ctx.childSlot( * Initializes and manages a slot for one child component. * The child component can be either active or dismissed (destroyed). * + * **It is strongly recommended to call this method on the Main thread.** + * * @param source a source of navigation events. * @param key a key of the slot, must be unique within the parent (hosting) component. * @param saveConfiguration a function that saves the provided configuration into [SerializableContainer]. diff --git a/decompose/src/commonMain/kotlin/com/arkivanov/decompose/router/stack/ChildStackFactory.kt b/decompose/src/commonMain/kotlin/com/arkivanov/decompose/router/stack/ChildStackFactory.kt index 9aa9ae179..4bb00bf8a 100644 --- a/decompose/src/commonMain/kotlin/com/arkivanov/decompose/router/stack/ChildStackFactory.kt +++ b/decompose/src/commonMain/kotlin/com/arkivanov/decompose/router/stack/ChildStackFactory.kt @@ -17,6 +17,8 @@ import kotlinx.serialization.builtins.ListSerializer /** * Initializes and manages a stack of components. * + * **It is strongly recommended to call this method on the Main thread.** + * * @param source a source of navigation events. * @param serializer an optional [KSerializer] to be used for serializing and deserializing configurations. * If `null` then the navigation state will not be preserved. @@ -60,6 +62,8 @@ fun , C : Any, T : Any> Ctx.childStack( /** * A convenience extension function for [ComponentContext.childStack]. + * + * **It is strongly recommended to call this method on the Main thread.** */ fun , C : Any, T : Any> Ctx.childStack( source: NavigationSource>, @@ -81,6 +85,8 @@ fun , C : Any, T : Any> Ctx.childStack( /** * Initializes and manages a stack of components. * + * **It is strongly recommended to call this method on the Main thread.** + * * @param source a source of navigation events. * @param initialStack a stack of component configurations (ordered from tail to head) that should be set * if there is no saved state, must be not empty and unique. diff --git a/docs/navigation/overview.md b/docs/navigation/overview.md index 3bff4849e..60e7a5a73 100644 --- a/docs/navigation/overview.md +++ b/docs/navigation/overview.md @@ -40,9 +40,9 @@ Please make sure you [setup](https://github.com/Kotlin/kotlinx.serialization#set ## Navigation and the main thread -The navigation API is thread-safe, technically the navigation can be performed on any thread. However, it's strongly recommended to perform the navigation on the Main thread. Since the navigation is performed synchronously, Decompose instantiates components and calls lifecycle callbacks on the current thread. Navigating on a background thread may cause unexpected behaviour. +The navigation API is thread-safe, technically the navigation can be performed on any thread. However, it's strongly recommended to initialize and perform the navigation on the Main thread. Since the navigation is performed synchronously, Decompose instantiates components and calls lifecycle callbacks on the current thread. Navigating on a background thread may cause unexpected behaviour. !!!warning - Always perform the navigation on the Main thread. + Always initialize and perform the navigation on the Main thread. Decompose tries its best to detect when the navigation is performed on a non-main thread. When it happens, Decompose calls the special error handler - `onDecomposeError`. By default, it prints the exception to logs, however you can override the default behaviour by providing your own handler.