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 12 // OVERVIEW: 13 // 14 // MemoryCoordinatorClient is an interface which a component can implement to 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. 27 28 // MemoryState is an indicator that processes can use to guide their memory 29 // allocation policies. For example, a process that receives the throttled 30 // state can use that as as signal to decrease memory cache limits. 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 { 34 // The state is unknown. 35 UNKNOWN = -1, 36 // No memory constraints. 37 NORMAL = 0, 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) 42 THROTTLED = 1, 43 // Still resident in memory but core processing logic has been suspended. 44 // In most cases, OnPurgeMemory() will be called before entering this state. 45 SUSPENDED = 2, 46 }; 47 48 const int kMemoryStateMax = static_cast<int>(MemoryState::SUSPENDED) + 1; 49 50 // Returns a string representation of MemoryState. 51 BASE_EXPORT const char* MemoryStateToString(MemoryState state); 52 53 // This is an interface for components which can respond to memory status 54 // changes. An initial state is NORMAL. See MemoryCoordinatorClientRegistry for 55 // threading guarantees and ownership management. 56 class BASE_EXPORT MemoryCoordinatorClient { 57 public: 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. 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. OnMemoryStateChange(MemoryState state)66 virtual void OnMemoryStateChange(MemoryState state) {} 67 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. OnPurgeMemory()71 virtual void OnPurgeMemory() {} 72 73 protected: 74 virtual ~MemoryCoordinatorClient() = default; 75 }; 76 77 } // namespace base 78 79 #endif // BASE_MEMORY_MEMORY_COORDINATOR_CLIENT_H_ 80