memory coordinator: Add MemoryCoordinatorClient::OnPurgeMemory()

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 148f4c175345cd78af72506283ff76f04478231d..1506040d1169185c033f8071081941c40340d749 100644
--- a/base/memory/memory_coordinator_client.h
+++ b/base/memory/memory_coordinator_client.h
@@ -12,16 +12,20 @@ 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.
+// adjust "future allocation" and "existing allocation". For "future allocation"
+// it provides a callback to observe memory state changes, and for "existing
+// allocation" it provides a callback to purge memory.
+//
+// Unlike MemoryPressureListener, memory state changes are stateful. 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 update their allocation policies (e.g. setting cache limit) that persist
+// for the duration of the memory state. Purging requests will be throttled as
+// well.
 
 // 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.
+// allocation policies. For example, a process that receives the throttled
+// state can use that as as signal to decrease memory cache limits.
 // NOTE: This enum is used to back an UMA histogram, and therefore should be
 // treated as append-only.
 enum class MemoryState : int {
@@ -29,14 +33,13 @@ enum class MemoryState : int {
   UNKNOWN = -1,
   // 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).
+  // Running and interactive but memory allocation should be throttled.
+  // Clients should set lower budget for any memory that is used as an
+  // optimization but that is not necessary for the process to run (e.g.

[hajimehoshi, 2017/01/24 11:46:31]

'caches' should be in this line.

[bashi, 2017/01/26 01:05:49]

Do you mean s/an optimization/optimization caches/ ?

+  // 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).
+  // In most cases, OnPurgeMemory() is called before entering this state.
   SUSPENDED = 2,
 };
 
@@ -55,10 +58,16 @@ class BASE_EXPORT MemoryCoordinatorClient {
   //  * 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;
+  //  * SUSPENDED: Release resources if they don't need when suspended.
+  virtual void OnMemoryStateChange(MemoryState state) {}
+
+  // Called to reclaim memory.
+  // This callback should free up any memory that is used as an optimization, or
+  // any memory whose contents can be reproduced when transitioning out of

[hajimehoshi, 2017/01/24 11:46:31]

'the' should be in this line

[bashi, 2017/01/26 01:05:49]

Could you elaborate a bit more? Where should I add 'the'?

+  // the suspended state (e.g. parsed resource that can be reloaded from disk).
+  virtual void OnPurgeMemory() {}
 
-protected:
+ protected:
   virtual ~MemoryCoordinatorClient() {}
 };