1 /* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
2 /* vim: set ts=8 sts=2 et sw=2 tw=80: */
3 /* This Source Code Form is subject to the terms of the Mozilla Public
4 * License, v. 2.0. If a copy of the MPL was not distributed with this
5 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
7 #ifndef dom_ipc_SharedStringMap_h
8 #define dom_ipc_SharedStringMap_h
10 #include "mozilla/AutoMemMap.h"
11 #include "mozilla/Result.h"
12 #include "mozilla/dom/ipc/StringTable.h"
13 #include "nsTHashMap.h"
15 namespace mozilla::dom::ipc
{
17 class SharedStringMapBuilder
;
20 * This class provides a simple, read-only key-value string store, with all
21 * data packed into a single segment of memory, which can be shared between
24 * Look-ups are performed by binary search of a static table in the mapped
25 * memory region, and all returned strings are literals which reference the
26 * mapped data. No copies are performed on instantiation or look-up.
28 * Important: The mapped memory created by this class is persistent. Once an
29 * instance has been initialized, the memory that it allocates can never be
30 * freed before process shutdown. Do not use it for short-lived mappings.
32 class SharedStringMap
{
33 using FileDescriptor
= mozilla::ipc::FileDescriptor
;
37 * The header at the beginning of the shared memory region describing its
38 * layout. The layout of the shared memory is as follows:
41 * A Header struct describing the contents of the rest of the memory region.
43 * - Optional alignment padding for Header[].
45 * - Entry[header.mEntryCount]:
46 * An array of Entry structs, one for each entry in the map. Entries are
47 * lexocographically sorted by key.
49 * - StringTable<nsCString>:
50 * A region of flat, null-terminated C strings. Entry key strings are
51 * encoded as character offsets into this region.
53 * - Optional alignment padding for char16_t[]
55 * - StringTable<nsString>:
56 * A region of flat, null-terminated UTF-16 strings. Entry value strings are
57 * encoded as character (*not* byte) offsets into this region.
61 // The number of entries in this map.
64 // The raw byte offset of the beginning of the key string table, from the
65 // start of the shared memory region, and its size in bytes.
66 size_t mKeyStringsOffset
;
67 size_t mKeyStringsSize
;
69 // The raw byte offset of the beginning of the value string table, from the
70 // start of the shared memory region, and its size in bytes (*not*
72 size_t mValueStringsOffset
;
73 size_t mValueStringsSize
;
77 * Describes a value in the string map, as offsets into the key and value
81 // The offset and size of the entry's UTF-8 key in the key string table.
82 StringTableEntry mKey
;
83 // The offset and size of the entry's UTF-16 value in the value string
85 StringTableEntry mValue
;
88 NS_INLINE_DECL_REFCOUNTING(SharedStringMap
)
90 // Note: These constructors are infallible on the premise that this class
91 // is used primarily in cases where it is critical to platform
93 explicit SharedStringMap(const FileDescriptor
&, size_t);
94 explicit SharedStringMap(SharedStringMapBuilder
&&);
97 * Searches for the given value in the map, and returns true if it exists.
99 bool Has(const nsCString
& aKey
);
102 * Searches for the given value in the map, and, if it exists, returns true
103 * and places its value in aValue.
105 * The returned value is a literal string which references the mapped memory
108 bool Get(const nsCString
& aKey
, nsAString
& aValue
);
112 * Searches for an entry for the given key. If found, returns true, and
113 * places its index in the entry array in aIndex.
115 bool Find(const nsCString
& aKey
, size_t* aIndex
);
119 * Returns the number of entries in the map.
121 uint32_t Count() const { return EntryCount(); }
124 * Returns the string entry at the given index. Keys are guaranteed to be
125 * sorted lexographically.
127 * The given index *must* be less than the value returned by Count().
129 * The returned value is a literal string which references the mapped memory
132 nsCString
GetKeyAt(uint32_t aIndex
) const {
133 MOZ_ASSERT(aIndex
< Count());
134 return KeyTable().Get(Entries()[aIndex
].mKey
);
138 * Returns the string value for the entry at the given index.
140 * The given index *must* be less than the value returned by Count().
142 * The returned value is a literal string which references the mapped memory
145 nsString
GetValueAt(uint32_t aIndex
) const {
146 MOZ_ASSERT(aIndex
< Count());
147 return ValueTable().Get(Entries()[aIndex
].mValue
);
151 * Returns a copy of the read-only file descriptor which backs the shared
152 * memory region for this map. The file descriptor may be passed between
153 * processes, and used to construct new instances of SharedStringMap with
154 * the same data as this instance.
156 FileDescriptor
CloneFileDescriptor() const;
158 size_t MapSize() const { return mMap
.size(); }
161 ~SharedStringMap() = default;
164 // Type-safe getters for values in the shared memory region:
165 const Header
& GetHeader() const { return mMap
.get
<Header
>()[0]; }
167 RangedPtr
<const Entry
> Entries() const {
168 return {reinterpret_cast<const Entry
*>(&GetHeader() + 1), EntryCount()};
171 uint32_t EntryCount() const { return GetHeader().mEntryCount
; }
173 StringTable
<nsCString
> KeyTable() const {
174 auto& header
= GetHeader();
175 return {{&mMap
.get
<uint8_t>()[header
.mKeyStringsOffset
],
176 header
.mKeyStringsSize
}};
179 StringTable
<nsString
> ValueTable() const {
180 auto& header
= GetHeader();
181 return {{&mMap
.get
<uint8_t>()[header
.mValueStringsOffset
],
182 header
.mValueStringsSize
}};
185 loader::AutoMemMap mMap
;
189 * A helper class which builds the contiguous look-up table used by
190 * SharedStringMap. Each key-value pair in the final map is added to the
191 * builder, before it is finalized and transformed into a snapshot.
193 class MOZ_RAII SharedStringMapBuilder
{
195 SharedStringMapBuilder() = default;
198 * Adds a key-value pair to the map.
200 void Add(const nsCString
& aKey
, const nsString
& aValue
);
203 * Finalizes the binary representation of the map, writes it to a shared
204 * memory region, and then initializes the given AutoMemMap with a reference
205 * to the read-only copy of it.
207 Result
<Ok
, nsresult
> Finalize(loader::AutoMemMap
& aMap
);
210 using Entry
= SharedStringMap::Entry
;
212 StringTableBuilder
<nsCStringHashKey
, nsCString
> mKeyTable
;
213 StringTableBuilder
<nsStringHashKey
, nsString
> mValueTable
;
215 nsTHashMap
<nsCStringHashKey
, Entry
> mEntries
;
218 } // namespace mozilla::dom::ipc
220 #endif // dom_ipc_SharedStringMap_h