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_SHARED_MEMORY_ALLOCATOR_H_ | |
6 #define BASE_MEMORY_SHARED_MEMORY_ALLOCATOR_H_ | |
7 | |
8 #include <stdint.h> | |
9 | |
10 #include "base/atomicops.h" | |
11 #include "base/base_export.h" | |
12 #include "base/macros.h" | |
13 | |
14 namespace base { | |
15 | |
16 // Simple allocator for pieces of a memory block that may be shared across | |
17 // multiple processes. | |
18 // | |
19 // This class provides for thread-secure (i.e. safe against other threads | |
20 // or processes that may be compromised and thus have malicious intent) | |
21 // allocation of memory within a designated block and also a mechanism by | |
22 // which other threads can learn of the allocations with any additional | |
23 // shared information. | |
24 // | |
25 // There is (currently) no way to release an allocated block of data because | |
26 // doing so would risk invalidating pointers held by other processes and | |
27 // greatly complicate the allocation algorithm. | |
28 // | |
29 // Construction of this object can accept new, clean (i.e. zeroed) memory | |
30 // or previously initialized memory. In the first case, construction must | |
31 // be allowed to complete before letting other allocators attach to the same | |
32 // segment. In other words, don't share the segment until at least one | |
33 // allocator has been attached to it. | |
34 // | |
35 // It should be noted that memory doesn't need to actually have zeros written | |
36 // throughout; it just needs to read as zero until something diffferent is | |
37 // written to a location. This is an important distinction as it supports the | |
38 // use-case of non-pinned memory, such as from a demand-allocated region by | |
39 // the OS or a memory-mapped file that auto-grows from a starting size of zero. | |
40 class BASE_EXPORT SharedMemoryAllocator { | |
41 public: | |
42 struct Iterator { | |
43 int32_t last; | |
44 uint32_t niter; | |
45 }; | |
46 | |
47 struct MemoryInfo { | |
48 int32_t total; | |
49 int32_t free; | |
50 }; | |
chrisha
2015/11/03 18:20:51
Each of these structs is worth of a one line comme
bcwhite
2015/11/03 22:32:17
Done.
| |
51 | |
52 // The allocator operates on any arbitrary block of memory. Creation and | |
53 // sharing of that block with another process is the responsibility of the | |
54 // caller. The allocator needs to know only the block's |base| address, the | |
55 // total |size| of the block, and any internal |page| size (zero if not | |
56 // paged) across which allocations should not span. | |
57 // | |
58 // SharedMemoryAllocator does NOT take ownership of this memory block. The | |
59 // caller must manage it and ensure it stays available throughout the lifetime | |
60 // of this object. | |
61 SharedMemoryAllocator(void* base, int32_t size, int32_t page_size); | |
chrisha
2015/11/03 18:20:51
The comments for this still aren't clear.
The des
bcwhite
2015/11/03 22:32:17
Comment updated and extended.
Regarding multiple
| |
62 ~SharedMemoryAllocator(); | |
63 | |
64 // Get an object referenced by an |offset|. For safety reasons, the |type| | |
65 // code and size-of(|T|) are compared to ensure the reference is valid | |
66 // and cannot return an object outside of the memory segment. A |type| of | |
67 // zero will match any though the size is still checked. NULL is returned | |
68 // if any problem is detected, such as corrupted storage or incorrect | |
69 // parameters. Callers MUST check that the returned value is not-null EVERY | |
70 // TIME before accessing it or risk crashing! Once dereferenced, the pointer | |
71 // is safe to reuse forever. | |
72 // | |
73 // NOTE: Though this method will guarantee that an object of the specified | |
74 // type can be accessed without going outside the bounds of the memory | |
75 // segment, it makes not guarantees of the validity of the data within the | |
76 // object itself. If it is expected that the contents of the segment could | |
77 // be compromised with malicious intent, the object must be hardened as well. | |
78 template <typename T> | |
79 T* GetType(int32_t offset, int32_t type) { | |
chrisha
2015/11/03 18:20:51
This is poorly named, as it's not actually getting
bcwhite
2015/11/03 22:32:17
It was originally "GetObject" but it turns out tha
| |
80 return static_cast<T*>(GetBlockData(offset, type, sizeof(T), false)); | |
81 } | |
82 | |
83 // Reserve space in the memory segment of the desired |size| and |type|. | |
84 // A return value of zero indicates the allocation failed, otherwise the | |
85 // returned offset can be used by any process to get a real pointer via | |
86 // the GetType() call. | |
chrisha
2015/11/03 18:20:51
Comment that the user is expected to Commit/MakeIt
bcwhite
2015/11/03 22:32:17
Done.
| |
87 int32_t Allocate(int32_t size, int32_t type); | |
88 | |
89 // Get the information about the amount of free space in the allocator. The | |
90 // amount of free space should be treated as approximate due to extras from | |
91 // alignment and metadata, but will never return less than could actually | |
92 // be allocated. | |
chrisha
2015/11/03 18:20:51
Also note that this is inherently 'racy' in the se
bcwhite
2015/11/03 22:32:17
Done.
| |
93 void GetMemoryInfo(MemoryInfo* meminfo); | |
94 | |
95 // Allocated objects can be added to an internal list that can then be | |
96 // iterated over by other processes. | |
97 void MakeIterable(int32_t offset); | |
chrisha
2015/11/03 18:20:51
Do we want to use the seemingly standard 'Allocate
bcwhite
2015/11/03 22:32:17
I moved it. It's not necessary to commit all allo
| |
98 | |
99 // Iterating uses a |state| structure (initialized by CreateIterator) and | |
100 // returns both the offset reference to the object as well as the |type| of | |
101 // that object. A zero return value indicates there are currently no more | |
102 // objects to be found but future attempts can be made without having to | |
103 // reset the iterator to "first". | |
104 void CreateIterator(Iterator* state); | |
105 int32_t GetNextIterable(Iterator* state, int32_t* type); | |
chrisha
2015/11/03 18:20:51
Is it worth making this have STL iterator semantic
bcwhite
2015/11/03 22:32:17
I'm not sure. STL iterators have a designated "en
| |
106 | |
107 // If there is some indication that the shared memory has become corrupted, | |
108 // calling this will attempt to prevent further damage by indicating to | |
109 // all processes that something is not as expected. | |
110 void SetCorrupted(); | |
111 bool IsCorrupted(); | |
chrisha
2015/11/03 18:20:51
Does SetCorrupted need to be exposed for anyone to
bcwhite
2015/11/03 22:32:17
I was thinking that the caller might want to repor
| |
112 | |
113 // Flag set if an allocation has failed because memory was full. | |
114 bool IsFull(); | |
115 | |
116 private: | |
117 struct SharedMetadata; | |
118 struct BlockHeader; | |
119 | |
120 BlockHeader* GetBlock(int32_t offset, int32_t type, int32_t size, | |
121 bool special); | |
122 void* GetBlockData(int32_t offset, int32_t type, int32_t size, bool special); | |
123 | |
124 SharedMetadata* shared_meta_; | |
125 char* mem_base_; // char because sizeof guaranteed 1 -- easy offset calc | |
126 int32_t mem_size_; | |
127 int32_t mem_page_; | |
chrisha
2015/11/03 18:20:51
Should these be stored in this object, or in the h
bcwhite
2015/11/03 22:32:17
They need to be stored in both places. We want to
| |
128 int32_t last_seen_; | |
chrisha
2015/11/03 18:20:51
Comment for what this is? While you're at it, comm
bcwhite
2015/11/03 22:32:17
Done.
| |
129 subtle::Atomic32 corrupted_; // TODO(bcwhite): Use std::atomic<char> when ok. | |
130 | |
131 DISALLOW_COPY_AND_ASSIGN(SharedMemoryAllocator); | |
132 }; | |
133 | |
134 } // namespace base | |
135 | |
136 #endif // BASE_MEMORY_SHARED_MEMORY_ALLOCATOR_H_ | |
OLD | NEW |