Class SynchronizedDictionary

Synchronized IDictionary wrapper that uses read/write locks to synchronize access to the underlying dictionary.

Inheritance

object

SynchronizedDictionary

LocalCache

Implements

IDictionary

ICollection

IEnumerable

ISerializable

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Namespace: Tangosol.Util.Collections

Assembly: Coherence.dll

Syntax

[Serializable]
public class SynchronizedDictionary : IDictionary, ICollection, IEnumerable, ISerializable

Remarks

This class uses read/write locks to ensure that only a single thread can modify the underlying dictionary at any given time, while allowing concurrent reads by multiple threads.

While all individual operations exposed by this class are thread-safe, you may still need to synchronize access to an instance of this class if you need to perform multiple operations atomically.

In order to do that, you can do one of the following:

• Lock the SyncRoot property. Because the write locks used internally also lock SyncRoot, this will prevent concurrent modification. However, concurrent read operations will still be allowed, which means that other threads will be able to see partial updates. If you need truly atomic multi-operation updates, you should use write locks instead.
• Use read locks. By acquiring a read lock externally, you can ensure that no modifications take place while you are reading from the dictionary. See AcquireReadLock() for details.
• Use write locks. By acquiring a write lock, you can achieve complete isolation and fully atomic multi-operation updates, as no other thread will be able to either read from or write to the dictionary until the write lock is released. See AcquireWriteLock() for details.

Note 1: If you attempt to acquire a write lock on a thread that holds a read lock, the read lock will be promoted to a write lock as soon as all read locks held by other threads are released.

Note 2: The enumerator returned by the GetEnumerator() method is not thread-safe. You should either acquire a read lock or lock the SyncRoot explicitly if you need to enumerate dictionary entries in a thread-safe manner.

Note 3: This class has been renamed from SynchronizedHashtable to SynchronizedDictionary in Coherence 3.5, to better reflect the fact that it can be used to wrap any IDictionary implementation.

Constructors

SynchronizedDictionary()

Create SynchronizedDictionary instance.

Declaration

public SynchronizedDictionary()

Remarks

This constructor will create a wrapper around the internal HashDictionary instance, which means that the created dictionary instance will support null keys, contrary to the general IDictionary contract.

See Also

HashDictionary

SynchronizedDictionary(IDictionary)

specified dictionary.

Declaration

public SynchronizedDictionary(IDictionary dict)

Parameters

Type	Name	Description
IDictionary	dict	Dictionary to wrap.

SynchronizedDictionary(int)

Create SynchronizedDictionary instance.

Declaration

public SynchronizedDictionary(int capacity)

Parameters

Type	Name	Description
int	capacity	The initial capacity of the internal HashDictionary.

Remarks

This constructor will create a wrapper around the internal HashDictionary instance, which means that the created dictionary instance will support null keys, contrary to the general IDictionary contract.

See Also

HashDictionary

SynchronizedDictionary(SerializationInfo, StreamingContext)

Initializes a new instance of the SynchronizedDictionary class using the specified SerializationInfo and StreamingContext.

Declaration

protected SynchronizedDictionary(SerializationInfo info, StreamingContext context)

Parameters

Type	Name	Description
SerializationInfo	info	A SerializationInfo object containing the information required to initialize this SynchronizedDictionary instance.
StreamingContext	context	A StreamingContext object containing the source and destination of the serialized stream associated with this dictionary.

Fields

m_dict

Wrapped, non-thread safe dictionary.

Declaration

protected readonly IDictionary m_dict

Field Value

Type	Description
IDictionary

Properties

Count

Gets the number of key/value pairs in this dictionary.

Declaration

public virtual int Count { get; }

Property Value

Type	Description
int	The number of key/value pairs in this dictionary.

Delegate

Return the delegate IDictionary.

Declaration

public virtual IDictionary Delegate { get; }

Property Value

Type	Description
IDictionary

IsFixedSize

Get a value indicating whether this dictionary has a fixed size.

