SafeHashMap Class Reference

#include <coherence/util/SafeHashMap.hpp>

Inherits AbstractMap.

Inherited by IdentityHashMap, and WeakHashMap.

List of all members.


Detailed Description

An implementation of coherence::util::Map that is synchronized, but minimally so.

This class is for use in situation where high concurrency is required, but so is data integrity.

All additions and removals are synchronized on the map, so to temporarily prevent changes to the map contents, synchronize on the map object.

Author:
mf 2008.02.25

Public Types

typedef spec::Handle Handle
 SafeHashMap Handle definition.
typedef spec::View View
 SafeHashMap View definition.
typedef spec::Holder Holder
 SafeHashMap Holder definition.
typedef this_spec::Handle Handle
 AbstractMap Handle definition.
typedef this_spec::View View
 AbstractMap View definition.
typedef this_spec::Holder Holder
 AbstractMap Holder definition.

Public Member Functions

virtual size32_t size () const
 Return the number of key-value mappings in this map.

Returns:
the number of key-value mappings in this map.

virtual bool isEmpty () const
 Return true if this map contains no key-value mappings.

Returns:
true if this map contains no key-value mappings.

virtual bool containsKey (Object::View vKey) const
 Return true if this map contains a mapping for the specified key.

Parameters:
vKey key whose presence in this map is to be tested.
Returns:
true if this map contains a mapping for the specified key.

virtual Object::Holder get (Object::View vKey) const
 Return the value to which this map maps the specified key.

Return NULL if the map contains no mapping for this key. A return value of NULL does not necessarily indicate that the map contains no mapping for the key; it's also possible that the map explicitly maps the key to NULL. The containsKey operation may be used to distinguish these two cases.

Parameters:
vKey key whose associated value is to be returned.
Returns:
the value to which this map maps the specified key, or NULL if the map contains no mapping for this key.
See also:
containsKey()

virtual Object::Holder put (Object::View vKey, Object::Holder ohValue)
 Associate the specified value with the specified key in this map.

If the map previously contained a mapping for this key, the old value is replaced by the specified value.

Parameters:
vKey key with which the specified value is to be associated.
ohValue value to be associated with the specified key.
Returns:
previous value associated with specified key, or NULL if there was no mapping for key. A NULL return can also indicate that the map previously associated NULL with the specified key.
Exceptions:
coherence::lang::UnsupportedOperationException if the put() operation is not supported by this map.

virtual Object::Holder remove (Object::View vKey)
 Remove the mapping for this key from this map if it is present.

Return the value to which the map previously associated the key, or NULL if the map contained no mapping for this key. (A NULL return can also indicate that the map previously associated NULL with the specified key.) The map will not contain a mapping for the specified key once the call returns.

Parameters:
vKey key whose mapping is to be removed from the map.
Returns:
previous value associated with specified key, or NULL if there was no mapping for key.
Exceptions:
coherence::lang::UnsupportedOperationException if the remove() operation is not supported by this map.

virtual void clear ()
 Remove all mappings from this map.

Exceptions:
coherence::lang::UnsupportedOperationException if the clear()operation is not supported by this map.

virtual Set::View entrySet () const
 Return a set of the mappings contained in this map.

Each element in the returned set is a Map::Entry::View. The set is backed by the map, so changes to the map are reflected in the set. If the map is modified while an iteration over the set is in progress, the results of the iteration are undefined.

Returns:
a set of the mappings contained in this map.

virtual Set::Handle entrySet ()
 Return a set of the mappings contained in this map.

Each element in the returned set is a Map::Entry::Handle. The set is backed by the map, so changes to one are reflected in the other. If the map is modified while an iteration over the set is in progress, the results of the iteration are undefined.

Returns:
a set of the mappings contained in this map.

virtual Entry::Handle getEntry (Object::View vKey) const
 Locate an Entry in the hash map based on its key.

Static Public Attributes

