Add documentation for MemoryCoordinator-related primitives

base/memory/memory_coordinator.md

Index: base/memory/memory_coordinator.md
diff --git a/base/memory/memory_coordinator.md b/base/memory/memory_coordinator.md
new file mode 100644
index 0000000000000000000000000000000000000000..bb9d2af639d83c6f89eb3b6c72ae3744a493b35c
--- /dev/null
+++ b/base/memory/memory_coordinator.md
@@ -0,0 +1,33 @@
+# Overview
+
+To be a good memory citizen, each memory-intensive component needs to
+have the following two notions:

[Ryan Sleevi, 2017/02/25 02:57:10]

Suggestion: "memory-intensive" leaves it subjective to the reader as to what is
or is not in scope of this.

To ensure Chromium projects make the best use of available system memory,
developers should strive to ensure their code and components address the
following two scenarios:

1. How to deal with past allocations when the system is under memory pressure.
  Components are expected to reduce as much previously allocated
  memory as possible by listening for and processing notifications
  that signal such pressure.

  For example, a component that has an internal cache may choose
  to clear the cache as a way to reduce memory.

  This is a _reactive_ way to reduce the memory footprint.

2. How to deal with future allocations when the system is under memory pressure.
  Components are expected to reduce or throttle future memory
  allocations for as long as the memory pressure exists, which for
  memory constrained devices and applications, may be indefinitely.

  For example, a component that has an internal cache may limit the
  cache size (or disable caching, if appropriate) for the duration
  of the memory pressure event.

  This is the _proactive_ way to reduce the memory footprint.


The changes I made are trying to avoid subjective/interpretative statements,
which will hopefully provide clearer guidance. This is eliminating
"memory-intensive" or "high". I also tried to offer symmetry for the examples,
and Markdown-cleaned them up a little to use hanging indents :)

+
+(a) How to deal with past allocations when the system is under high memroy pressure.
+Specifically, the component is expected to purge as much memory as possible.
+This is a 'reactive' way to reduce memory footprint.
+
+(b) How to deal with future allocations when the system is under high memroy pressure.
+Specifically, the component is expected to throttle future memory allocations by,
+for example, lowering the cache size. This is a 'proactive' way to reduce memory footprint.
+
+# Current status

[Ryan Sleevi, 2017/02/25 02:57:10]

# Current Status

## Reactive Reduction
To properly address reactive reduction in memory, classes should make use of the
following classes:

* [base::MemoryPressureListener](memory_pressure_listener.h) allows a component
to subscribe a Callback to be notified as the available system memory changes.
Components are expected to respond to the
`MEMORY_PRESSURE_LEVEL_MODERATE` and `MEMORY_PRESSURE_LEVEL_CRITICAL`
notifications and take steps to free memory, as described in the class
documentation.
* [base::MemoryCoordinatorClient](memory_coordinator_client.h) allows components
to implement an interface that receives notifications when the available system
memory changes. Components are expected to implement this interface by ensuring
that the `OnPurgeMemory()` method takes steps to free memory, as described in
the class documentation.

Note: `base::MemoryPressureListener` is in the process of being deprecated,
while the `base::MemoryCoordinatorClient` is still being developed behind a
flag. Until `base::MemoryCoordinatorClient` becomes the default, components
should implement both methods of receiving reactive notifications.

## Proactive Reduction
To properly address proactive reduction in memory, classes should make use of
the following classes:

* [base::SysInfo::IsLowEndDevice()](../sys_info.h) indicates whether the device
is operating in a constrained memory environment.

  For non-Android devices, this is 512MB of RAM or less. For Android
  devices, this is a compile-time flag dependent on the device being
  targeted.

  Components should make use of this information to significantly
  reduce or eliminate allocations that are not core to the 
  functionality of the component, and should strive to free available
  memory as quickly as reasonable.

  For example, a cache size might be 128 items under normal
  conditions, but may be only 16 items (or disabled) for devices
  that are memory constrained.

* [base::MemoryCoordinatorClient](memory_coordinator_client.h) provides the
`OnMemoryStateChange()` notification that provides dynamic notification about
memory pressure.

  Components that make use of this notification should make use of
  the `THROTTLED` and `SUSPENDED` notifications to adjust future
  memory allocations and growth.

Note: `MemoryCoordinatorClient` and `IsLowEndDevice` are complementary, and as
such, components should implement both strategies of managing memory
allocations.



My highlights of the change here:
- Follow the format of the introduction
- Make use of Markdown to the most we can
- isLowEndDevice does *NOT* appear to be a compile time flag, on Android and
!Android, judging by both sys_info.cc and sys_info_android.cc
- Remove the discussion about 'MemoryCoordinator', since as it relates to
developing, it appears to be MemoryCoordinator*Client*

+
+Currently we have three ways to control memory components:
+MemoryCoordinator, MemoryPressureListener and isLowEndDevice.
+
+* The MemoryPressureListener provides a way for memory components to listen
+memory-pressure notifications and purge memory when the system is under
+high memory pressure. The MemoryPressureListener is an interface that provides APIs
+to deal with (a).
+
+* The isLowEndDevice provides a way for memory components to enter a low-memory
+mode on low-memory devices. In the low-memory mode, the memory components
+are exepcted to trade off performance for memory. The isLowEndDevice is a compile-time
+configuration to deal with (b).
+
+* MemoryCoordinator is going to provide APIs for (a) and (b). In the future,
+the MemoryPressureListener and the isLowEndDevice will be unified into the MemoryCoordinator.
+The MemoryCoordinator is still behind a runtime flag. Until it is fully shipped,
+each memory component needs to support all of the MemoryPressureListener,
+the isLowEndDevice and the MemoryCoordinator.