Loading core/java/android/content/ComponentCallbacks.java +24 −10 Original line number Diff line number Diff line Loading @@ -22,6 +22,11 @@ import android.content.res.Configuration; * The set of callback APIs that are common to all application components * ({@link android.app.Activity}, {@link android.app.Service}, * {@link ContentProvider}, and {@link android.app.Application}). * * <p class="note"><strong>Note:</strong> You should also implement the {@link * ComponentCallbacks2} interface, which provides the {@link * ComponentCallbacks2#onTrimMemory} callback to help your app manage its memory usage more * effectively.</p> */ public interface ComponentCallbacks { /** Loading @@ -34,21 +39,30 @@ public interface ComponentCallbacks { * object will have been updated to return resource values matching the * new configuration. * * <p>For more information, read <a href="{@docRoot}guide/topics/resources/runtime-changes.html" * >Handling Runtime Changes</a>. * * @param newConfig The new device configuration. */ void onConfigurationChanged(Configuration newConfig); /** * This is called when the overall system is running low on memory, and * would like actively running process to try to tighten their belt. While * actively running processes should trim their memory usage. While * the exact point at which this will be called is not defined, generally * it will happen around the time all background process have been killed, * that is before reaching the point of killing processes hosting * it will happen when all background process have been killed. * That is, before reaching the point of killing processes hosting * service and foreground UI that we would like to avoid killing. * * <p>Applications that want to be nice can implement this method to release * any caches or other unnecessary resources they may be holding on to. * The system will perform a gc for you after returning from this method. * <p>You should implement this method to release * any caches or other unnecessary resources you may be holding on to. * The system will perform a garbage collection for you after returning from this method. * <p>Preferably, you should implement {@link ComponentCallbacks2#onTrimMemory} from * {@link ComponentCallbacks2} to incrementally unload your resources based on various * levels of memory demands. That API is available for API level 14 and higher, so you should * only use this {@link #onLowMemory} method as a fallback for older versions, which can be * treated the same as {@link ComponentCallbacks2#onTrimMemory} with the {@link * ComponentCallbacks2#TRIM_MEMORY_COMPLETE} level.</p> */ void onLowMemory(); } core/java/android/content/ComponentCallbacks2.java +62 −1 Original line number Diff line number Diff line Loading @@ -18,7 +18,68 @@ package android.content; /** * Extended {@link ComponentCallbacks} interface with a new callback for * finer-grained memory management. * 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> * <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> * </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. */ public interface ComponentCallbacks2 extends ComponentCallbacks { Loading Loading
core/java/android/content/ComponentCallbacks.java +24 −10 Original line number Diff line number Diff line Loading @@ -22,6 +22,11 @@ import android.content.res.Configuration; * The set of callback APIs that are common to all application components * ({@link android.app.Activity}, {@link android.app.Service}, * {@link ContentProvider}, and {@link android.app.Application}). * * <p class="note"><strong>Note:</strong> You should also implement the {@link * ComponentCallbacks2} interface, which provides the {@link * ComponentCallbacks2#onTrimMemory} callback to help your app manage its memory usage more * effectively.</p> */ public interface ComponentCallbacks { /** Loading @@ -34,21 +39,30 @@ public interface ComponentCallbacks { * object will have been updated to return resource values matching the * new configuration. * * <p>For more information, read <a href="{@docRoot}guide/topics/resources/runtime-changes.html" * >Handling Runtime Changes</a>. * * @param newConfig The new device configuration. */ void onConfigurationChanged(Configuration newConfig); /** * This is called when the overall system is running low on memory, and * would like actively running process to try to tighten their belt. While * actively running processes should trim their memory usage. While * the exact point at which this will be called is not defined, generally * it will happen around the time all background process have been killed, * that is before reaching the point of killing processes hosting * it will happen when all background process have been killed. * That is, before reaching the point of killing processes hosting * service and foreground UI that we would like to avoid killing. * * <p>Applications that want to be nice can implement this method to release * any caches or other unnecessary resources they may be holding on to. * The system will perform a gc for you after returning from this method. * <p>You should implement this method to release * any caches or other unnecessary resources you may be holding on to. * The system will perform a garbage collection for you after returning from this method. * <p>Preferably, you should implement {@link ComponentCallbacks2#onTrimMemory} from * {@link ComponentCallbacks2} to incrementally unload your resources based on various * levels of memory demands. That API is available for API level 14 and higher, so you should * only use this {@link #onLowMemory} method as a fallback for older versions, which can be * treated the same as {@link ComponentCallbacks2#onTrimMemory} with the {@link * ComponentCallbacks2#TRIM_MEMORY_COMPLETE} level.</p> */ void onLowMemory(); }
core/java/android/content/ComponentCallbacks2.java +62 −1 Original line number Diff line number Diff line Loading @@ -18,7 +18,68 @@ package android.content; /** * Extended {@link ComponentCallbacks} interface with a new callback for * finer-grained memory management. * 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> * <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> * </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. */ public interface ComponentCallbacks2 extends ComponentCallbacks { Loading