static const size32_t DEFAULT_INITIALSIZE
 Default initial size provides a prime modulo and is large enough that resize is not immediate.
static const size32_t BIGGEST_MODULO
 Biggest possible modulo.

Protected Member Functions

 SafeHashMap (size32_t cInitialBuckets=17, float32_t flLoadFactor=1.0F, float32_t flGrowthRate=3.0F)
 Construct a thread-safe hash map using the specified settings.
 SafeHashMap (const SafeHashMap &that)
 Copy constructor.
virtual Entry::Handle instantiateEntry (Object::View vKey, Object::Holder ohValue, size32_t nHash)
 Factory pattern, initialized with the specified valued.
virtual Entry::Handle instantiateEntry (Entry::View vEntry)
 Factory pattern, instantiate an Entry that is either a deep or shalow copy.
virtual Set::Handle instantiateEntrySet ()
 Factory pattern.
virtual Set::View instantiateEntrySet () const
 Factory pattern.
virtual void grow ()
 Resize the bucket array, rehashing all Entries.
virtual size32_t getHashCode (Object::View vKey) const
 Return the hash code to use for the specified key.
virtual Entry::Handle cloneEntryList (Entry::View vEntryThat) const
 Clone an entire linked list of entries.
virtual Entry::Handle getEntryInternal (Object::View vKey) const
 Locate an Entry in the hash map based on its key.
virtual void removeEntryInternal (Entry::Handle hEntry)
 Removes the passed Entry from the map.
virtual size32_t getBucketIndex (size32_t nHash, size32_t cBuckets) const
 Calculate the bucket number for a particular hash code.
virtual ObjectArray::View getStableBucketArray () const
 Get the bucket array, or if a resize is occurring, wait for the resize to complete and return the new bucket array.
virtual void iteratorActivated () const
 Register the activation of an Iterator.
virtual void iteratorDeactivated () const
 Unregister the (formerly active) Iterator.
virtual bool isActiveIterator () const
 Determine if there are any active Iterators, which may mean that they are in the middle of iterating over the Map.
virtual void invalidate ()
 Invaldiate the Map so it's no longer useable.
virtual bool isValid () const
 Retrun wither the Map is still valid or not.

Protected Attributes

const Object::View RESIZING
 When resizing completes, a notification is issued against this object.
size32_t m_cEntries
 The number of entries stored in the hash map, 0 <= n.
MemberHandle
< ObjectArray
m_haeBucket
 The array of hash buckets.
size32_t m_cCapacity
 The capacity of the hash map (the point at which it must resize), 1 <= n.
float32_t m_flLoadFactor
 The determining factor for the hash map capacity given a certain number of buckets, such that capactiy = bucketcount * loadfactor.
float32_t m_flGrowthRate
 The rate of growth as a fraction of the current number of buckets, 0 < n, such that the hash map grows to bucketcount * (1 + growthrate).
MemberHandle
< AtomicCounter
m_hAtomicIterators
 A count of the number of active Iterators on this map.

Classes

class  Entry
 A map entry (key-value pair). More...
class  EntrySet
 A set of entries backed by this map. More...
class  EntrySetIterator
 An Iterator over the EntrySet that is backed by the SafeHashMap. More...

Constructor & Destructor Documentation

SafeHashMap ( size32_t  cInitialBuckets = 17,
float32_t  flLoadFactor = 1.0F,
float32_t  flGrowthRate = 3.0F 
) [protected]

Construct a thread-safe hash map using the specified settings.

Parameters:
cInitialBuckets the initial number of hash buckets, 0 < n
flLoadFactor the acceptable load factor before resizing occurs, 0 < n, such that a load factor of 1.0 causes resizing when the number of entries exceeds the number of buckets
flGrowthRate the rate of bucket growth when a resize occurs, 0 < n, such that a growth rate of 1.0 will double the number of buckets: bucketcount = bucketcount * (1 + growthrate)


Member Function Documentation

virtual Entry::Handle instantiateEntry ( Object::View  vKey,
Object::Holder  ohValue,
size32_t  nHash 
) [protected, virtual]

