more javadocs for onTrimMemory()

Change-Id: I52a99bc1b07732e474d1c632f3021c6c4db8c5ab

2 files changed, 86 insertions, 11 deletions

diff --git a/core/java/android/content/ComponentCallbacks.java b/core/java/android/content/ComponentCallbacks.java
index dad60b0..b96c8d3 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}).
+ *
+ * <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 {
     /**
@@ -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.
-     * 
+     *
      * <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();
 }
diff --git a/core/java/android/content/ComponentCallbacks2.java b/core/java/android/content/ComponentCallbacks2.java
index a3b4e5e..b78548b 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}).
+ *
+ * <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 {