Oracle Coherence for C++ API
Release 3.6.1.0

E18813-01

Hashtable Class Reference

#include <coherence/util/Hashtable.hpp>

Inherits AbstractMap.

List of all members.


Detailed Description

An implementation of coherence::util::Map that is thread-safe, but unlike SafeHashMap does not attempt to provide stable iteration in the presence of concurrent modifications.

Hashtable is an open-addressing based hash map implementation, relying on an array of pre-allocated entry structures. This approach significantly reduces the cost of insertion into the map as there is no Entry allocation required except as part of rehashing. This optimization makes it an good candidate for short lived maps.

Though thread-safe Hashtable is optimized for single-threaded access, and assumes that in most cases escape-analysis will elide the synchronization. If the Map will be accessed concurrently by many threads it is likely that SafeHashMap would be a better choice. If the Map will largely live on a single thread, or be short lived then Hashtable is a good choice.

Note: Hashtable's entryset iterator returns Map::Entry objects which are only valid until the iterator is advanced. If the Entry needs to be retained longer then it should either be cloned or an shallow copy should be created.

Author:
mf 2009.01.23
Since:
Coherence 3.5

Public Types

typedef spec::Handle  Handle
  Hashtable Handle definition.
typedef spec::View  View
  Hashtable View definition.
typedef spec::Holder  Holder
  Hashtable 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  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 void  putAll (Map::View vMap)
  Copy all of the mappings from the specified map to this map.

The effect of this call is equivalent to that of calling put(k, v) on this map once for each mapping from key k to value v in the specified map. The behavior of this operation is unspecified if the specified map is modified while the operation is in progress.

Parameters:
vMap  mappings to be stored in this map.
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.


Protected Member Functions

  Hashtable (size32_t cEstimate=17, float32_t flLoadFactor=0.3F, float32_t flGrowthRate=3.0F)
  Construct a thread-safe hash map using the specified settings.
  Hashtable (const Hashtable &that)
  Copy constructor.

Constructor & Destructor Documentation

Hashtable ( size32_t  cEstimate = 17,
float32_t  flLoadFactor = 0.3F,
float32_t  flGrowthRate = 3.0F  
) [protected]

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

Parameters:
cEstimate  the anticipated number of elements that will be stored
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)

The documentation for this class was generated from the following file:
Copyright © 2000, 2010, Oracle and/or its affiliates. All rights reserved.