pegasus/src/Pegasus/Common/HashTable.h - diff

Return to HashTable.h CVS log

Up to [Pegasus] / pegasus / src / Pegasus / Common

Diff for /pegasus/src/Pegasus/Common/HashTable.h between version 1.1 and 1.23

version 1.1, 2001/04/27 00:01:00

version 1.23, 2006/11/08 22:24:00

Line 1

//%/////////////////////////////////////////////////////////////////////////////

//%2006////////////////////////////////////////////////////////////////////////

// Company, L.P.; IBM Corp.; The Open Group; Tivoli Systems.

// IBM Corp.; EMC Corporation, The Open Group.

// IBM Corp.; EMC Corporation; VERITAS Software Corporation; The Open Group.

// EMC Corporation; VERITAS Software Corporation; The Open Group.

// EMC Corporation; Symantec Corporation; The Open Group.

// Permission is hereby granted, free of charge, to any person obtaining a

// Permission is hereby granted, free of charge, to any person obtaining a copy

// copy of this software and associated documentation files (the "Software"),

// of this software and associated documentation files (the "Software"), to

// to deal in the Software without restriction, including without limitation

// deal in the Software without restriction, including without limitation the

// the rights to use, copy, modify, merge, publish, distribute, sublicense,

// rights to use, copy, modify, merge, publish, distribute, sublicense, and/or

// and/or sell copies of the Software, and to permit persons to whom the

// sell copies of the Software, and to permit persons to whom the Software is

// Software is furnished to do so, subject to the following conditions:

// furnished to do so, subject to the following conditions:

// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR

// THE ABOVE COPYRIGHT NOTICE AND THIS PERMISSION NOTICE SHALL BE INCLUDED IN

// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,

// ALL COPIES OR SUBSTANTIAL PORTIONS OF THE SOFTWARE. THE SOFTWARE IS PROVIDED

// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL

// "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT

// THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER

// LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR

// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING

// PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT

// FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER

// HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN

// DEALINGS IN THE SOFTWARE.

// ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION

// WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

//==============================================================================

// Author: Mike Brasher (mbrasher@bmc.com)

// Modified By:

//%/////////////////////////////////////////////////////////////////////////////

#ifndef Pegasus_HashTable_h

Line 30

Line 36

#include <Pegasus/Common/Config.h>

#include <Pegasus/Common/String.h>

#include <Pegasus/Common/CIMObjectPath.h>

#include <Pegasus/Common/Linkage.h>

PEGASUS_NAMESPACE_BEGIN

PEGASUS_COMMON_LINKAGE inline Uint32 Hash(const String& str);

/* This is the default hash function object used by the HashTable template.

Specializations are provided for common types.

template<class K>

struct HashFunc

{

};

PEGASUS_TEMPLATE_SPECIALIZATION struct PEGASUS_COMMON_LINKAGE HashFunc<String>

{

static Uint32 hash(const String& str);

};

PEGASUS_TEMPLATE_SPECIALIZATION struct HashFunc<Uint32>

{

static Uint32 hash(Uint32 x) { return x + 13; }

};

PEGASUS_TEMPLATE_SPECIALIZATION struct HashFunc <CIMObjectPath>

{

static Uint32 hash (const CIMObjectPath & path)

{

return path.makeHashCode ();

}

};

// Computes a hash code for a string without regard to case. For example, it

// yields the same hash code for "AB", "ab", "Ab", and "aB".

struct PEGASUS_COMMON_LINKAGE HashLowerCaseFunc

{

static Uint32 hash(const String& str);

};

/* This is a function object used by the HashTable to compare keys. This is

the default implementation. Others may be defined and passed in the

template argument list to perform other kinds of comparisons.

template<class K>

struct EqualFunc

{

static Boolean equal(const K& x, const K& y)

{

return x == y;

}

};

PEGASUS_TEMPLATE_SPECIALIZATION struct EqualFunc <CIMObjectPath>

{

static Boolean equal (const CIMObjectPath & x, const CIMObjectPath & y)

{

return x.identical (y);

}

};

Equal function object that can be used by HashTable to compare keys that

should be treated as case insensitive.

This function can be used for hash table keys constructed from strings that

should be treated as case insensitive (e.g. class names, namespace names,

system names).

/** Representation for a bucket. The HashTable class derives from this

Note: this function compares Strings based on the process locale.

struct EqualNoCaseFunc

{

static Boolean equal (const String & x, const String & y)

{

return (0 == String::compareNoCase (x, y));

}

};

/* Representation for a bucket. The HashTable class derives from this

bucket to append a key and value. This base class just defines

the pointer to the next bucket in the chain.

class PEGASUS_COMMON_LINKAGE BucketBase

class PEGASUS_COMMON_LINKAGE _BucketBase

{

public:

/** Virtual destructor to ensure destruction of derived class

/* Default constructor. */

