NamedMapTKey, TValue Class

ScaleOut Software NamedCache API
The NamedMapTKey, TValue semantics follow the signature of the ConcurrentDictionary class in Microsoft's System.Collections.Concurrent namespace and it uses ScaleOut StateServer to store keys and values. NamedMapTKey, TValue represents a thread-safe collection of key-value pairs that can be accessed by multiple threads concurrently. The map contents are coherent across the in-memory data grid.
Inheritance Hierarchy

SystemObject
  Soss.Client.ConcurrentNamedMapTKey, TValue

Namespace:  Soss.Client.Concurrent
Assembly:  soss_namedcache (in soss_namedcache.dll) Version: 6.1.0.0
Syntax

public class NamedMap<TKey, TValue>

Type Parameters

TKey
The type of keys in the map.
TValue
The type of values in the map.

The NamedMapTKey, TValue type exposes the following members.

Constructors

  NameDescription
Public methodNamedMapTKey, TValue(String)
Creates a new instance of the NamedMapTKey, TValue class corresponding to the given name. The instance uses default serializers based on the BinaryFormater class.
Public methodNamedMapTKey, TValue(String, CustomSerializerTKey, CustomSerializerTValue)
Creates a new instance of the NamedMapTKey, TValue class corresponding to the given name and assigns custom key and value serializers to it.
Top
Properties

  NameDescription
Public propertyAutoCorrectStreamPosition
Controls the stream reading behavior when the serialized key/value elements are retrieved from in-memory data grid as the memory stream chunks. When using either XML-based or Json-like custom serializers to serialize keys or values, it might be necessary for NamedMapTKey, TValue to control the memory stream position after reading an individual key or its value out of memory stream.
Public propertyAvailabilityMode
Controls whether object replication is enabled for the named map.

Enabling replication provides fault tolerance, i.e., it ensures that no data is lost in case of host failure at the expense of increased memory and network utilization. If replication is enabled (AvailabilityMode.UseReplicas), the number of replicas created is controlled by the max_replicas parameter in the ScaleOut StateServer configuration. By default, object replication is enabled.

Public propertyClientCacheSize
Gets and sets the maximum number of key/value entries in the client cache. Client cache size is set to 10000 by default.
Public propertyCoherencyIntervalMilliseconds
Gets and sets coherency interval, i.e., the maximum allowed time between the last server read request and a TryGetValue(TKey, TValue) request before the client will retrieve the object from the server instead of the client cache (if present). A coherency interval of 0 means that the values are never served out of the client cache. Coherency interval is set to 0 by default, so TryGetValue(TKey, TValue) always retrieves latest value from the server.
Public propertyInvocationGrid
Public propertyKeySerializer
Public propertyMapID
Returns the integer value used as the identifier of the named map.
Public propertyMapName
Gets the map name.
Public propertyMaxServerRetries
Sets the maximum number of server request retries when a race condition between client requests occur.
Public propertyParallelOperationTransport
Public propertyValueSerializer
Top
Methods

  NameDescription
Public methodCode exampleAddOrUpdate(TKey, FuncTKey, TValue, FuncTKey, TValue, TValue)
Adds a key/value pair to NamedMapTKey, TValue if the key does not already exist, or updates a key/value pair in the NamedMapTKey, TValue if the key already exists.
Public methodAddOrUpdate(TKey, TValue, FuncTKey, TValue, TValue)
Adds a key/value pair to the NamedMapTKey, TValue if the key does not already exist, or updates a key/value pair in the NamedMapTKey, TValue if the key already exists.
Public methodClear
Removes all keys and values from the NamedMapTKey, TValue.
Public methodContainsKey
Determines whether the NamedMapTKey, TValue contains the specified key.
Public methodContainsValue
Returns true if there are one or more keys with the specified value.

Note: this method requires that InvocationGrid is assigned to the NamedMapTKey, TValue.

Public methodCreateBulkLoader
Gets the BulkLoaderTKey, TValue view of the NamedMapTKey, TValue"/>, which can be used to efficiently put a large number of keys in the map.
Public methodEquals
Determines whether the specified object is equal to the current object.
(Inherited from Object.)
Public methodExecuteCount
Retrieves the number of key/value pairs contained in the NamedMapTKey, TValue.
Public methodCode exampleExecuteParallelQuery(QueryConditionTKey, TValue)
Runs a query on the map contents with the specified QueryConditionTKey, TValue. The operation has an infinite timeout. If QueryConditionTKey, TValue is null, all map's keys will be returned.

Note: this method requires that an InvocationGrid is assigned to the NamedMapTKey, TValue.

Public methodCode exampleExecuteParallelQuery(QueryConditionTKey, TValue, TimeSpan)
Runs a query on the map contents with the specified QueryConditionTKey, TValue. If QueryConditionTKey, TValue is null, all map's keys will be returned.

Note: this method requires that InvocationGrid is assigned to the NamedMapTKey, TValue.

Protected methodFinalize
Allows an object to try to free resources and perform other cleanup operations before it is reclaimed by garbage collection.
(Inherited from Object.)
Public methodGetHashCode
Serves as the default hash function.
(Inherited from Object.)
Public methodGetKeysForValue
Searches for a specific value in the map and returns all keys this value is associated with.

Note: this method requires that InvocationGrid is assigned to the NamedMapTKey, TValue.

