1/*
2 * Copyright (C) 2006 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
17package android.content;
18
19import android.annotation.IntDef;
20
21import java.lang.annotation.Retention;
22import java.lang.annotation.RetentionPolicy;
23
24/**
25 * Extended {@link ComponentCallbacks} interface with a new callback for
26 * finer-grained memory management. This interface is available in all application components
27 * ({@link android.app.Activity}, {@link android.app.Service},
28 * {@link ContentProvider}, and {@link android.app.Application}).
29 *
30 * <p>You should implement {@link #onTrimMemory} to incrementally release memory based on current
31 * system constraints. Using this callback to release your resources helps provide a more
32 * responsive system overall, but also directly benefits the user experience for
33 * your app by allowing the system to keep your process alive longer. That is,
34 * if you <em>don't</em> trim your resources based on memory levels defined by this callback,
35 * the system is more likely to kill your process while it is cached in the least-recently used
36 * (LRU) list, thus requiring your app to restart and restore all state when the user returns to it.
37 *
38 * <p>The values provided by {@link #onTrimMemory} do not represent a single linear progression of
39 * memory limits, but provide you different types of clues about memory availability:</p>
40 * <ul>
41 * <li>When your app is running:
42 *  <ol>
43 *  <li>{@link #TRIM_MEMORY_RUNNING_MODERATE} <br>The device is beginning to run low on memory.
44 * Your app is running and not killable.
45 *  <li>{@link #TRIM_MEMORY_RUNNING_LOW} <br>The device is running much lower on memory.
46 * Your app is running and not killable, but please release unused resources to improve system
47 * performance (which directly impacts your app's performance).
48 *  <li>{@link #TRIM_MEMORY_RUNNING_CRITICAL} <br>The device is running extremely low on memory.
49 * Your app is not yet considered a killable process, but the system will begin killing
50 * background processes if apps do not release resources, so you should release non-critical
51 * resources now to prevent performance degradation.
52 *  </ol>
53 * </li>
54 * <li>When your app's visibility changes:
55 *  <ol>
56 *  <li>{@link #TRIM_MEMORY_UI_HIDDEN} <br>Your app's UI is no longer visible, so this is a good
57 * time to release large resources that are used only by your UI.
58 *  </ol>
59 * </li>
60 * <li>When your app's process resides in the background LRU list:
61 *  <ol>
62 *  <li>{@link #TRIM_MEMORY_BACKGROUND} <br>The system is running low on memory and your process is
63 * near the beginning of the LRU list. Although your app process is not at a high risk of being
64 * killed, the system may already be killing processes in the LRU list, so you should release
65 * resources that are easy to recover so your process will remain in the list and resume
66 * quickly when the user returns to your app.
67 *  <li>{@link #TRIM_MEMORY_MODERATE} <br>The system is running low on memory and your process is
68 * near the middle of the LRU list. If the system becomes further constrained for memory, there's a
69 * chance your process will be killed.
70 *  <li>{@link #TRIM_MEMORY_COMPLETE} <br>The system is running low on memory and your process is
71 * one of the first to be killed if the system does not recover memory now. You should release
72 * absolutely everything that's not critical to resuming your app state.
73 *   <p>To support API levels lower than 14, you can use the {@link #onLowMemory} method as a
74 * fallback that's roughly equivalent to the {@link ComponentCallbacks2#TRIM_MEMORY_COMPLETE} level.
75 *  </li>
76 *  </ol>
77 * <p class="note"><strong>Note:</strong> When the system begins
78 * killing processes in the LRU list, although it primarily works bottom-up, it does give some
79 * consideration to which processes are consuming more memory and will thus provide more gains in
80 * memory if killed. So the less memory you consume while in the LRU list overall, the better
81 * your chances are to remain in the list and be able to quickly resume.</p>
82 * </li>
83 * </ul>
84 * <p>More information about the different stages of a process lifecycle (such as what it means
85 * to be placed in the background LRU list) is provided in the <a
86 * href="{@docRoot}guide/components/processes-and-threads.html#Lifecycle">Processes and Threads</a>
87 * document.
88 */
89public interface ComponentCallbacks2 extends ComponentCallbacks {
90
91    /** @hide */
92    @IntDef(prefix = { "TRIM_MEMORY_" }, value = {
93            TRIM_MEMORY_COMPLETE,
94            TRIM_MEMORY_MODERATE,
95            TRIM_MEMORY_BACKGROUND,
96            TRIM_MEMORY_UI_HIDDEN,
97            TRIM_MEMORY_RUNNING_CRITICAL,
98            TRIM_MEMORY_RUNNING_LOW,
99            TRIM_MEMORY_RUNNING_MODERATE,
100    })
101    @Retention(RetentionPolicy.SOURCE)
102    public @interface TrimMemoryLevel {}
103
104    /**
105     * Level for {@link #onTrimMemory(int)}: the process is nearing the end
106     * of the background LRU list, and if more memory isn't found soon it will
107     * be killed.
108     */
109    static final int TRIM_MEMORY_COMPLETE = 80;
110
111    /**
112     * Level for {@link #onTrimMemory(int)}: the process is around the middle
113     * of the background LRU list; freeing memory can help the system keep
114     * other processes running later in the list for better overall performance.
115     */
116    static final int TRIM_MEMORY_MODERATE = 60;
117
118    /**
119     * Level for {@link #onTrimMemory(int)}: the process has gone on to the
120     * LRU list.  This is a good opportunity to clean up resources that can
121     * efficiently and quickly be re-built if the user returns to the app.
122     */
123    static final int TRIM_MEMORY_BACKGROUND = 40;
124
125    /**
126     * Level for {@link #onTrimMemory(int)}: the process had been showing
127     * a user interface, and is no longer doing so.  Large allocations with
128     * the UI should be released at this point to allow memory to be better
129     * managed.
130     */
131    static final int TRIM_MEMORY_UI_HIDDEN = 20;
132
133    /**
134     * Level for {@link #onTrimMemory(int)}: the process is not an expendable
135     * background process, but the device is running extremely low on memory
136     * and is about to not be able to keep any background processes running.
137     * Your running process should free up as many non-critical resources as it
138     * can to allow that memory to be used elsewhere.  The next thing that
139     * will happen after this is {@link #onLowMemory()} called to report that
140     * nothing at all can be kept in the background, a situation that can start
141     * to notably impact the user.
142     */
143    static final int TRIM_MEMORY_RUNNING_CRITICAL = 15;
144
145    /**
146     * Level for {@link #onTrimMemory(int)}: the process is not an expendable
147     * background process, but the device is running low on memory.
148     * Your running process should free up unneeded resources to allow that
149     * memory to be used elsewhere.
150     */
151    static final int TRIM_MEMORY_RUNNING_LOW = 10;
152
153    /**
154     * Level for {@link #onTrimMemory(int)}: the process is not an expendable
155     * background process, but the device is running moderately low on memory.
156     * Your running process may want to release some unneeded resources for
157     * use elsewhere.
158     */
159    static final int TRIM_MEMORY_RUNNING_MODERATE = 5;
160
161    /**
162     * Called when the operating system has determined that it is a good
163     * time for a process to trim unneeded memory from its process.  This will
164     * happen for example when it goes in the background and there is not enough
165     * memory to keep as many background processes running as desired.  You
166     * should never compare to exact values of the level, since new intermediate
167     * values may be added -- you will typically want to compare if the value
168     * is greater or equal to a level you are interested in.
169     *
170     * <p>To retrieve the processes current trim level at any point, you can
171     * use {@link android.app.ActivityManager#getMyMemoryState
172     * ActivityManager.getMyMemoryState(RunningAppProcessInfo)}.
173     *
174     * @param level The context of the trim, giving a hint of the amount of
175     * trimming the application may like to perform.
176     */
177    void onTrimMemory(@TrimMemoryLevel int level);
178}
179