_BucketBase() : next(0) { }

/* Virtual destructor to ensure destruction of derived class

elements.

virtual ~BucketBase();

virtual ~_BucketBase();

/** returns true if the key pointed to by the key argument is equal

/* returns true if the key pointed to by the key argument is equal

to the internal key of this bucket. This method must be overridden

by the derived class.

virtual Boolean equal(const void* key) const = 0;

BucketBase* next;

/* Clone this bucket. */

virtual _BucketBase* clone() const = 0;

_BucketBase* next;

};

class HashTableBase;

class _HashTableRep;

/** This class implements a simple hash table forward iterator. */

/* This class implements a simple hash table forward iterator. */

class PEGASUS_COMMON_LINKAGE HashTableIteratorBase

class PEGASUS_COMMON_LINKAGE _HashTableIteratorBase

{

public:

HashTableIteratorBase() : _first(0), _last(0), _bucket(0) { }

_HashTableIteratorBase() : _first(0), _last(0), _bucket(0) { }

operator Boolean() const { return _bucket != 0; }

operator int() const { return _bucket != 0; }

HashTableIteratorBase operator++(int);

_HashTableIteratorBase operator++(int);

HashTableIteratorBase& operator++();

_HashTableIteratorBase& operator++();

HashTableIteratorBase(BucketBase** first, BucketBase** last);

_HashTableIteratorBase(_BucketBase** first, _BucketBase** last);

protected:

BucketBase** _first;

_BucketBase** _first;

BucketBase** _last;

_BucketBase** _last;

BucketBase* _bucket;

_BucketBase* _bucket;

friend HashTableBase;

friend class _HashTableRep;

};

/** The HashTableBase class is the base class which HashTable derives from.

// ATTN: reorganization not supported yet.

/*- The _HashTableRep class is the representation class used by HashTable.

This code is primarily an internal class used to implement the HashTable.

But there may be occasions to use it directly.

HashTableBase parcels out much of the large code so that that code is not

_HashTableRep parcels out much of the large code so that that code is not

instantiated by the HashTable template class many times. This scheme helps

reduce code bloat caused by templates. The HashTable template class below

acts as kind of a wrapper around this class.

HashTableBase is implemented as an array of pointers to chains of hash

_HashTableRep is implemented as an array of pointers to chains of hash

buckets. The table initially allocates some number of chains (which can

be controlled by the constructor) and then may increase the number of

chains later (resulting in a reorganization of the hash table).

ATTN: reorganization not supported yet.

class PEGASUS_COMMON_LINKAGE HashTableBase

class PEGASUS_COMMON_LINKAGE _HashTableRep

{

public:

/** This constructor allocates an array of pointers to chains of buckets,

/*- This constructor allocates an array of pointers to chains of buckets,

which of course are all empty at this time. The numChains argument

If the numChains argument is less than eight, then eight chains will

be created.

@param numChains - specifies the initial number of chains.

@param numChains specifies the initial number of chains.

HashTableBase(Uint32 numChains);

_HashTableRep(Uint32 numChains);

/** Destructor. */

