dom/ipc/SharedStringMap.h

   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/. */
   6
   7 #ifndef dom_ipc_SharedStringMap_h
   8 #define dom_ipc_SharedStringMap_h
   9
  10 #include "mozilla/AutoMemMap.h"
  11 #include "mozilla/Result.h"
  12 #include "mozilla/dom/ipc/StringTable.h"
  13 #include "nsTHashMap.h"
  14
  15 namespace mozilla::dom::ipc {
  16
  17 class SharedStringMapBuilder;
  18
  19 /**
  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
  22  * processes.
  23  *
  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.
  27  *
  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.
  31  */
  32 class SharedStringMap {
  33   using FileDescriptor = mozilla::ipc::FileDescriptor;
  34
  35  public:
  36   /**
  37    * The header at the beginning of the shared memory region describing its
  38    * layout. The layout of the shared memory is as follows:
  39    *
  40    * - Header:
  41    *   A Header struct describing the contents of the rest of the memory region.
  42    *
  43    * - Optional alignment padding for Header[].
  44    *
  45    * - Entry[header.mEntryCount]:
  46    *   An array of Entry structs, one for each entry in the map. Entries are
  47    *   lexocographically sorted by key.
  48    *
  49    * - StringTable<nsCString>:
  50    *   A region of flat, null-terminated C strings. Entry key strings are
  51    *   encoded as character offsets into this region.
  52    *
  53    * - Optional alignment padding for char16_t[]
  54    *
  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.
  58    */
  59   struct Header {
  60     uint32_t mMagic;
  61     // The number of entries in this map.
  62     uint32_t mEntryCount;
  63
  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;
  68
  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*
  71     // characters).
  72     size_t mValueStringsOffset;
  73     size_t mValueStringsSize;
  74   };
  75
  76   /**
  77    * Describes a value in the string map, as offsets into the key and value
  78    * string tables.
  79    */
  80   struct Entry {
  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
  84     // table.
  85     StringTableEntry mValue;
  86   };
  87
  88   NS_INLINE_DECL_REFCOUNTING(SharedStringMap)
  89
  90   // Note: These constructors are infallible on the premise that this class
  91   // is used primarily in cases where it is critical to platform
  92   // functionality.
  93   explicit SharedStringMap(const FileDescriptor&, size_t);
  94   explicit SharedStringMap(SharedStringMapBuilder&&);
  95
  96   /**
  97    * Searches for the given value in the map, and returns true if it exists.
  98    */
  99   bool Has(const nsCString& aKey);
 100
 101   /**
 102    * Searches for the given value in the map, and, if it exists, returns true
 103    * and places its value in aValue.
 104    *
 105    * The returned value is a literal string which references the mapped memory
 106    * region.
 107    */
 108   bool Get(const nsCString& aKey, nsAString& aValue);
 109
 110  private:
 111   /**
 112    * Searches for an entry for the given key. If found, returns true, and
 113    * places its index in the entry array in aIndex.
 114    */
 115   bool Find(const nsCString& aKey, size_t* aIndex);
 116
 117  public:
 118   /**
 119    * Returns the number of entries in the map.
 120    */
 121   uint32_t Count() const { return EntryCount(); }
 122
 123   /**
 124    * Returns the string entry at the given index. Keys are guaranteed to be
 125    * sorted lexographically.
 126    *
 127    * The given index *must* be less than the value returned by Count().
 128    *
 129    * The returned value is a literal string which references the mapped memory
 130    * region.
 131    */
 132   nsCString GetKeyAt(uint32_t aIndex) const {
 133     MOZ_ASSERT(aIndex < Count());
 134     return KeyTable().Get(Entries()[aIndex].mKey);
 135   }
 136
 137   /**
 138    * Returns the string value for the entry at the given index.
 139    *
 140    * The given index *must* be less than the value returned by Count().
 141    *
 142    * The returned value is a literal string which references the mapped memory
 143    * region.
 144    */
 145   nsString GetValueAt(uint32_t aIndex) const {
 146     MOZ_ASSERT(aIndex < Count());
 147     return ValueTable().Get(Entries()[aIndex].mValue);
 148   }
 149
 150   /**
 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.
 155    */
 156   FileDescriptor CloneFileDescriptor() const;
 157
 158   size_t MapSize() const { return mMap.size(); }
 159
 160  protected:
 161   ~SharedStringMap() = default;
 162
 163  private:
 164   // Type-safe getters for values in the shared memory region:
 165   const Header& GetHeader() const { return mMap.get<Header>()[0]; }
 166
 167   RangedPtr<const Entry> Entries() const {
 168     return {reinterpret_cast<const Entry*>(&GetHeader() + 1), EntryCount()};
 169   }
 170
 171   uint32_t EntryCount() const { return GetHeader().mEntryCount; }
 172
 173   StringTable<nsCString> KeyTable() const {
 174     auto& header = GetHeader();
 175     return {{&mMap.get<uint8_t>()[header.mKeyStringsOffset],
 176              header.mKeyStringsSize}};
 177   }
 178
 179   StringTable<nsString> ValueTable() const {
 180     auto& header = GetHeader();
 181     return {{&mMap.get<uint8_t>()[header.mValueStringsOffset],
 182              header.mValueStringsSize}};
 183   }
 184
 185   loader::AutoMemMap mMap;
 186 };
 187
 188 /**
 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.
 192  */
 193 class MOZ_RAII SharedStringMapBuilder {
 194  public:
 195   SharedStringMapBuilder() = default;
 196
 197   /**
 198    * Adds a key-value pair to the map.
 199    */
 200   void Add(const nsCString& aKey, const nsString& aValue);
 201
 202   /**
 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.
 206    */
 207   Result<Ok, nsresult> Finalize(loader::AutoMemMap& aMap);
 208
 209  private:
 210   using Entry = SharedStringMap::Entry;
 211
 212   StringTableBuilder<nsCStringHashKey, nsCString> mKeyTable;
 213   StringTableBuilder<nsStringHashKey, nsString> mValueTable;
 214
 215   nsTHashMap<nsCStringHashKey, Entry> mEntries;
 216 };
 217
 218 }  // namespace mozilla::dom::ipc
 219
 220 #endif  // dom_ipc_SharedStringMap_h