[cache] Document

src/hb-cache.hh

@@ -30,18 +30,31 @@
 #include "hb.hh"
 
 
-/* Implements a lockfree cache for int->int functions.
+/* Implements a lockfree and thread-safe cache for int->int functions,
+ * using (optionally) _relaxed_ atomic integer operations.
  *
- * The cache is a fixed-size array of 16-bit or 32-bit integers.
- * The key is split into two parts: the cache index and the rest.
+ * The cache is a fixed-size array of 16-bit or 32-bit integers,
+ * typically 256 elements.
  *
- * The cache index is used to index into the array.  The rest is used
- * to store the key and the value.
+ * The key is split into two parts: the cache index (high bits)
+ * and the rest (low bits).
+ *
+ * The cache index is used to index into the array.  The array
+ * member is a 16-bit or 32-bit integer that is used *both*
+ * to store the low bits of the key, and the value.
  *
  * The value is stored in the least significant bits of the integer.
- * The key is stored in the most significant bits of the integer.
- * The key is shifted by cache_bits to the left to make room for the
- * value.
+ * The low bits of the key are stored in the most significant bits
+ * of the integer.
+ *
+ * A cache hit is detected by comparing the low bits of the key
+ * with the high bits of the integer at the right position in the
+ * array. If they match, the value is extracted from the least
+ * significant bits of the integer and returned. Otherwise, a
+ * cache miss is detected.
+ *
+ * Cache operations (storage and retrieval) involve just a few
+ * arithmetic operations and a single memory access.
  */
 
 template <unsigned int key_bits=16,