Declaration

public virtual bool IsFixedSize { get; }

Property Value

Type	Description
bool	true if this dictionary has a fixed size, false otherwise.

IsReadLockHeld

Determines whether or not the current thread holds a read lock.

Declaration

public virtual bool IsReadLockHeld { get; }

Property Value

Type	Description
bool	true if the current thread holds a read lock; false otherwise.

See Also

AcquireReadLock()

AcquireReadLock(int)

IsReadOnly

Get a value indicating whether this dictionary is read-only.

Declaration

public virtual bool IsReadOnly { get; }

Property Value

Type	Description
bool	true if this dictionary is read-only, false otherwise.

IsSynchronized

Gets a value indicating whether access to this dictionary is thread-safe.

Declaration

public virtual bool IsSynchronized { get; }

Property Value

Type	Description
bool	Always true.

IsWriteLockHeld

Determines whether or not the current thread holds the write lock.

Declaration

public virtual bool IsWriteLockHeld { get; }

Property Value

Type	Description
bool	true if the current thread holds the write lock; false otherwise.

See Also

AcquireWriteLock()

AcquireWriteLock(int)

this[object]

Get or set the value associated with the specified key.

Declaration

public virtual object this[object key] { get; set; }

Parameters

Type	Name	Description
object	key	The key whose value to get or set.

Property Value

Type	Description
object	The value associated with the specified key.

Keys

Get a collection containing the keys in this dictionary.

Declaration

public virtual ICollection Keys { get; }

Property Value

Type	Description
ICollection	A collection of the keys in this dictionary.

SyncRoot

Get an object that can be used to synchronize access to this dictionary.

Declaration

public virtual object SyncRoot { get; }

Property Value

Type	Description
object	An object that is used to synchronize access to this dictionary.

Remarks

This property is used internally to synchronize mutating operations on this dictionary.

You can use it externally to block mutating operations as well, but keep in mind that simply locking this property will not prevent concurrent read operations. If you need to block both read and write operations, use AcquireWriteLock() method instead.

See Also

AcquireReadLock()

AcquireWriteLock()

Values

Get a collection containing the values in this dictionary.

Declaration

public virtual ICollection Values { get; }

Property Value

Type	Description
ICollection	A collection of the values in this dictionary.

Methods

AcquireReadLock()

Acquire a read lock.

Declaration

public void AcquireReadLock()

Remarks

This method will block until the read lock is acquired.

Multiple threads can hold read locks at the same time, but no thread will be able to acquire a write lock until all read locks are released.

This method should always be used in combination with a ReleaseReadLock() method in the following manner:

dict.AcquireReadLock();
try
{
    // access dictionary
}
finally
{
    dict.ReleaseReadLock();
}

This will ensure that the lock is released properly even if an exception is thrown by the code within the try block.

See Also

AcquireReadLock(int)

ReleaseReadLock()

AcquireReadLock(int)

Acquire a read lock.

Declaration

public bool AcquireReadLock(int timeout)

Parameters

Type	Name	Description
int	timeout	Timeout in milliseconds.

Returns

Type	Description
bool	true if a lock was acquired within the specified time, false otherwise.

Remarks

This method will attempt to acquire a read lock for up to timeout milliseconds, and will return a boolean value specifying whether or not the lock was acquired successfully.

Multiple threads can hold read locks at the same time, but no thread will be able to acquire a write lock until all read locks are released.

This method should always be used in combination with a ReleaseReadLock() method in the following manner:

if (dict.AcquireReadLock(timeout))
{
    try
    {
        // access dictionary
    }
    finally
    {
        dict.ReleaseReadLock();
    }
}

This will ensure that the dictionary is not accessed unless the lock was acquired successfully, and that the lock is released properly even if an exception is thrown by the code within the try block.

It is entirely up to you how to handle the case when the AcquireReadLock method returns false. For example, you can ignore the fact, throw an exception, or retry the operation by placing the code above within a loop.

See Also

