Bug 1581875 - Improving documentation of XXXHuffmanTable::lookup;r=arai

Differential Revision: https://phabricator.services.mozilla.com/D46952

--HG--
extra : moz-landing-system : lando

Author: David Teller

js/src/frontend/BinASTTokenReaderContext.cpp

@@ -59,15 +59,6 @@ static_assert(
 // more bites than necessary, just to be on the safe side.
 const uint8_t MAX_PREFIX_BIT_LENGTH = 32;
 
-// Maximal bit length acceptable in a `HuffmanTableSaturated`.
-//
-// As `HuffmanTableSaturated` require O(2 ^ max bit len) space, we
-// cannot afford to use them for all tables. Whenever the max bit
-// length in the table is <= MAX_BIT_LENGTH_IN_SATURATED_TABLE,
-// we use a `HuffmanTableSaturated`. Otherwise, we fall back to
-// a slower but less memory-hungry solution.
-const uint8_t MAX_BIT_LENGTH_IN_SATURATED_TABLE = 10;
-
 // The length of the bit buffer, in bits.
 const uint8_t BIT_BUFFER_SIZE = 64;
 
@@ -2053,7 +2044,7 @@ JS::Result<Ok> SingleLookupHuffmanTable<T>::initWithSingleValue(JSContext* cx,
 template <typename T>
 JS::Result<Ok> SingleLookupHuffmanTable<T>::initStart(
     JSContext* cx, size_t numberOfSymbols, uint8_t largestBitLength) {
-  MOZ_ASSERT(largestBitLength <= MAX_BIT_LENGTH_IN_SATURATED_TABLE);
+  MOZ_ASSERT_IF(largestBitLength != 32, uint32_t(1) << largestBitLength <= mozilla::MaxValue<InternalIndex>::value);
   MOZ_ASSERT(values.empty());  // Make sure that we're initializing.
 
   this->largestBitLength = largestBitLength;

js/src/frontend/BinASTTokenReaderContext.h

@@ -236,13 +236,16 @@ class NaiveHuffmanTable {
 
   // Lookup a value in the table.
   //
-  // Return an entry with a value of `nullptr` if the value is not in the table.
+  // The return of this method contains:
   //
-  // The lookup may advance `key` by `[0, key.bitLength]` bits. Typically, in a
-  // table with a single instance, or if the value is not in the table, it
-  // will advance by 0 bits. The caller is responsible for advancing its
-  // bitstream by `result.key.bitLength` bits.
-  HuffmanEntry<const T*> lookup(HuffmanLookup key) const;
+  // - the resulting value (`nullptr` if the value is not in the table);
+  // - the number of bits in the entry associated to this value.
+  //
+  // Note that entries inside a single table are typically associated to
+  // distinct bit lengths. The caller is responsible for checking
+  // the result of this method and advancing the bitstream by
+  // `result.key.bitLength` bits.
+  HuffmanEntry<const T*> lookup(HuffmanLookup lookup) const;
 
   // The number of values in the table.
   size_t length() const { return values.length(); }
@@ -459,12 +462,15 @@ class SingleLookupHuffmanTable {
 
   // Lookup a value in the table.
   //
-  // Return an entry with a value of `nullptr` if the value is not in the table.
+  // The return of this method contains:
   //
-  // The lookup may advance `key` by `[0, key.bitLength]` bits. Typically, in a
-  // table with a single instance, or if the value is not in the table, it
-  // will advance by 0 bits. The caller is responsible for advancing its
-  // bitstream by `result.key.bitLength` bits.
+  // - the resulting value (`nullptr` if the value is not in the table);
+  // - the number of bits in the entry associated to this value.
+  //
+  // Note that entries inside a single table are typically associated to
+  // distinct bit lengths. The caller is responsible for checking
+  // the result of this method and advancing the bitstream by
+  // `result.key.bitLength` bits.
   HuffmanEntry<const T*> lookup(HuffmanLookup key) const;
 
   // The number of values in the table.
@@ -654,12 +660,15 @@ class MultiLookupHuffmanTable {
 
   // Lookup a value in the table.
   //
-  // Return an entry with a value of `nullptr` if the value is not in the table.
+  // The return of this method contains:
   //
-  // The lookup may advance `key` by `[0, key.bitLength]` bits. Typically, in a
-  // table with a single instance, or if the value is not in the table, it
-  // will advance by 0 bits. The caller is responsible for advancing its
-  // bitstream by `result.key.bitLength` bits.
+  // - the resulting value (`nullptr` if the value is not in the table);
+  // - the number of bits in the entry associated to this value.
+  //
+  // Note that entries inside a single table are typically associated to
+  // distinct bit lengths. The caller is responsible for checking
+  // the result of this method and advancing the bitstream by
+  // `result.key.bitLength` bits.
   HuffmanEntry<const T*> lookup(HuffmanLookup key) const;
 
   // The number of values in the table.
@@ -786,12 +795,15 @@ struct GenericHuffmanTable {
 
   // Lookup a value in the table.
   //
-  // Return an entry with a value of `nullptr` if the value is not in the table.
+  // The return of this method contains:
   //
-  // The lookup may advance `key` by `[0, key.bitLength]` bits. Typically, in a
-  // table with a single instance, or if the value is not in the table, it
-  // will advance by 0 bits. The caller is responsible for advancing its
-  // bitstream by `result.key.bitLength` bits.
+  // - the resulting value (`nullptr` if the value is not in the table);
+  // - the number of bits in the entry associated to this value.
+  //
+  // Note that entries inside a single table are typically associated to
+  // distinct bit lengths. The caller is responsible for checking
+  // the result of this method and advancing the bitstream by
+  // `result.key.bitLength` bits.
   HuffmanEntry<const T*> lookup(HuffmanLookup key) const;
 
  private: