/*
* tclHash.c --
*
* Implementation of in-memory hash tables for Tcl and Tcl-based
* applications.
*
* Copyright (c) 1991-1993 The Regents of the University of California.
* Copyright (c) 1994 Sun Microsystems, Inc.
*
* See the file "license.terms" for information on usage and redistribution
* of this file, and for a DISCLAIMER OF ALL WARRANTIES.
*
* SCCS: @(#) tclHash.c 1.15 96/02/15 11:50:23
*/
#include "tclInt.h"
/*
* When there are this many entries per bucket, on average, rebuild
* the hash table to make it larger.
*/
/*
* The following macro takes a preliminary integer hash value and
* produces an index into a hash tables bucket list. The idea is
* to make it so that preliminary values that are arbitrarily similar
* will end up in different buckets. The hash function was taken
* from a random-number generator.
*/
/*
* Procedure prototypes for static procedures in this file:
*/
char *key));
char *key));
char *key));
char *key));
/*
*----------------------------------------------------------------------
*
* Tcl_InitHashTable --
*
* Given storage for a hash table, set up the fields to prepare
* the hash table for use.
*
* Results:
* None.
*
* Side effects:
* TablePtr is now ready to be passed to Tcl_FindHashEntry and
* Tcl_CreateHashEntry.
*
*----------------------------------------------------------------------
*/
void
* is supplied by the caller. */
int keyType; /* Type of keys to use in table:
* TCL_STRING_KEYS, TCL_ONE_WORD_KEYS,
* or an integer >= 2. */
{
tablePtr->numEntries = 0;
if (keyType == TCL_STRING_KEYS) {
} else if (keyType == TCL_ONE_WORD_KEYS) {
} else {
};
}
/*
*----------------------------------------------------------------------
*
* Tcl_DeleteHashEntry --
*
* Remove a single entry from a hash table.
*
* Results:
* None.
*
* Side effects:
* The entry given by entryPtr is deleted from its table and
* should never again be used by the caller. It is up to the
* caller to free the clientData field of the entry, if that
* is relevant.
*
*----------------------------------------------------------------------
*/
void
{
} else {
panic("malformed bucket chain in Tcl_DeleteHashEntry");
}
break;
}
}
}
}
/*
*----------------------------------------------------------------------
*
* Tcl_DeleteHashTable --
*
* Free up everything associated with a hash table except for
* the record for the table itself.
*
* Results:
* None.
*
* Side effects:
* The hash table is no longer useable.
*
*----------------------------------------------------------------------
*/
void
{
int i;
/*
* Free up all the entries in the table.
*/
for (i = 0; i < tablePtr->numBuckets; i++) {
}
}
/*
* Free up the bucket array, if it was dynamically allocated.
*/
}
/*
* Arrange for panics if the table is used again without
* re-initialization.
*/
}
/*
*----------------------------------------------------------------------
*
* Tcl_FirstHashEntry --
*
* Locate the first entry in a hash table and set up a record
* that can be used to step through all the remaining entries
* of the table.
*
* Results:
* The return value is a pointer to the first entry in tablePtr,
* or NULL if tablePtr has no entries in it. The memory at
* *searchPtr is initialized so that subsequent calls to
* Tcl_NextHashEntry will return all of the entries in the table,
* one at a time.
*
* Side effects:
* None.
*
*----------------------------------------------------------------------
*/
* progress through the table. */
{
return Tcl_NextHashEntry(searchPtr);
}
/*
*----------------------------------------------------------------------
*
* Tcl_NextHashEntry --
*
* Once a hash table enumeration has been initiated by calling
* Tcl_FirstHashEntry, this procedure may be called to return
* successive elements of the table.
*
* Results:
* The return value is the next entry in the hash table being
* enumerated, or NULL if the end of the table is reached.
*
* Side effects:
* None.
*
*----------------------------------------------------------------------
*/
* progress through the table. Must
* have been initialized by calling
* Tcl_FirstHashEntry. */
{
return NULL;
}
}
return hPtr;
}
/*
*----------------------------------------------------------------------
*
* Tcl_HashStats --
*
* Return statistics describing the layout of the hash table
* in its hash buckets.
*
* Results:
* The return value is a malloc-ed string containing information
* about tablePtr. It is the caller's responsibility to free
* this string.
*
* Side effects:
* None.
*
*----------------------------------------------------------------------
*/
char *
{
char *result, *p;
/*
* Compute a histogram of bucket usage.
*/
for (i = 0; i < NUM_COUNTERS; i++) {
count[i] = 0;
}
overflow = 0;
average = 0.0;
for (i = 0; i < tablePtr->numBuckets; i++) {
j = 0;
j++;
}
if (j < NUM_COUNTERS) {
count[j]++;
} else {
overflow++;
}
tmp = j;
}
/*
* Print out the histogram and a few other pieces of information.
*/
for (i = 0; i < NUM_COUNTERS; i++) {
sprintf(p, "number of buckets with %d entries: %d\n",
i, count[i]);
p += strlen(p);
}
sprintf(p, "number of buckets with %d or more entries: %d\n",
p += strlen(p);
return result;
}
/*
*----------------------------------------------------------------------
*
* HashString --
*
* Compute a one-word summary of a text string, which can be
* used to generate a hash index.
*
* Results:
* The return value is a one-word summary of the information in
* string.
*
* Side effects:
* None.
*
*----------------------------------------------------------------------
*/
static unsigned int
register char *string; /* String from which to compute hash value. */
{
register unsigned int result;
register int c;
/*
* I tried a zillion different hash functions and asked many other
* people for advice. Many people had their own favorite functions,
* all different, but no-one had much idea why they were good ones.
* I chose the one below (multiply by 9 and add new character)
* because of the following reasons:
*
* 1. Multiplying by 10 is perfect for keys that are decimal strings,
* and multiplying by 9 is just about as good.
* 2. Times-9 is (shift-left-3) plus (old). This means that each
* character's bits hang around in the low-order bits of the
* hash value for ever, plus they spread fairly rapidly up to
* the high-order bits to fill out the hash value. This seems
* works well both for decimal and non-decimal strings.
*/
result = 0;
while (1) {
c = *string;
string++;
if (c == 0) {
break;
}
}
return result;
}
/*
*----------------------------------------------------------------------
*
* StringFind --
*
* Given a hash table with string keys, and a string key, find
* the entry with a matching key.
*
* Results:
* The return value is a token for the matching entry in the
* hash table, or NULL if there was no matching entry.
*
* Side effects:
* None.
*
*----------------------------------------------------------------------
*/
static Tcl_HashEntry *
char *key; /* Key to use to find matching entry. */
{
int index;
/*
* Search all of the entries in the appropriate bucket.
*/
break;
}
if (*p1 == '\0') {
return hPtr;
}
}
}
return NULL;
}
/*
*----------------------------------------------------------------------
*
* StringCreate --
*
* Given a hash table with string keys, and a string key, find
* the entry with a matching key. If there is no matching entry,
* then create a new entry that does match.
*
* Results:
* The return value is a pointer to the matching entry. If this
* is a newly-created entry, then *newPtr will be set to a non-zero
* value; otherwise *newPtr will be set to 0. If this is a new
* entry the value stored in the entry will initially be 0.
*
* Side effects:
* A new entry may be added to the hash table.
*
*----------------------------------------------------------------------
*/
static Tcl_HashEntry *
char *key; /* Key to use to find or create matching
* entry. */
int *newPtr; /* Store info here telling whether a new
* entry was created. */
{
int index;
/*
* Search all of the entries in this bucket.
*/
break;
}
if (*p1 == '\0') {
*newPtr = 0;
return hPtr;
}
}
}
/*
* Entry not found. Add a new one to the bucket.
*/
*newPtr = 1;
hPtr->clientData = 0;
tablePtr->numEntries++;
/*
* If the table has exceeded a decent size, rebuild it with many
* more buckets.
*/
}
return hPtr;
}
/*
*----------------------------------------------------------------------
*
* OneWordFind --
*
* Given a hash table with one-word keys, and a one-word key, find
* the entry with a matching key.
*
* Results:
* The return value is a token for the matching entry in the
* hash table, or NULL if there was no matching entry.
*
* Side effects:
* None.
*
*----------------------------------------------------------------------
*/
static Tcl_HashEntry *
register char *key; /* Key to use to find matching entry. */
{
int index;
/*
* Search all of the entries in the appropriate bucket.
*/
return hPtr;
}
}
return NULL;
}
/*
*----------------------------------------------------------------------
*
* OneWordCreate --
*
* Given a hash table with one-word keys, and a one-word key, find
* the entry with a matching key. If there is no matching entry,
* then create a new entry that does match.
*
* Results:
* The return value is a pointer to the matching entry. If this
* is a newly-created entry, then *newPtr will be set to a non-zero
* value; otherwise *newPtr will be set to 0. If this is a new
* entry the value stored in the entry will initially be 0.
*
* Side effects:
* A new entry may be added to the hash table.
*
*----------------------------------------------------------------------
*/
static Tcl_HashEntry *
register char *key; /* Key to use to find or create matching
* entry. */
int *newPtr; /* Store info here telling whether a new
* entry was created. */
{
int index;
/*
* Search all of the entries in this bucket.
*/
*newPtr = 0;
return hPtr;
}
}
/*
* Entry not found. Add a new one to the bucket.
*/
*newPtr = 1;
hPtr->clientData = 0;
tablePtr->numEntries++;
/*
* If the table has exceeded a decent size, rebuild it with many
* more buckets.
*/
}
return hPtr;
}
/*
*----------------------------------------------------------------------
*
* ArrayFind --
*
* Given a hash table with array-of-int keys, and a key, find
* the entry with a matching key.
*
* Results:
* The return value is a token for the matching entry in the
* hash table, or NULL if there was no matching entry.
*
* Side effects:
* None.
*
*----------------------------------------------------------------------
*/
static Tcl_HashEntry *
char *key; /* Key to use to find matching entry. */
{
}
/*
* Search all of the entries in the appropriate bucket.
*/
if (count == 0) {
return hPtr;
}
break;
}
}
}
return NULL;
}
/*
*----------------------------------------------------------------------
*
* ArrayCreate --
*
* Given a hash table with one-word keys, and a one-word key, find
* the entry with a matching key. If there is no matching entry,
* then create a new entry that does match.
*
* Results:
* The return value is a pointer to the matching entry. If this
* is a newly-created entry, then *newPtr will be set to a non-zero
* value; otherwise *newPtr will be set to 0. If this is a new
* entry the value stored in the entry will initially be 0.
*
* Side effects:
* A new entry may be added to the hash table.
*
*----------------------------------------------------------------------
*/
static Tcl_HashEntry *
register char *key; /* Key to use to find or create matching
* entry. */
int *newPtr; /* Store info here telling whether a new
* entry was created. */
{
}
/*
* Search all of the entries in the appropriate bucket.
*/
if (count == 0) {
*newPtr = 0;
return hPtr;
}
break;
}
}
}
/*
* Entry not found. Add a new one to the bucket.
*/
*newPtr = 1;
hPtr->clientData = 0;
}
tablePtr->numEntries++;
/*
* If the table has exceeded a decent size, rebuild it with many
* more buckets.
*/
}
return hPtr;
}
/*
*----------------------------------------------------------------------
*
* BogusFind --
*
* This procedure is invoked when an Tcl_FindHashEntry is called
* on a table that has been deleted.
*
* Results:
* If panic returns (which it shouldn't) this procedure returns
* NULL.
*
* Side effects:
* Generates a panic.
*
*----------------------------------------------------------------------
*/
/* ARGSUSED */
static Tcl_HashEntry *
char *key; /* Key to use to find matching entry. */
{
panic("called Tcl_FindHashEntry on deleted table");
return NULL;
}
/*
*----------------------------------------------------------------------
*
* BogusCreate --
*
* This procedure is invoked when an Tcl_CreateHashEntry is called
* on a table that has been deleted.
*
* Results:
* If panic returns (which it shouldn't) this procedure returns
* NULL.
*
* Side effects:
* Generates a panic.
*
*----------------------------------------------------------------------
*/
/* ARGSUSED */
static Tcl_HashEntry *
char *key; /* Key to use to find or create matching
* entry. */
int *newPtr; /* Store info here telling whether a new
* entry was created. */
{
panic("called Tcl_CreateHashEntry on deleted table");
return NULL;
}
/*
*----------------------------------------------------------------------
*
* RebuildTable --
*
* This procedure is invoked when the ratio of entries to hash
* buckets becomes too large. It creates a new table with a
* larger bucket array and moves all of the entries into the
* new table.
*
* Results:
* None.
*
* Side effects:
* Memory gets reallocated and entries get re-hashed to new
* buckets.
*
*----------------------------------------------------------------------
*/
static void
{
/*
* Allocate and initialize the new bucket array, and set up
* hashing constants for new array size.
*/
*newChainPtr = NULL;
}
/*
* Rehash all of the existing entries into the new bucket array.
*/
} else {
register int *iPtr;
int count;
}
}
}
}
/*
* Free up the old bucket array, if it was dynamically allocated.
*/
ckfree((char *) oldBuckets);
}
}