Merge "Update ComponentCallbacks2" into main

import java.lang.annotation.RetentionPolicy;

/**

 * Extended {@link ComponentCallbacks} interface with a new callback for

 * finer-grained memory management. This interface is available in all application components

 * ({@link android.app.Activity}, {@link android.app.Service},

 * {@link ContentProvider}, and {@link android.app.Application}).

 *

 * <p>You should implement {@link #onTrimMemory} to incrementally release memory based on current

 * system constraints. Using this callback to release your resources helps provide a more

 * responsive system overall, but also directly benefits the user experience for

 * your app by allowing the system to keep your process alive longer. That is,

 * if you <em>don't</em> trim your resources based on memory levels defined by this callback,

 * the system is more likely to kill your process while it is cached in the least-recently used

 * (LRU) list, thus requiring your app to restart and restore all state when the user returns to it.

 *

 * <p>The values provided by {@link #onTrimMemory} do not represent a single linear progression of

 * memory limits, but provide you different types of clues about memory availability:</p>

 * Callbacks for app state transitions that can be used to improve background memory management.

 * This interface is available in all application components ({@link android.app.Activity}, {@link

 * android.app.Service}, {@link ContentProvider}, and {@link android.app.Application}).

 *

 * <p>You should implement {@link #onTrimMemory} to release memory when your app goes to background

 * states. Doing so helps the system keep your app's process cached in memory for longer, such that

 * the next time that the user brings your app to the foreground, the app will perform a <a

 * href="{@docRoot}topic/performance/vitals/launch-time">warm or hot start</a>, resuming faster and

 * retaining state.

 *

 * <h2>Trim memory levels and how to handle them</h2>

 *

 * <ul>

 * <li>When your app is running:

 *  <ol>

 *  <li>{@link #TRIM_MEMORY_RUNNING_MODERATE} <br>The device is beginning to run low on memory.

 * Your app is running and not killable.

 *  <li>{@link #TRIM_MEMORY_RUNNING_LOW} <br>The device is running much lower on memory.

 * Your app is running and not killable, but please release unused resources to improve system

 * performance (which directly impacts your app's performance).

 *  <li>{@link #TRIM_MEMORY_RUNNING_CRITICAL} <br>The device is running extremely low on memory.

 * Your app is not yet considered a killable process, but the system will begin killing

 * background processes if apps do not release resources, so you should release non-critical

 * resources now to prevent performance degradation.

 *  </ol>

 * </li>

 * <li>When your app's visibility changes:

 *  <ol>

 *  <li>{@link #TRIM_MEMORY_UI_HIDDEN} <br>Your app's UI is no longer visible, so this is a good

 * time to release large resources that are used only by your UI.

 *  </ol>

 * </li>

 * <li>When your app's process resides in the background LRU list:

 *  <ol>

 *  <li>{@link #TRIM_MEMORY_BACKGROUND} <br>The system is running low on memory and your process is

 * near the beginning of the LRU list. Although your app process is not at a high risk of being

 * killed, the system may already be killing processes in the LRU list, so you should release

 * resources that are easy to recover so your process will remain in the list and resume

 * quickly when the user returns to your app.

 *  <li>{@link #TRIM_MEMORY_MODERATE} <br>The system is running low on memory and your process is

 * near the middle of the LRU list. If the system becomes further constrained for memory, there's a

 * chance your process will be killed.

 *  <li>{@link #TRIM_MEMORY_COMPLETE} <br>The system is running low on memory and your process is

 * one of the first to be killed if the system does not recover memory now. You should release

 * absolutely everything that's not critical to resuming your app state.

 *   <p>To support API levels lower than 14, you can use the {@link #onLowMemory} method as a

 * fallback that's roughly equivalent to the {@link ComponentCallbacks2#TRIM_MEMORY_COMPLETE} level.

 *  </li>

 *  </ol>

 * <p class="note"><strong>Note:</strong> When the system begins

 * killing processes in the LRU list, although it primarily works bottom-up, it does give some

 * consideration to which processes are consuming more memory and will thus provide more gains in

 * memory if killed. So the less memory you consume while in the LRU list overall, the better

 * your chances are to remain in the list and be able to quickly resume.</p>

 * </li>

 *   <li>{@link #TRIM_MEMORY_UI_HIDDEN} <br>

 *       Your app's UI is no longer visible. This is a good time to release large memory allocations

 *       that are used only by your UI, such as {@link android.graphics.Bitmap Bitmaps}, or

 *       resources related to video playback or animations.

 *   <li>{@link #TRIM_MEMORY_BACKGROUND} <br>

 *       Your app's process is considered to be in the background, and has become eligible to be

 *       killed in order to free memory for other processes. Releasing more memory will prolong the

 *       time that your process can remain cached in memory. An effective strategy is to release

 *       resources that can be re-built when the user returns to your app.

 * </ul>

 * <p>More information about the different stages of a process lifecycle (such as what it means

 * to be placed in the background LRU list) is provided in the <a

 * href="{@docRoot}guide/components/processes-and-threads.html#Lifecycle">Processes and Threads</a>

 * document.

 *

 * <p>Apps that continue to do work for the user when they're not visible can respond to the {@link

 * #TRIM_MEMORY_UI_HIDDEN} callback by changing their behavior to favor lower memory usage. For

 * example, a music player may keep full-sized album art for all tracks in the currently playing

 * playlist as Bitmaps cached in memory. When the app is backgrounded but music playback continues,

 * the app can change the caching behavior to cache fewer, or smaller, Bitmaps in memory.

 *

 * <p>The ordinal values for trim levels represent an escalating series of memory pressure events,

 * with incrementing values accordingly. More states may be added in the future. As such, it's

 * important not to check for specific values, but rather check if the level passed to {@link

 * #onTrimMemory} is greater than or equal to the levels that your application handles. For example:

 *

 * <pre>{@code

 * public void onTrimMemory(int level) {

 *     if (level >= TRIM_MEMORY_BACKGROUND) {

 *         // Release any resources that can be rebuilt

 *         // quickly when the app returns to the foreground

 *         releaseResources();

 *     } else if (level >= TRIM_MEMORY_UI_HIDDEN) {

 *         // Release UI-related resources

 *         releaseUiResources();

 *     }

 * }

 * }</pre>

 *

 * <p class="note"><strong>Note:</strong> the runtime may invoke Garbage Collection (GC) in response

 * to application state changes. There is no need to explicitly invoke GC from your app.

 */

public interface ComponentCallbacks2 extends ComponentCallbacks {