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