RememberObserver.kt

/*
 * Copyright 2021 The Android Open Source Project
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package androidx.compose.runtime

/**
 * Objects implementing this interface are notified when they are initially used in a composition
 * and when they are no longer being used.
 *
 * An object is [remembered][onRemembered] by the composition if it is [remember]ed in at least
 * one place in a composition. Compose may implicitly [remember] an object if doing so is
 * required to restart the composition later, such as for composable function parameters. An
 * object is [forgotten][onForgotten] when it is no longer [remember]ed anywhere in that
 * composition. If a single instance is [remember]ed in more than one location in
 * the same composition, its [onRemembered] and [onForgotten] will be called for each location in
 * the composition.
 *
 * When objects implementing this interface is remmembered and forgotten together,
 * the order of [onForgotten] is guaranteed to be called in the opposite order of [onRemembered].
 * For example, if two objects, A and B are [remember]ed together, A followed by B,
 * [onRemembered] will be called first on A then on B. If they forgotten together then
 * [onForgotten] will be called on B first then on A.
 *
 * Implementations of [RememberObserver] should generally not expose those object references
 * outside of their immediate usage sites. A [RememberObserver] reference that is propagated to
 * multiple parts of a composition might remain present in the composition for longer than
 * expected if it is remembered (explicitly or implicitly) elsewhere, and a [RememberObserver]
 * that appears more once can have its callback methods called multiple times in no meaningful
 * order and on multiple threads.
 *
 * An object remembered in only one place in only one composition is guaranteed to,
 *
 * 1. have either [onRemembered] or [onAbandoned] called
 * 2. if [onRemembered] is called, [onForgotten] will eventually be called
 */
@Suppress("CallbackName")
interface RememberObserver {
    /**
     * Called when this object is successfully remembered by a composition. This method is called on
     * the composition's **apply thread.**
     */
    fun onRemembered()

    /**
     * Called when this object is forgotten by a composition. This method is called on the
     * composition's **apply thread.**
     */
    fun onForgotten()

    /**
     * Called when this object is returned by the callback to `remember` but is not successfully
     * remembered by a composition.
     */
    fun onAbandoned()
}