Public methodGetOrAdd(TKey, FuncTKey, TValue)
Adds a key/value pair to the NamedMapTKey, TValue if the key does not already exist.
Public methodGetOrAdd(TKey, TValue)
Adds a key/value pair to the NamedMapTKey, TValue if the key does not already exist.
Public methodGetType
Gets the Type of the current instance.
(Inherited from Object.)
Public methodCode exampleInvokeTParam, TResult(NamedMapInvokableTKey, TValue, TParam, TResult, TParam)
Runs a parallel method invocation on the map contents and returns the result. The operation has an infinite timeout. The Eval and Merge methods should be defined by the instance of the NamedMapInvokableTKey, TValue, TParam, TResult class.

Note: this method requires that InvocationGrid is assigned to the NamedMapTKey, TValue.

Public methodCode exampleInvokeTParam, TResult(NamedMapInvokableTKey, TValue, TParam, TResult, TParam, TimeSpan)
Runs a parallel method invocation on the map contents and returns the result. The Eval and Merge methods should be defined via passing instance of the NamedMapInvokableTKey, TValue, TParam, TResult class.

Note: this method requires that InvocationGrid is assigned to the NamedMapTKey, TValue.

Protected methodMemberwiseClone
Creates a shallow copy of the current Object.
(Inherited from Object.)
Public methodPutAll
Efficiently puts contents of the specified map into the named map. This method should be preferred to TryAdd(TKey, TValue) when updating the map with a large number of keys and values. If the named map already contains a mapping for a key, its value will be replaced with the value in the input map.
Public methodRetrieveAllKeys
Retrieves the collection of keys in the NamedMapTKey, TValue from the ScaleOut StateServer service.
Public methodCode exampleRunMapReduceMK, MV, OK, OV(NamedMapOK, OV, MapperTKey, TValue, MK, MV, CombinerMK, MV, ReducerMK, MV, OK, OV, TimeSpan)
Provides a simple and fast way to perform a MapReduce operation that does not require Hadoop infrastructure.
Public methodStatic memberCode exampleRunMapReduceMK, MV, OK, OV(NamedMapTKey, TValue, NamedMapOK, OV, MapperTKey, TValue, MK, MV, CombinerMK, MV, ReducerMK, MV, OK, OV, TimeSpan)
Provides a simple and fast way to perform a MapReduce operation that does not require Hadoop infrastructure.
Public methodToString
Returns a string that represents the current object.
(Inherited from Object.)
Public methodTryAdd
Attempts to add the specified key and value to the NamedMapTKey, TValue.
Public methodTryGetValue
Attempts to get the value associated with the specified key from the NamedMapTKey, TValue.
Public methodTryRemove(TKey)
Attempts to remove the value with the specified key from the NamedMapTKey, TValue.
Public methodCode exampleTryRemove(TKey, RemoveBehavior, TValue)
Attempts to remove and return the value with the specified key from the NamedMapTKey, TValue. If the parameter is set to the RemoveBehaviorOptions.DoNotReturnValue, the value is removed and is not returned via the value parameter to optimize the method call performance.
Public methodTryUpdate(TKey, TValue)
Updates the key with a newValue value.
Public methodTryUpdate(TKey, TValue, TValue)
Compares the existing value for the specified key with a specified value, and if they are equal, updates the key with a third value.
Top
Remarks

Objects that are in a NamedMap are stored with minimal overhead and at much higher densities in the ScaleOut StateServer service than objects that are stored using the traditional NamedCache API. Since internal object metadata is minimized for NamedMap objects, individual objects do not have the same rich features that are available in the NamedCache API. But this allows much higher numbers of objects to be stored in memory and enables faster parallel access in your application.

Examples

Basic CRUD operations with the NamedMap class
using System;
using Soss.Client.Concurrent;

// Sample class to be put into the SOSS store.
[Serializable]
class SampleClass
{
    public int IntVal;
    public double DoubleVal;
    public string StringVal;
}

class NamedMapBasicOps
{
    static void Main(string[] args)
    {
        // Initialize object to be stored:
        SampleClass sampleObj = new SampleClass();
        sampleObj.IntVal = 2014;
        sampleObj.DoubleVal = 7.25;
        sampleObj.StringVal = "Original value";

        NamedMap<string, SampleClass> nm = new NamedMap<string, SampleClass>("myMap");

        // Add the sampleObj to the named map:
        if (nm.TryAdd("key1", sampleObj) == true)
            Console.WriteLine("Object was successfully added to the named map.");
        else
            Console.WriteLine("An unexpected element with the same key already exists.");


        // Read this key/value pair from the map:
        SampleClass retObj = null;
        bool objFound = nm.TryGetValue("key1", out retObj);
        if (objFound)
            Console.WriteLine("Object was successfully retrieved from the named map.");
        else
            Console.WriteLine("Warning: The object was unexpectedly not found.");


        // Update the object in the named map:
        retObj = nm.AddOrUpdate("key1", (k) =>
        {
            // This "addValueFactory" callback won't be called because we're doing an update
            Console.WriteLine("Warning: item unexpectedly not found during update.");
            return new SampleClass();
        }, (k, v) =>
        {
            // The "updateValueFactory" lambda used to modify our existing object:
            v.IntVal = v.IntVal * -1;
            v.DoubleVal = v.DoubleVal * -1;
            v.StringVal = "Updated value";
            return v;
        });


        // Remove the object from the map:
        bool objRemoved = nm.TryRemove("key1");
        if (objFound)
            Console.WriteLine("Object successfully removed from the named map.");
        else
            Console.WriteLine("Warning: The removal failed unexpectedly.");
    }
}
See Also

Reference