Factory pattern, initialized with the specified valued.

Parameters:
vKey the associated key
ohValue the assocaited value
nHash the associated hash code
Returns:
a new instance of the Entry class (or a subclass thereof)

Reimplemented in IdentityHashMap, and WeakHashMap.

virtual Entry::Handle instantiateEntry ( Entry::View  vEntry  )  [protected, virtual]

Factory pattern, instantiate an Entry that is either a deep or shalow copy.

Parameters:
vEntry the Entry to copy
fDeep whether to make a deep copy of the Entry or not

Reimplemented in IdentityHashMap, and WeakHashMap.

virtual Entry::Handle getEntry ( Object::View  vKey  )  const [virtual]

Locate an Entry in the hash map based on its key.

Parameters:
vKey the key object to search for
Returns:
the Entry or NULL

virtual Set::Handle instantiateEntrySet (  )  [protected, virtual]

Factory pattern.

Returns:
a new instance of the EntrySet class (or a subclass thereof)

virtual Set::View instantiateEntrySet (  )  const [protected, virtual]

Factory pattern.

Returns:
a new instance of the EntrySet class (or a subclass thereof)

virtual size32_t getHashCode ( Object::View  vKey  )  const [protected, virtual]

Return the hash code to use for the specified key.

Parameters:
vKey the key to hash
Returns:
the hash code to use for the key

Reimplemented in IdentityHashMap.

virtual Entry::Handle cloneEntryList ( Entry::View  vEntryThat  )  const [protected, virtual]

Clone an entire linked list of entries.

This method must be called on the map that will contain the clones, to allow the map to be the parent of the entries if the entries are not static inner classes.

Parameters:
vEntryThat the entry that is the head of the list to clone
Returns:
NULL if the entry is NULL, otherwise an entry that is a clone of the passed entry, and a linked list of clones for each entry in the linked list that was passed

virtual Entry::Handle getEntryInternal ( Object::View  vKey  )  const [protected, virtual]

Locate an Entry in the hash map based on its key.

Unlike the getEntry method, there must be no side-effects of calling this method.

Parameters:
vKey the key object to search for
Returns:
the Entry or null

virtual void removeEntryInternal ( Entry::Handle  hEntry  )  [protected, virtual]

Removes the passed Entry from the map.

Note: Unlike calling the "remove" method, which is overriden at subclasses, calling this method directly does not generate any events.

Parameters:
hEntry the entry to remove from this map

virtual size32_t getBucketIndex ( size32_t  nHash,
size32_t  cBuckets 
) const [protected, virtual]

Calculate the bucket number for a particular hash code.

Parameters:
nHash the hash code
cBuckets the number of buckets
Returns:
the bucket index for the specified hash code

virtual ObjectArray::View getStableBucketArray (  )  const [protected, virtual]

Get the bucket array, or if a resize is occurring, wait for the resize to complete and return the new bucket array.

Returns:
the latest bucket array

virtual bool isActiveIterator (  )  const [protected, virtual]

Determine if there are any active Iterators, which may mean that they are in the middle of iterating over the Map.

Returns:
true iff there is at least one active Iterator

virtual bool isValid (  )  const [protected, virtual]

Retrun wither the Map is still valid or not.

Returns:
whether the Map is still valid or not.


Member Data Documentation

const size32_t DEFAULT_INITIALSIZE [static]

Default initial size provides a prime modulo and is large enough that resize is not immediate.

(A hash map probably uses less than 128 bytes initially.)

const Object::View RESIZING [protected]

When resizing completes, a notification is issued against this object.

Due to custom serialization this field cannot be marked as "final", but must be treated as such.

MemberHandle<ObjectArray> m_haeBucket [protected]

The array of hash buckets.

This field is declared volatile in order to reduce synchronization.


The documentation for this class was generated from the following file: Copyright (c) 2000-2008 Oracle. All rights reserved.