/*- Copy constructor. */

~HashTableBase();

_HashTableRep(const _HashTableRep& x);

/** Returns the size of this hash table (the number of entries). */

/*- Destructor. */

Uint32 getSize() const { return _size; }

~_HashTableRep();

/** Clears the contents of this hash table. After this is called, the

/*- Assignment operator. */

getSize() method returns zero.

_HashTableRep& operator=(const _HashTableRep& x);

/*- Returns the size of this hash table (the number of entries). */

Uint32 size() const { return _size; }

/*- Clears the contents of this hash table. After this is called, the

size() method returns zero.

void clear();

/** Inserts new key-value pair into hash table. Deletes the bucket on

/*- Inserts new key-value pair into hash table. Deletes the bucket on

failure so caller need not.

@param hashCode - hash code generated by caller's hash function.

@param hashCode hash code generated by caller's hash function.

@param bucket - bucket to be inserted.

@param bucket bucket to be inserted.

@param key - pointer to key.

@param key pointer to key.

@return true if insertion successful; false if duplicate key.

Boolean insert(Uint32 hashCode, BucketBase* bucket, const void* key);

Boolean insert(Uint32 hashCode, _BucketBase* bucket, const void* key);

/** Finds the bucket with the given key. This method uses the

/*- Finds the bucket with the given key. This method uses the

BucketBase::equal() method to compare keys.

_BucketBase::equal() method to compare keys.

@param hashCode - hash code generated by caller's hash function.

@param hashCode hash code generated by caller's hash function.

@param key - void pointer to key.

@param key void pointer to key.

@return pointer to bucket with that key or zero otherwise.

const BucketBase* lookup(Uint32 hashCode, const void* key);

const _BucketBase* lookup(Uint32 hashCode, const void* key) const;

/** Removes the bucket with the given key. This method uses the

/*- Removes the bucket with the given key. This method uses the

BucketBase::equal() method to compare keys.

_BucketBase::equal() method to compare keys.

@param hashCode - hash code generated by caller's hash function.

@param hashCode hash code generated by caller's hash function.

@param key - void pointer to key.

@param key void pointer to key.

@return true if entry found and removed and false otherwise.

Boolean remove(Uint32 hashCode, const void* key);

_BucketBase** getChains() const { return _chains; }

Uint32 getNumChains() const { return _numChains; }

protected:

Uint32 _size;

Uint32 _numChains;

BucketBase** _chains;

_BucketBase** _chains;

};

/** The Bucket class is used to implement the HashTable class.

/* The _Bucket class is used to implement the HashTable class.

template<class K, class V>

template<class K, class V, class E>

class Bucket : public BucketBase

class _Bucket : public _BucketBase

{

public:

Bucket(const K& key, const V& value) : _key(key), _value(value) { }

_Bucket(const K& key, const V& value) : _key(key), _value(value) { }

virtual ~Bucket();

virtual ~_Bucket();

virtual Boolean equal(const void* key) const;

virtual _BucketBase* clone() const;

K& getKey() { return _key; }

V& getValue() { return _value; }

Line 177

Line 275

V _value;

};

template<class K, class V>

template<class K, class V, class E>

Boolean Bucket<K,V>::equal(const void* key) const

Boolean _Bucket<K, V, E>::equal(const void* key) const

{

return *((K*)key) == _key;

return E::equal(*((K*)key), _key);

}

template<class K, class V>

template<class K, class V, class E>

Bucket<K,V>::~Bucket()

_Bucket<K, V, E>::~_Bucket()

{

}

/** Iterator for HashTable class. */

template<class K, class V, class E>

template<class K, class V>

_BucketBase* _Bucket<K, V, E>::clone() const

class HashTableIterator : public HashTableIteratorBase

{

return new _Bucket<K, V, E>(_key, _value);

}

/* Iterator for HashTable class. */

template<class K, class V, class E>

class _HashTableIterator : public _HashTableIteratorBase

