OLD | NEW |
(Empty) | |
| 1 // Copyright (c) 2015 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_PERSISTENT_MEMORY_ALLOCATOR_H_ |
| 6 #define BASE_MEMORY_PERSISTENT_MEMORY_ALLOCATOR_H_ |
| 7 |
| 8 #include <stdint.h> |
| 9 #include <string> |
| 10 |
| 11 #include "base/atomicops.h" |
| 12 #include "base/base_export.h" |
| 13 #include "base/gtest_prod_util.h" |
| 14 #include "base/macros.h" |
| 15 |
| 16 namespace base { |
| 17 |
| 18 class HistogramBase; |
| 19 |
| 20 // Simple allocator for pieces of a memory block that may be persistent |
| 21 // to some storage or shared across multiple processes. |
| 22 // |
| 23 // This class provides for thread-secure (i.e. safe against other threads |
| 24 // or processes that may be compromised and thus have malicious intent) |
| 25 // allocation of memory within a designated block and also a mechanism by |
| 26 // which other threads can learn of these allocations. |
| 27 // |
| 28 // There is (currently) no way to release an allocated block of data because |
| 29 // doing so would risk invalidating pointers held by other processes and |
| 30 // greatly complicate the allocation algorithm. |
| 31 // |
| 32 // Construction of this object can accept new, clean (i.e. zeroed) memory |
| 33 // or previously initialized memory. In the first case, construction must |
| 34 // be allowed to complete before letting other allocators attach to the same |
| 35 // segment. In other words, don't share the segment until at least one |
| 36 // allocator has been attached to it. |
| 37 // |
| 38 // It should be noted that memory doesn't need to actually have zeros written |
| 39 // throughout; it just needs to read as zero until something diffferent is |
| 40 // written to a location. This is an important distinction as it supports the |
| 41 // use-case of non-pinned memory, such as from a demand-allocated region by |
| 42 // the OS or a memory-mapped file that auto-grows from a starting size of zero. |
| 43 class BASE_EXPORT PersistentMemoryAllocator { |
| 44 public: |
| 45 typedef int32_t Reference; |
| 46 |
| 47 // Internal state information when iterating over memory allocations. |
| 48 struct Iterator { |
| 49 Reference last; |
| 50 uint32_t niter; |
| 51 }; |
| 52 |
| 53 // Returned information about the internal state of the heap. |
| 54 struct MemoryInfo { |
| 55 size_t total; |
| 56 size_t free; |
| 57 }; |
| 58 |
| 59 enum : uint32_t { |
| 60 kTypeIdAny = 0 // Match any type-id inside GetAsObject(). |
| 61 }; |
| 62 |
| 63 // The allocator operates on any arbitrary block of memory. Creation and |
| 64 // persisting or sharing of that block with another process is the |
| 65 // responsibility of the caller. The allocator needs to know only the |
| 66 // block's |base| address, the total |size| of the block, and any internal |
| 67 // |page| size (zero if not paged) across which allocations should not span. |
| 68 // The |name|, if provided, is used to distinguish histograms for this |
| 69 // allocator. Only the primary owner of the segment should define this value; |
| 70 // other processes can learn it from the shared state. |
| 71 // |
| 72 // PersistentMemoryAllocator does NOT take ownership of the memory block. |
| 73 // The caller must manage it and ensure it stays available throughout the |
| 74 // lifetime of this object. |
| 75 // |
| 76 // Memory segments for sharing must have had an allocator attached to them |
| 77 // before actually being shared. If the memory segment was just created, it |
| 78 // should be zeroed before being passed here. If it was an existing segment, |
| 79 // the values here will be compared to copies stored in the shared segment |
| 80 // as a guard against corruption. |
| 81 PersistentMemoryAllocator(void* base, size_t size, size_t page_size, |
| 82 const std::string& name); |
| 83 ~PersistentMemoryAllocator(); |
| 84 |
| 85 // Get an object referenced by a |ref|. For safety reasons, the |type_id| |
| 86 // code and size-of(|T|) are compared to ensure the reference is valid |
| 87 // and cannot return an object outside of the memory segment. A |type_id| of |
| 88 // zero will match any though the size is still checked. NULL is returned |
| 89 // if any problem is detected, such as corrupted storage or incorrect |
| 90 // parameters. Callers MUST check that the returned value is not-null EVERY |
| 91 // TIME before accessing it or risk crashing! Once dereferenced, the pointer |
| 92 // is safe to reuse forever. |
| 93 // |
| 94 // NOTE: Though this method will guarantee that an object of the specified |
| 95 // type can be accessed without going outside the bounds of the memory |
| 96 // segment, it makes no guarantees of the validity of the data within the |
| 97 // object itself. If it is expected that the contents of the segment could |
| 98 // be compromised with malicious intent, the object must be hardened as well. |
| 99 template <typename T> |
| 100 T* GetAsObject(Reference ref, uint32_t type_id) { |
| 101 return static_cast<T*>(GetBlockData(ref, type_id, sizeof(T))); |
| 102 } |
| 103 |
| 104 // Get the number of bytes allocated to a block. This is useful when storing |
| 105 // arrays in order to validate the ending boundary. The returned value will |
| 106 // include any padding added to achieve the required alignment and so could |
| 107 // be larger than given in the original Allocate() request. |
| 108 size_t GetAllocSize(Reference ref); |
| 109 |
| 110 // Reserve space in the memory segment of the desired |size| and |type_id|. |
| 111 // A return value of zero indicates the allocation failed, otherwise the |
| 112 // returned reference can be used by any process to get a real pointer via |
| 113 // the GetAsObject() call. |
| 114 int32_t Allocate(size_t size, uint32_t type_id); |
| 115 |
| 116 // Allocated objects can be added to an internal list that can then be |
| 117 // iterated over by other processes. If an allocated object can be found |
| 118 // another way, such as by having its reference within a different object |
| 119 // that will be made iterable, then this call is not necessary. This always |
| 120 // succeeds unless corruption is detected; check IsCorrupted() to find out. |
| 121 void MakeIterable(Reference ref); |
| 122 |
| 123 // Get the information about the amount of free space in the allocator. The |
| 124 // amount of free space should be treated as approximate due to extras from |
| 125 // alignment and metadata. Concurrent allocations from other threads will |
| 126 // also make the true amount less than what is reported. |
| 127 void GetMemoryInfo(MemoryInfo* meminfo); |
| 128 |
| 129 // Iterating uses a |state| structure (initialized by CreateIterator) and |
| 130 // returns both the reference to the object as well as the |type_id| of |
| 131 // that object. A zero return value indicates there are currently no more |
| 132 // objects to be found but future attempts can be made without having to |
| 133 // reset the iterator to "first". |
| 134 void CreateIterator(Iterator* state); |
| 135 int32_t GetNextIterable(Iterator* state, uint32_t* type_id); |
| 136 |
| 137 // If there is some indication that the memory has become corrupted, |
| 138 // calling this will attempt to prevent further damage by indicating to |
| 139 // all processes that something is not as expected. |
| 140 void SetCorrupt(); |
| 141 |
| 142 // This can be called to determine if corruption has been detected in the |
| 143 // segment, possibly my a malicious actor. Once detected, future allocations |
| 144 // will fail and iteration may not locate all objects. |
| 145 bool IsCorrupt(); |
| 146 |
| 147 // Flag set if an allocation has failed because the memory segment was full. |
| 148 bool IsFull(); |
| 149 |
| 150 // Update static-state histograms. This should be called on a periodic basis |
| 151 // to record such things as how much of the total space is used. |
| 152 void UpdateStaticHistograms(); |
| 153 |
| 154 private: |
| 155 struct SharedMetadata; |
| 156 struct BlockHeader; |
| 157 static const Reference kReferenceQueue; |
| 158 static const Reference kReferenceNull; |
| 159 |
| 160 // The shared metadata is always located at the top of the memory segment. |
| 161 // This convenience function eliminates constant casting of the base pointer |
| 162 // within the code. |
| 163 SharedMetadata* shared_meta() { |
| 164 return reinterpret_cast<SharedMetadata*>(mem_base_); |
| 165 } |
| 166 |
| 167 BlockHeader* GetBlock(Reference ref, uint32_t type_id, int32_t size, |
| 168 bool queue_ok, bool free_ok); |
| 169 void* GetBlockData(Reference ref, uint32_t type_id, int32_t size); |
| 170 |
| 171 char* mem_base_; // Same. (char because sizeof guaranteed 1) |
| 172 int32_t mem_size_; // Size of entire memory segment. |
| 173 int32_t mem_page_; // Page size allocations shouldn't cross. |
| 174 subtle::Atomic32 corrupted_; // Local version of "corrupted" flag. |
| 175 |
| 176 HistogramBase* allocs_histogram_; // Histogram recording allocs. |
| 177 HistogramBase* used_histogram_; // Histogram recording used space. |
| 178 |
| 179 FRIEND_TEST_ALL_PREFIXES(PersistentMemoryAllocatorTest, AllocateAndIterate); |
| 180 DISALLOW_COPY_AND_ASSIGN(PersistentMemoryAllocator); |
| 181 }; |
| 182 |
| 183 } // namespace base |
| 184 |
| 185 #endif // BASE_MEMORY_PERSISTENT_MEMORY_ALLOCATOR_H_ |
OLD | NEW |