Document memory coordinator

base/memory/memory_coordinator_client.h

 // Copyright 2016 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 #ifndef BASE_MEMORY_MEMORY_COORDINATOR_CLIENT_H_
 #define BASE_MEMORY_MEMORY_COORDINATOR_CLIENT_H_
 
 #include "base/base_export.h"
 
 namespace base {
 
+// OVERVIEW:
+//
+// MemoryCoordinatorClient is an interface which a component can implement to
+// respond memory state changes. Unlike MemoryPressureListener, this is a

[dcheng, 2016/09/26 04:55:07]

Nit: to respond => to respond to

[bashi, 2016/09/26 05:57:22]

Done.

+// stateful mechanism and clients receive notifications only when memory states
+// are changed. In order to avoid thrashing, state transitions won't occur in a

[dcheng, 2016/09/26 04:55:07]

Nit: State transitions are throttled to avoid thrashing; the exact throttling
period is platform dependent, but will be at least N seconds (where N is an
actual number... maybe there's a concrete lower bound we can give here like 10
or 15 second?)

[bashi, 2016/09/26 05:57:22]

Done. I choose "5-10 seconds" as the design doc which chrisha@ wrote.

https://docs.google.com/document/d/1GMSkij4qpbkK6T7MtCX9FcPlv39Q9J2lmW8qY8Wmf...

+// short period of time. The minimum time period of transtion depends on
+// platforms/OSes but at least in seconds.
+
 // 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.
 enum class MemoryState {
   // The state is unknown.
   UNKNOWN = -1,
   // No memory constraints.
   NORMAL = 0,
   // Running and interactive but allocation should be throttled.
   THROTTLED = 1,
   // Still resident in memory but core processing logic has been suspended.
   SUSPENDED = 2,
 };
 
 // This is an interface for components which can respond to memory status
-// changes.
+// changes. 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 could occur except for

[dcheng, 2016/09/26 04:55:07]

Is UNKNOWN an initial state?

[bashi, 2016/09/26 05:57:22]

At this point, NORMAL is an initial state. But there is a todo comment in
memory_coordinator.cc to have a setup state. Mentioned initial state.

+  // 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;
 };
 
 }  // namespace base
 
 #endif  // BASE_MEMORY_MEMORY_COORDINATOR_CLIENT_H_