{

public:

HashTableIterator()

_HashTableIterator()

: HashTableIteratorBase() { }

: _HashTableIteratorBase() { }

HashTableIterator(BucketBase** first, BucketBase** last)

_HashTableIterator(_BucketBase** first, _BucketBase** last)

: HashTableIteratorBase(first, last) { }

: _HashTableIteratorBase(first, last) { }

const K& key() const { return ((Bucket<K,V>*)_bucket)->getKey(); }

const K& key() const { return ((_Bucket<K, V, E>*)_bucket)->getKey(); }

const V& value() const { return ((Bucket<K,V>*)_bucket)->getValue(); }

const V& value() const { return ((_Bucket<K, V, E>*)_bucket)->getValue(); }

};

/** HashTable provides a simple hash table implementation which associates

/** The HashTable class provides a simple hash table implementation which

key-value pairs.

associates key-value pairs.

This implementation minimizes template bloat considerably by factoring out

most of the code into a common non-template class (see _HashTableRep).

The HashTable class is mostly a wrapper to add proper type semantics to the

use of its representation class.

Hashing as always is O(1).

HashTable uses the most popular hash table implementation which utilizes

an array of pointers to bucket chains. This is organized as follows:

<pre>

+---+

| | +-----+-------+

0 | ----->| key | value |

| | +-----+-------+

+---+

| | +-----+-------+ +-----+-------+ +-----+-------+

1 | ----->| key | value |-->| key | value |-->| key | value |

| | +-----+-------+ +-----+-------+ +-----+-------+

+---+

| | +-----+-------+ +-----+-------+

N-1| ----->| key | value |-->| key | value |

| | +-----+-------+ +-----+-------+

+---+

</pre>

To locate an item a hash function is applied to the key to produce an

integer value. Then the modulo of that integer is taken with N to select

a chain (as shown above). Then the chain is searched for a bucket whose

key value is the same as the target key.

The number of chains default to DEFAULT_NUM_CHAINS but should be about

one-third the number of expected entries (so that the average chain

will be three long). Making the number of chains too large will waste

space causing the hash table to be very sparse. But for optimal efficiency,

one might set the number of chains to be the same as the expected number

of entries.

This implementation does have NOT an adaptive growth algorithm yet which

would allow it to increase the number of chains periodically based on some

statistic (e.g., when the number of entries is more than three times the

number of chains; this would keep the average chain length below three).

The following example shows how to instantiate a HashTable which associates

String keys with Uint32 values.

<pre>

typedef HashTable<String, Uint32> HT;

HT ht;

</pre>

Some of the template arguments are defaulted in the above example (the

third and forth). The instantiation is explicitly qualified like this

(which by the way has exactly the same effect).

<pre>

typedef HashTable<String, Uint32,

EqualFunc<String>, HashFunc<String>> HT;

</pre>

The third and fourth arguments are described more in detail later.

Then, entries may be inserted like this:

<pre>

ht.insert("Red", 111);

ht.insert("Green", 222);

ht.insert("Blue", 222);

</pre>

And entries may be looked up as follows:

<pre>

Uint32 value;

ht.lookup("Red", value);

</pre>

And entries may be removed like this:

<pre>

h.remove("Red");

</pre>

Iteration is done like this:

<pre>

for (HT::Iterator i = ht.start(); i; i++)

{

// To access the key call i.key()!

// To access the value call i.value()!

}

</pre>

Note that only forward iteration is supported (no backwards iteration),

AND that the hashtable MUST NOT be modified during the iteration!!!

Equality of keys is determined using the EqualFunc class which is

the default third argument of the template argument list. A new function

object may be defined and passed to modify the behavior (for example, one

might define equality of strings to ignore whitespace). Here is how to

define and use a new equality function object:

<pre>

struct MyEqualFunc

{

static Boolean equal(const String& x, const String& y)

{

// do something here to test for equality!

}

};

...

EqualFunc<String, Uint32, MyEqualFunc> ht;

</pre>

When the lookup(), insert(), and remove() methods are called, the

MyEqualFunc::equal() method will be used to determine equality.

Hash functions are provided for common types (as part of the default

HashFunc class). For other types it is possible to define a custom function

object as follows:

<pre>

struct MyHashFunc

{

static Uint32 hash(const String& x)

{

// Do some hashing here!

}

};

...

EqualFunc<String, Uint32, MyEqualFunc, MyHashFunc> ht;

</pre>

As always, the hash function should provide a reasonably uniform

distrubtion so that all of the entries don't get crowded into a few

chains. Note that a hash function which returns zero, would force

the pathalogical case in which all entries are placed in the first

chain.

template<class K, class V>

template<class K, class V, class E , class H >

class HashTable : public HashTableBase

class HashTable

{

public:

typedef HashTableIterator<K,V> Iterator;

typedef _HashTableIterator<K, V, E> Iterator;

/** By default, we create this many chains initially */

