From a23fd88729bd10c02a9d631c9954616b3a1d0f6f Mon Sep 17 00:00:00 2001 From: Scott Main Date: Thu, 15 Aug 2013 13:53:31 -0700 Subject: [PATCH] more javadocs for onTrimMemory() Change-Id: I52a99bc1b07732e474d1c632f3021c6c4db8c5ab --- core/java/android/content/ComponentCallbacks.java | 34 ++++++++---- core/java/android/content/ComponentCallbacks2.java | 63 +++++++++++++++++++++- 2 files changed, 86 insertions(+), 11 deletions(-) diff --git a/core/java/android/content/ComponentCallbacks.java b/core/java/android/content/ComponentCallbacks.java index dad60b0d2121..b96c8d38f99d 100644 --- a/core/java/android/content/ComponentCallbacks.java +++ b/core/java/android/content/ComponentCallbacks.java @@ -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}). + * + *

Note: 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.

*/ public interface ComponentCallbacks { /** @@ -29,26 +34,35 @@ 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. - * + * *

At the time that this function has been called, your Resources * object will have been updated to return resource values matching the * new configuration. - * + * + *

For more information, read Handling Runtime Changes. + * * @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. - * - *

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. + * + *

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. + *

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.

*/ void onLowMemory(); } diff --git a/core/java/android/content/ComponentCallbacks2.java b/core/java/android/content/ComponentCallbacks2.java index a3b4e5efb583..b78548b873b1 100644 --- a/core/java/android/content/ComponentCallbacks2.java +++ b/core/java/android/content/ComponentCallbacks2.java @@ -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}). + * + *

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 don't 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. + * + *

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:

+ * + *

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 Processes and Threads + * document. */ public interface ComponentCallbacks2 extends ComponentCallbacks { -- 2.11.0