1 /* 2 * Copyright 2021 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 package androidx.compose.runtime 18 19 /** 20 * Objects implementing this interface are notified when they are initially used in a composition 21 * and when they are no longer being used. 22 * 23 * An object is [remembered][onRemembered] by the composition if it is [remember]ed in at least one 24 * place in a composition. Compose may implicitly [remember] an object if doing so is required to 25 * restart the composition later, such as for composable function parameters. An object is 26 * [forgotten][onForgotten] when it is no longer [remember]ed anywhere in that composition. If a 27 * single instance is [remember]ed in more than one location in the same composition, its 28 * [onRemembered] and [onForgotten] will be called for each location in the composition. 29 * 30 * When objects implementing this interface is remembered and forgotten together, the order of 31 * [onForgotten] is guaranteed to be called in the opposite order of [onRemembered]. For example, if 32 * two objects, A and B are [remember]ed together, A followed by B, [onRemembered] will be called 33 * first on A then on B. If they forgotten together then [onForgotten] will be called on B first 34 * then on A. 35 * 36 * Implementations of [RememberObserver] should generally not expose those object references outside 37 * of their immediate usage sites. A [RememberObserver] reference that is propagated to multiple 38 * parts of a composition might remain present in the composition for longer than expected if it is 39 * remembered (explicitly or implicitly) elsewhere, and a [RememberObserver] that appears more once 40 * can have its callback methods called multiple times in no meaningful order and on multiple 41 * threads. 42 * 43 * An object remembered in only one place in only one composition is guaranteed to, 44 * 1. have either [onRemembered] or [onAbandoned] called 45 * 2. if [onRemembered] is called, [onForgotten] will eventually be called 46 */ 47 @Suppress("CallbackName") 48 interface RememberObserver { 49 /** 50 * Called when this object is successfully remembered by a composition. This method is called on 51 * the composition's **apply thread.** 52 */ onRememberednull53 fun onRemembered() 54 55 /** 56 * Called when this object is forgotten by a composition. This method is called on the 57 * composition's **apply thread.** 58 */ 59 fun onForgotten() 60 61 /** 62 * Called when this object is returned by the callback to `remember` but is not successfully 63 * remembered by a composition. 64 */ 65 fun onAbandoned() 66 } 67