/* By default, we create this many chains initially */

enum { DEFAULT_NUM_CHAINS = 32 };

/** Constructor.

@param numChains - number of chains to create.

@param numChains number of chains to create.

HashTable(Uint32 numChains = DEFAULT_NUM_CHAINS)

HashTable(Uint32 numChains = DEFAULT_NUM_CHAINS) : _rep(numChains)

: HashTableBase(numChains)

{

}

/** Copy constructor. */

HashTable(const HashTable<K,V,E,H>& x) : _rep(x._rep)

{

}

/** Assignment operator. */

HashTable<K,V,E,H>& operator=(const HashTable<K,V,E,H>& x)

{

if (this != &x)

_rep = x._rep;

return *this;

}

/** Returns the size of this hash table (the number of entries). */

Uint32 size() const { return _rep.size(); }

/** Clears the contents of this hash table. After this is called, the

size() method returns zero.

void clear() { _rep.clear(); }

/** Inserts new key-value pair into hash table.

@param key - key component.

@param key key component.

@param value - value component.

@param value value component.

@return true on success; false if duplicate key.

Boolean insert(const K& key, const V& value)

{

return HashTableBase::insert(

return _rep.insert(

Hash(key), new Bucket<K,V>(key, value), &key);

H::hash(key), new _Bucket<K, V, E>(key, value), &key);

}

/** Checks to see if hash table contains an entry with the given key.

@param key key to be searched for

@return true if hash table contains an entry with the given key.

Boolean contains(const K& key) const

{

V value;

return lookup(key, value);

}

/** Looks up the entry with the given key.

@param key - key of entry to be located.

@param key key of entry to be located.

@param value - output value.

@param value output value.

@return true if found; false otherwise.

Boolean lookup(const K& key, V& value);

Boolean lookup(const K& key, V& value) const;

/** Removes the entry with the given key.

@param key - key of entry to be removed.

@param key key of entry to be removed.

@return true on success; false otherwise.

Boolean remove(const K& key)

{

return HashTableBase::remove(Hash(key), &key);

return _rep.remove(H::hash(key), &key);

}

/** Obtains an iterator for this object. */

Iterator start() const

{

return Iterator(_chains, _chains + _numChains);

return Iterator(

_rep.getChains(), _rep.getChains() + _rep.getNumChains());

}

private:

_HashTableRep _rep;

};

template<class K, class V>

template<class K, class V, class E, class H>

inline Boolean HashTable<K,V>::lookup(const K& key, V& value)

inline Boolean HashTable<K, V, E, H>::lookup(const K& key, V& value) const

{

Bucket<K,V>* bucket = (Bucket<K,V>*)HashTableBase::lookup(Hash(key), &key);

_Bucket<K, V, E>* bucket

= (_Bucket<K, V, E>*)_rep.lookup(H::hash(key), &key);

if (bucket)

{

Legend:

Removed from v.1.1
changed lines
	Added in v.1.23

No CVS admin address has been configured