Skip to content

Commit d4b69f1

Browse files
committed
docs(android): Note the cost of reading INavScope.app
The member read as a cheap accessor, which invites call sites that run more often than once per navigation. It isn't: App's copy constructor isn't public, so an App can't be copied on its own, and NavScope goes through Contexts instead. That deep-copies every context on the scope -- on Android including a fully populated Device -- and discards all of it but the App. Document the caller-facing warning on INavScope.app and the mechanism behind it on NavScope.app, so the constraint sits where it is true and whoever replaces the copy later doesn't have to re-derive it. Also records why a copy is needed at all, which was undocumented: callers mutate the result before binding it to a transaction, so handing out the scope's live App would corrupt shared scope state.
1 parent 2733897 commit d4b69f1

2 files changed

Lines changed: 21 additions & 3 deletions

File tree

‎sentry-android-navigation3/src/main/kotlin/io/sentry/compose/navigation3/lifecycle/NavScope.kt‎

Lines changed: 18 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,15 @@ internal class NavScope(
3636
}
3737
}
3838

39+
/**
40+
* Copies the whole of [IScope.getContexts] in order to return a copy of its [App].
41+
*
42+
* [App]'s copy constructor isn't public, so an `App` can't be copied on its own. Going through
43+
* [Contexts] deep-copies every context on the scope and discards all of it but the `App`.
44+
*
45+
* Called once per navigation that changes the top of the back stack, so the cost is bounded.
46+
* Don't add call sites without reading [INavScope.app] first.
47+
*/
3948
override val app: App?
4049
get() = Contexts(delegate.contexts).app
4150

@@ -106,7 +115,15 @@ internal interface INavScope {
106115

107116
var screen: String?
108117

109-
/** A copy of the scope's app context, if any. */
118+
/**
119+
* A copy of the scope's app context, if any.
120+
*
121+
* A copy rather than the live instance, because callers mutate the result before binding it to a
122+
* transaction, and mutating the scope's own [App] would corrupt shared scope state.
123+
*
124+
* Implementations may have to copy more than the [App] to produce it, so treat this as expensive:
125+
* read it once where it's needed rather than per frame or in a loop. See [NavScope.app].
126+
*/
110127
val app: App?
111128

112129
/**

‎sentry-android-navigation3/src/main/kotlin/io/sentry/compose/navigation3/lifecycle/NavScopes.kt‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -57,8 +57,9 @@ internal const val NAVIGATION_CONTEXT_KEY: String = "Navigation"
5757
* 1. each `SentryNavEffect` is called in the same composable as the `NavDisplay` it observes;
5858
* 2. no `SentryNavEffect` is called from inside a `NavDisplay`, e.g., from a nav entry, scene, or
5959
* entry decorator†;
60-
* 3. each Activity or Fragment calls at most one `SentryNavEffect` from its own content (Fragments
61-
* count separately from the Activity that hosts them); and
60+
* 3. each Activity or Fragment calls at most one `SentryNavEffect` from its own content (sibling
61+
* Fragments may each have their own effect, but not alongside one in the Activity hosting them);
62+
* and
6263
* 4. the user can interact with only one of those Activities or Fragments at a time.
6364
*
6465
* † Meant to ensure each effect's `LocalLifecycleOwner` is an Activity or a Fragment and not a

0 commit comments

Comments
 (0)