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 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
