* 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 {
/**
* component is running. Note that, unlike activities, other components
* are never restarted when a configuration changes: they must always deal
* with the results of the change, such as by re-retrieving resources.
- *
+ *
* <p>At the time that this function has been called, your Resources
* 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();
}
/**
* 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 {
OSDN Git Service
