3.3 Inspection modes

3.3.1 Hash table inspection modes

There are three hash table inspection modes. They can be accessed in either the Common LispWorks or teletype inspectors.

A brief introduction to the representation of hash tables is necessary so that you can fully understand what you gain from the new modes.

Internally, a hash table is a structure containing, among other things,

a big vector
size and growth information
accessing functions.

When keys and values are added to the table, sufficiently similar keys are converted into the same index in the vector. When this happens, the similar keys and values are kept together in a chain that hangs off this place in the vector.

The different inspection modes provide views of different pieces of this structure:

HASH-TABLE: This mode is the "normal" view of a hash table; as a table of keys and values. When you inspect an item you inspect the value of the item.
ENUMERATED-HASH-TABLE
: This mode is a variation of the normal view, where a hash table is viewed simply as a list of lists. When you inspect an item you are inspecting a list containing a key and a value.
HASH-TABLE-STATISTICS
: This mode shows how long the chains in the hash table are, so that you can tell how efficiently it is being used. For example, if all chains contained fewer than two items the hash table would be being used well.
HASH-TABLE-HISTOGRAM
: This mode shows the statistical information fromHASH-TABLE-STATISTICS as a histogram.
STRUCTURE: This mode provides a raw view of the whole hash table structure. When you inspect an item you are inspecting the value of that slot in the hash table structure.

Here is an example of hash table inspection.

CL-USER 1 > (setq hash (make-hash-table)) 
Warning: Setting unbound variable HASH
#<EQL Hash table{0} 49ee564>

CL-USER 2 > (setf (gethash 'lisp hash) 'programming 
                  (gethash 'prolog hash) 'programming
                  (gethash 'c hash) 'programming
                  (gethash 'c++ hash) 'programming
                  (gethash 'english hash) 'natural
                  (gethash 'german hash) 'natural)
NATURAL

CL-USER 3 > (inspect hash) 

#<EQL Hash table{6} 49ee564> is a HASH-TABLE
[C++]       :  PROGRAMMING
[GERMAN]    :  NATURAL
[PROLOG]    :  PROGRAMMING
[LISP]      :  PROGRAMMING
[ENGLISH]   :  NATURAL
[C]         :  PROGRAMMING

CL-USER 4 : Inspect 1 > :m 
  1. HASH-TABLE
  2. HASH-TABLE-HISTOGRAM
  3. HASH-TABLE-STATISTICS
  4. ENUMERATED-HASH-TABLE
  5. STRUCTURE

CL-USER 5 : Inspect 1 > :m 3 


[chain of length 0 :]   :  25
[chain of length 1 :]   :  6

CL-USER 6 : Inspect 1 >

The hash table statistics show thathash has 31chains, of which 25 are empty and 6 have one entry.

CL-USER 6 : Inspect 1 > :m 2 
 

[chain of length 0 :]   :  "*************************"
[chain of length 1 :]   :  "******"

CL-USER 7 : Inspect 1 >

Here, the same information is represented as a histogram.

Below is the raw representation of the hash table:

CL-USER 7 : Inspect 1 > :m 5 

#<EQL Hash table{6} 49ee564> is a HASH-TABLE
[KIND]                 :  EQL
[SIZE]                 :  31
[REHASH-SIZE]          :  2.0
[REHASH-THRESHOLD]     :  1.0
[THRESHOLD]            :  31
[COUNTER]              :  850
[NUMBER-ENTRIES]       :  6
[TABLE]                :  #(NIL NIL NIL NIL 
                       #%((C . PROGRAMMING) NIL) NIL
                       NIL #%((ENGLISH . NATURAL) NIL)
                       NIL NIL ...)
[NO-DESTRUCT-REHASH]   :  NIL
[POWER2]               :  5
[HASH-REM]             :  SYSTEM::DIVIDE-5-1
[HASH-FN]              :  SYSTEM::EQL-HASHFN
[GETHASH-FN]           :  SYSTEM::GETHASH-EQL
[PUTHASH-FN]           :  SYSTEM::PUTHASH-EQL
[REMHASH-FN]           :  SYSTEM::REMHASH-EQL
[ENSURE-TLATTER-FN]    :  SYSTEM::ENSURE-TLATTER-EQL

CL-USER 8 : Inspect 1 >