Oracle Fusion Middleware C++ API Reference for Oracle Coherence: Hashtable Class Reference

Detailed Description

coherence::util::Map

SafeHashMap

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)