Bug 1477626 - Document some differences between mozilla::HashTable and PLDHashTable. r=Waldo
authorNicholas Nethercote <nnethercote@mozilla.com>
Thu, 26 Jul 2018 20:15:55 +1000
changeset 484638 a75c5a2a6bea6dfb924c04a350af97c7690e08b9
parent 484637 f856cee67cd205c0b096e8d1f3b5c6fa30dd3bfd
child 484639 8d22622b5264e15e0f429c226b9f413f413ba298
push id9719
push userffxbld-merge
push dateFri, 24 Aug 2018 17:49:46 +0000
treeherdermozilla-beta@719ec98fba77 [default view] [failures only]
perfherder[talos] [build metrics] [platform microbench] (compared to previous push)
reviewersWaldo
bugs1477626
milestone63.0a1
first release with
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
last release without
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
Bug 1477626 - Document some differences between mozilla::HashTable and PLDHashTable. r=Waldo MozReview-Commit-ID: DB0KUy99DDM
mfbt/HashTable.h
xpcom/ds/PLDHashTable.h
xpcom/ds/nsTHashtable.h
--- a/mfbt/HashTable.h
+++ b/mfbt/HashTable.h
@@ -1,14 +1,41 @@
 /* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 4 -*-
  * vim: set ts=8 sts=4 et sw=4 tw=99:
  * This Source Code Form is subject to the terms of the Mozilla Public
  * License, v. 2.0. If a copy of the MPL was not distributed with this
  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
 
+// A note on the differences between mozilla::HashTable and PLDHashTable (and
+// its subclasses, such as nsTHashtable).
+//
+// - mozilla::HashTable is a lot faster, largely because it uses templates
+//   throughout *and* inlines everything. PLDHashTable inlines operations much
+//   less aggressively, and also uses "virtual ops" for operations like hashing
+//   and matching entries that require function calls.
+//
+// - Correspondingly, mozilla::HashTable use is likely to increase executable
+//   size much more than PLDHashTable.
+//
+// - mozilla::HashTable has a nicer API, with a proper HashSet vs. HashMap
+//   distinction.
+//
+// - mozilla::HashTable requires more explicit OOM checking. Use
+//   mozilla::InfallibleAllocPolicy to make allocations infallible; note that
+//   return values of possibly-allocating methods such as add() will still need
+//   checking in some fashion -- e.g. with MOZ_ALWAYS_TRUE() -- due to the use
+//   of MOZ_MUST_USE.
+//
+// - mozilla::HashTable has a default capacity on creation of 32 and a minimum
+//   capacity of 4. PLDHashTable has a default capacity on creation of 8 and a
+//   minimum capacity of 8.
+//
+// - mozilla::HashTable allocates memory eagerly. PLDHashTable delays
+//   allocating until the first element is inserted.
+
 #ifndef mozilla_HashTable_h
 #define mozilla_HashTable_h
 
 #include "mozilla/AllocPolicy.h"
 #include "mozilla/Assertions.h"
 #include "mozilla/Attributes.h"
 #include "mozilla/Casting.h"
 #include "mozilla/HashFunctions.h"
--- a/xpcom/ds/PLDHashTable.h
+++ b/xpcom/ds/PLDHashTable.h
@@ -1,14 +1,17 @@
 /* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
 /* vim: set ts=8 sts=2 et sw=2 tw=80: */
 /* This Source Code Form is subject to the terms of the Mozilla Public
  * License, v. 2.0. If a copy of the MPL was not distributed with this
  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
 
+// See the comment at the top of mfbt/HashTable.h for a comparison between
+// PLDHashTable and mozilla::HashTable.
+
 #ifndef PLDHashTable_h
 #define PLDHashTable_h
 
 #include "mozilla/Atomics.h"
 #include "mozilla/Attributes.h" // for MOZ_ALWAYS_INLINE
 #include "mozilla/fallible.h"
 #include "mozilla/HashFunctions.h"
 #include "mozilla/MemoryReporting.h"
--- a/xpcom/ds/nsTHashtable.h
+++ b/xpcom/ds/nsTHashtable.h
@@ -1,14 +1,17 @@
 /* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
 /* vim: set ts=8 sts=2 et sw=2 tw=80: */
 /* This Source Code Form is subject to the terms of the Mozilla Public
  * License, v. 2.0. If a copy of the MPL was not distributed with this
  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
 
+// See the comment at the top of mfbt/HashTable.h for a comparison between
+// PLDHashTable and mozilla::HashTable.
+
 #ifndef nsTHashtable_h__
 #define nsTHashtable_h__
 
 #include "PLDHashTable.h"
 #include "nsPointerHashKeys.h"
 #include "mozilla/Assertions.h"
 #include "mozilla/Attributes.h"
 #include "mozilla/fallible.h"