bashi | b87488b | 2016-09-15 11:44:32 +0900 | [diff] [blame] | 1 | // Copyright 2016 The Chromium Authors. All rights reserved. |
| 2 | // Use of this source code is governed by a BSD-style license that can be |
| 3 | // found in the LICENSE file. |
| 4 | |
| 5 | #ifndef BASE_MEMORY_MEMORY_COORDINATOR_CLIENT_H_ |
| 6 | #define BASE_MEMORY_MEMORY_COORDINATOR_CLIENT_H_ |
| 7 | |
| 8 | #include "base/base_export.h" |
| 9 | |
| 10 | namespace base { |
| 11 | |
bashi | 783e617 | 2016-09-27 13:15:23 +0900 | [diff] [blame] | 12 | // OVERVIEW: |
| 13 | // |
| 14 | // MemoryCoordinatorClient is an interface which a component can implement to |
bashi | f651332 | 2017-01-30 10:05:29 +0900 | [diff] [blame] | 15 | // adjust "future allocation" and "existing allocation". For "future allocation" |
| 16 | // it provides a callback to observe memory state changes, and for "existing |
| 17 | // allocation" it provides a callback to purge memory. |
| 18 | // |
| 19 | // Unlike MemoryPressureListener, memory state changes are stateful. State |
| 20 | // transitions are throttled to avoid thrashing; the exact throttling period is |
| 21 | // platform dependent, but will be at least 5-10 seconds. When a state change |
| 22 | // notification is dispatched, clients are expected to update their allocation |
| 23 | // policies (e.g. setting cache limit) that persist for the duration of the |
| 24 | // memory state. Note that clients aren't expected to free up memory on memory |
| 25 | // state changes. Clients should wait for a separate purge request to free up |
| 26 | // memory. Purging requests will be throttled as well. |
bashi | 783e617 | 2016-09-27 13:15:23 +0900 | [diff] [blame] | 27 | |
bashi | b87488b | 2016-09-15 11:44:32 +0900 | [diff] [blame] | 28 | // MemoryState is an indicator that processes can use to guide their memory |
bashi | f651332 | 2017-01-30 10:05:29 +0900 | [diff] [blame] | 29 | // allocation policies. For example, a process that receives the throttled |
| 30 | // state can use that as as signal to decrease memory cache limits. |
bashi | 6033d18 | 2016-11-08 13:13:55 +0900 | [diff] [blame] | 31 | // NOTE: This enum is used to back an UMA histogram, and therefore should be |
| 32 | // treated as append-only. |
| 33 | enum class MemoryState : int { |
bashi | b87488b | 2016-09-15 11:44:32 +0900 | [diff] [blame] | 34 | // The state is unknown. |
| 35 | UNKNOWN = -1, |
| 36 | // No memory constraints. |
| 37 | NORMAL = 0, |
bashi | f651332 | 2017-01-30 10:05:29 +0900 | [diff] [blame] | 38 | // Running and interactive but memory allocation should be throttled. |
| 39 | // Clients should set lower budget for any memory that is used as an |
| 40 | // optimization but that is not necessary for the process to run. |
| 41 | // (e.g. caches) |
bashi | b87488b | 2016-09-15 11:44:32 +0900 | [diff] [blame] | 42 | THROTTLED = 1, |
| 43 | // Still resident in memory but core processing logic has been suspended. |
bashi | f651332 | 2017-01-30 10:05:29 +0900 | [diff] [blame] | 44 | // In most cases, OnPurgeMemory() will be called before entering this state. |
bashi | b87488b | 2016-09-15 11:44:32 +0900 | [diff] [blame] | 45 | SUSPENDED = 2, |
| 46 | }; |
| 47 | |
bashi | 6033d18 | 2016-11-08 13:13:55 +0900 | [diff] [blame] | 48 | const int kMemoryStateMax = static_cast<int>(MemoryState::SUSPENDED) + 1; |
| 49 | |
bashi | ae2ec39 | 2016-11-01 15:36:19 +0900 | [diff] [blame] | 50 | // Returns a string representation of MemoryState. |
| 51 | BASE_EXPORT const char* MemoryStateToString(MemoryState state); |
| 52 | |
bashi | b87488b | 2016-09-15 11:44:32 +0900 | [diff] [blame] | 53 | // This is an interface for components which can respond to memory status |
bashi | 783e617 | 2016-09-27 13:15:23 +0900 | [diff] [blame] | 54 | // changes. An initial state is NORMAL. See MemoryCoordinatorClientRegistry for |
| 55 | // threading guarantees and ownership management. |
bashi | b87488b | 2016-09-15 11:44:32 +0900 | [diff] [blame] | 56 | class BASE_EXPORT MemoryCoordinatorClient { |
| 57 | public: |
bashi | 783e617 | 2016-09-27 13:15:23 +0900 | [diff] [blame] | 58 | // Called when memory state has changed. Any transition can occur except for |
| 59 | // UNKNOWN. General guidelines are: |
| 60 | // * NORMAL: Restore the default settings for memory allocation/usage if |
| 61 | // it has changed. |
bashi | f651332 | 2017-01-30 10:05:29 +0900 | [diff] [blame] | 62 | // * THROTTLED: Use smaller limits for future memory allocations. You don't |
| 63 | // need to take any action on existing allocations. |
| 64 | // * SUSPENDED: Use much smaller limits for future memory allocations. You |
| 65 | // don't need to take any action on existing allocations. |
| 66 | virtual void OnMemoryStateChange(MemoryState state) {} |
bashi | ce75df1 | 2016-09-29 12:40:21 +0900 | [diff] [blame] | 67 | |
bashi | f651332 | 2017-01-30 10:05:29 +0900 | [diff] [blame] | 68 | // Called to purge memory. |
| 69 | // This callback should free up any memory that is used as an optimization, or |
| 70 | // any memory whose contents can be reproduced. |
| 71 | virtual void OnPurgeMemory() {} |
| 72 | |
| 73 | protected: |
Chris Watkins | 653cd66 | 2017-12-13 13:25:58 +0900 | [diff] [blame] | 74 | virtual ~MemoryCoordinatorClient() = default; |
bashi | b87488b | 2016-09-15 11:44:32 +0900 | [diff] [blame] | 75 | }; |
| 76 | |
| 77 | } // namespace base |
| 78 | |
| 79 | #endif // BASE_MEMORY_MEMORY_COORDINATOR_CLIENT_H_ |