Document memory coordinator

base/memory/memory_coordinator_client.h

Index: base/memory/memory_coordinator_client.h
diff --git a/base/memory/memory_coordinator_client.h b/base/memory/memory_coordinator_client.h
index da7104a8d94395decb299f15e86aa79069ce2e32..6e0ce6309eb1d52675cac7428db9cc77a6616f97 100644
--- a/base/memory/memory_coordinator_client.h
+++ b/base/memory/memory_coordinator_client.h
@@ -9,6 +9,16 @@
 
 namespace base {
 
+// OVERVIEW:
+//
+// MemoryCoordinatorClient is an interface which a component can implement to
+// respond to memory state changes. Unlike MemoryPressureListener, this is a
+// stateful mechanism and clients receive notifications only when memory states
+// are changed. State transitions are throttled to avoid thrashing; the exact
+// throttling period is platform dependent, but will be at least 5-10 seconds.
+// Clients are expected to make changes in memory usage that persist for the
+// duration of the memory state.
+
 // MemoryState is an indicator that processes can use to guide their memory
 // allocation policies. For example, a process that receives the suspended
 // state can use that as as signal to drop memory caches.
@@ -18,18 +28,29 @@ enum class MemoryState {
   // No memory constraints.
   NORMAL = 0,
   // Running and interactive but allocation should be throttled.
+  // Clients should free up any memory that is used as an optimization but
+  // that is not necessary for the process to run (e.g. caches).
   THROTTLED = 1,
   // Still resident in memory but core processing logic has been suspended.
+  // Clients should free up any memory that is used as an optimization, or
+  // any memory whose contents can be reproduced when transitioning out of
+  // the suspended state (e.g. parsed resource that can be reloaded from disk).
   SUSPENDED = 2,
 };
 
 // This is an interface for components which can respond to memory status
-// changes.
+// changes. An initial state is NORMAL. See MemoryCoordinatorClientRegistry for
+// threading guarantees and ownership management.
 class BASE_EXPORT MemoryCoordinatorClient {
  public:
   virtual ~MemoryCoordinatorClient() {}
 
-  // Called when memory state has changed.
+  // Called when memory state has changed. Any transition can occur except for
+  // UNKNOWN. General guidelines are:
+  //  * NORMAL:    Restore the default settings for memory allocation/usage if
+  //               it has changed.
+  //  * THROTTLED: Use smaller limits for memory allocations and caches.
+  //  * SUSPENDED: Purge memory.
   virtual void OnMemoryStateChange(MemoryState state) = 0;
 };