Oracle Coherence for C++ API
Release 3.6.0.0

E15728-01

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::View  getEntry (Object::View vKey) const
  Locate an Entry in the hash map based on its key.
virtual Entry::Handle  getEntry (Object::View vKey)
  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

FinalView< Object 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::View 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 Entry::Handle getEntry ( Object::View  vKey  )  [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.)

FinalView<Object> 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 © 2000, 2010, Oracle and/or its affiliates. All rights reserved.