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 17 package android.content; 18 19 import android.annotation.IntDef; 20 21 import java.lang.annotation.Retention; 22 import 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 */ 89 public 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 * @deprecated Apps are not notified of this level since API level 34 110 */ 111 @Deprecated 112 static final int TRIM_MEMORY_COMPLETE = 80; 113 114 /** 115 * Level for {@link #onTrimMemory(int)}: the process is around the middle 116 * of the background LRU list; freeing memory can help the system keep 117 * other processes running later in the list for better overall performance. 118 * 119 * @deprecated Apps are not notified of this level since API level 34 120 */ 121 @Deprecated 122 static final int TRIM_MEMORY_MODERATE = 60; 123 124 /** 125 * Level for {@link #onTrimMemory(int)}: the process has gone on to the 126 * LRU list. This is a good opportunity to clean up resources that can 127 * efficiently and quickly be re-built if the user returns to the app. 128 */ 129 static final int TRIM_MEMORY_BACKGROUND = 40; 130 131 /** 132 * Level for {@link #onTrimMemory(int)}: the process had been showing 133 * a user interface, and is no longer doing so. Large allocations with 134 * the UI should be released at this point to allow memory to be better 135 * managed. 136 */ 137 static final int TRIM_MEMORY_UI_HIDDEN = 20; 138 139 /** 140 * Level for {@link #onTrimMemory(int)}: the process is not an expendable 141 * background process, but the device is running extremely low on memory 142 * and is about to not be able to keep any background processes running. 143 * Your running process should free up as many non-critical resources as it 144 * can to allow that memory to be used elsewhere. The next thing that 145 * will happen after this is {@link #onLowMemory()} called to report that 146 * nothing at all can be kept in the background, a situation that can start 147 * to notably impact the user. 148 * 149 * @deprecated Apps are not notified of this level since API level 34 150 */ 151 @Deprecated 152 static final int TRIM_MEMORY_RUNNING_CRITICAL = 15; 153 154 /** 155 * Level for {@link #onTrimMemory(int)}: the process is not an expendable 156 * background process, but the device is running low on memory. 157 * Your running process should free up unneeded resources to allow that 158 * memory to be used elsewhere. 159 * 160 * @deprecated Apps are not notified of this level since API level 34 161 */ 162 @Deprecated 163 static final int TRIM_MEMORY_RUNNING_LOW = 10; 164 165 /** 166 * Level for {@link #onTrimMemory(int)}: the process is not an expendable 167 * background process, but the device is running moderately low on memory. 168 * Your running process may want to release some unneeded resources for 169 * use elsewhere. 170 * 171 * @deprecated Apps are not notified of this level since API level 34 172 */ 173 @Deprecated 174 static final int TRIM_MEMORY_RUNNING_MODERATE = 5; 175 176 /** 177 * Called when the operating system has determined that it is a good 178 * time for a process to trim unneeded memory from its process. 179 * 180 * You should never compare to exact values of the level, since new 181 * intermediate values may be added -- you will typically want to compare if 182 * the value is greater or equal to a level you are interested in. 183 * 184 * <p>To retrieve the processes current trim level at any point, you can 185 * use {@link android.app.ActivityManager#getMyMemoryState 186 * ActivityManager.getMyMemoryState(RunningAppProcessInfo)}. 187 * 188 * @param level The context of the trim, giving a hint of the amount of 189 * trimming the application may like to perform. 190 */ onTrimMemory(@rimMemoryLevel int level)191 void onTrimMemory(@TrimMemoryLevel int level); 192 } 193