AcquireReadLock()

ReleaseReadLock()

AcquireWriteLock()

Acquire a write lock.

Declaration

public void AcquireWriteLock()

Remarks

This method will block until the write lock is acquired.

Only a single thread can hold the write lock at any given time, and no other threads will be able to acquire either a read lock or a write lock until the write lock is released.

This method should always be used in combination with a ReleaseWriteLock() method in the following manner:

dict.AcquireWriteLock();
try
{
    // access dictionary
}
finally
{
    dict.ReleaseWriteLock();
}

This will ensure that the lock is released properly even if an exception is thrown by the code within the try block.

See Also

AcquireWriteLock(int)

ReleaseWriteLock()

AcquireWriteLock(int)

Acquire a write lock.

Declaration

public bool AcquireWriteLock(int timeout)

Parameters

Type	Name	Description
int	timeout	Timeout in milliseconds.

Returns

Type	Description
bool	true if a lock was acquired within the specified time, false otherwise.

Remarks

This method will attempt to acquire a write lock for up to timeout milliseconds, and will return a boolean value specifying whether or not the lock was acquired successfully.

Only a single thread can hold the write lock at any given time, and no other threads will be able to acquire either a read lock or a write lock until the write lock is released.

This method should always be used in combination with a ReleaseWriteLock() method in the following manner:

if (dict.AcquireWriteLock(timeout))
{
    try
    {
        // access dictionary
    }
    finally
    {
        dict.ReleaseWriteLock();
    }
}

This will ensure that the dictionary is not accessed unless the lock was acquired successfully, and that the lock is released properly even if an exception is thrown by the code within the try block.

It is entirely up to you how to handle the case when the AcquireWriteLock method returns false. For example, you can ignore the fact, throw an exception, or retry the operation by placing the code above within a loop.

See Also

AcquireWriteLock()

ReleaseWriteLock()

Add(object, object)

Add an entry with the specified key and value to this dictionary.

Declaration

public virtual void Add(object key, object value)

Parameters

Type	Name	Description
object	key	Entry key.
object	value	Entry value.

Clear()

Remove all entries from this dictionary.

Declaration

public virtual void Clear()

Contains(object)

Determine whether this dictionary contains the specified key.

Declaration

public virtual bool Contains(object key)

Parameters

Type	Name	Description
object	key	Key to search for.

Returns

Type	Description
bool	true if this dictionary contains the specified key.

CopyTo(Array, int)

Copy entries from this dictionary into the one-dimensional array.

Declaration

public virtual void CopyTo(Array array, int arrayIndex)

Parameters

Type	Name	Description
Array	array	An array to which entries should be copied.
int	arrayIndex	Index in array at which copying should start.

GetEnumerator()

Return an IDictionaryEnumerator that iterates through this dictionary.

Declaration

public virtual IDictionaryEnumerator GetEnumerator()

Returns

Type	Description
IDictionaryEnumerator	An IDictionaryEnumerator that iterates through this dictionary.

GetObjectData(SerializationInfo, StreamingContext)

Populates SerializationInfo with the data needed to serialize this object.

Declaration

public void GetObjectData(SerializationInfo info, StreamingContext context)

Parameters

Type	Name	Description
SerializationInfo	info	The SerializationInfo to populate with data.
StreamingContext	context	The serialization context.

Exceptions

Type	Condition
SecurityException	The caller does not have the required permission.

ReleaseReadLock()

Release a read lock.

Declaration

public void ReleaseReadLock()

See Also

AcquireReadLock()

AcquireReadLock(int)

ReleaseWriteLock()

Release a write lock.

Declaration

public void ReleaseWriteLock()

See Also

AcquireWriteLock()

AcquireWriteLock(int)

Remove(object)

Remove the entrty with the specified key from this dictionary.

Declaration

public virtual void Remove(object key)

Parameters

Type	Name	Description
object	key	Key that determines the entry to remove.

Implements

IDictionary

ICollection

IEnumerable

ISerializable