Add documentation for MemoryCoordinator-related primitives

base/memory/memory_pressure_listener.h

Index: base/memory/memory_pressure_listener.h
diff --git a/base/memory/memory_pressure_listener.h b/base/memory/memory_pressure_listener.h
index 7e97010085dc8dcaea7f0fb68993b968fc5484c5..476a07e9b3dc961e8b178cacd764a0930fad5b0b 100644
--- a/base/memory/memory_pressure_listener.h
+++ b/base/memory/memory_pressure_listener.h
@@ -43,6 +43,9 @@ namespace base {
 //    // Stop listening.
 //    delete my_listener;
 //
+// We're planning to replace MemoryPressureListener with MemoryCoordinator.
+// See a comment in MemoryCoordinator.
+// TODO(bashi): Deprecate MemoryPressureListener.

[Ryan Sleevi, 2017/02/08 15:02:04]

Note that the "we" here is ambiguous (is it team? Chromium? Google?) The thread
at
https://groups.google.com/a/chromium.org/forum/#!topic/chromium-dev/NH-S6KCkr2M
has more discussion about the challenges with that

Perhaps this could be rephrased more assertively, and give clearer guidance as
to what the recommended 'alternative' pattern is

// NOTE: The MemoryPressureListener is in the process of being replaced with the
MemoryCoordinator.
// For new code, prefer to implement the MemoryCoordinatorClient interface
specified in
// //base/memory/memory_coordinator_client.h
//
// The state MEMORY_PRESSURE_LEVEL_NONE corresponds to MemoryState::NORMAL and
the state
// MEMORY_PRESSURE_LEVEL_MODERATE corresponds to MemoryState::THROTTLED. The
state
// MEMORY_PRESSURE_LEVEL_CRITICAL is indicated via
MemoryCoordinatorClient::OnPurgeMemory()

1) I'm not sure if that's a correct mapping; if it isn't, it might be an
opportunity to improve the documentation
2) When I search the codebase for "MemoryCoordinator", I found multiple results
- but the MemoryCoordinatorClient was not the first of them

It might be better to put some of this broader roadmap in //docs (or in a
//base/memory/docs folder) and reference that here, since you can then more
freely expand upon the relationship between the classes, their equivalences, and
their known gaps.

[haraken, 2017/02/09 02:37:31]

- Removed 'we'.

- Regarding the mapping, we'll map LEVEL_NONE to MemoryState::NORMAL and
LEVEL_MODERATE and LEVEL_CRITICAL to MemoryState::THROTTLE. However, this is
still under experiments.

 class BASE_EXPORT MemoryPressureListener {
  public:
   // A Java counterpart will be generated for this enum.