Counter Behavior and Usage in Cache

A counter is a single long-value data structure stored in the cache. You can increment, decrement, lock, and have events registered against it. For example, a counter can be used to store the views every time a video is viewed on a social media site. It can also be used to store subscriptions against a website where people can subscribe or unsubscribe. NCache further enhances this counter by providing NCache-specific features such as Groups, Tags, Expiration, Locking, Dependencies, and more. For example, you can specify a counter against the group SubscriptionDetails which can contain customer objects as well as the subscription counter.

Behavior

  • Null is not a supported value type.
  • Counters are named. Hence, you need to provide a unique cache key for a counter.

Prerequisites

Before using the NCache client-side APIs, ensure that the following prerequisites are fulfilled:

Create Counter

The following code sample shows how a counter can be created in the cache using CreateCounter against the cache key SubscriptionCounter.

Tip

You can also configure searchable attributes such as Groups/Tags/Named Tags and invalidation attributes such as Expiration/Eviction/Dependency while creating a data structure.

try
{
  // Precondition: Cache is already connected

  // Specify unique cache key for counter
  string key = "SubscriptionCounter";

  // Set initial value of counter
  long initialValue = 15;

  // Create counter
  ICounter counter = cache.DataTypeManager.CreateCounter(key, initialValue);
}
catch (OperationFailedException ex)
{
    // NCache specific exception
    if(ex.ErrorCode == NCacheErrorCodes.KEY_ALREADY_EXISTS)
    {
        // The specified key already exists in the cache,
        // Either remove the existing object from the cache
        // Or specify another key
    }
    else
    {
        // NCache specific exception
        // Exception can occur due to:
        // Connection Failures
        // Operation Timeout
        // Operation performed during state transfer
    }
}
catch (Exception ex)
{
    // Any generic exception like ArgumentNullException or ArgumentException
}

Fetch and Update the Value of the Counter

You can update the value of a counter after its creation. The following code sample fetches a counter from the cache using GetCounter and sets its value to another value, using SetValue. It then increments its value using Increment or IncrementBy and decrements its value using Decrement or DecrementBy.

// Precondition: Cache is already connected

// Unique key for counter
string key = "SubscriptionCounter";

// Get counter against key
ICounter retrievedCounter = cache.DataTypeManager.GetCounter(key);

// Set value of counter to 100
retrievedCounter.SetValue(100);

// Increment value
long newValue =  retrievedCounter.Increment();

// Decrement value
newValue =  retrievedCounter.Decrement();

// Increment value by 10
newValue =  retrievedCounter.IncrementBy(10);

// Decrement value by 5
newValue =  retrievedCounter.DecrementBy(5);
Note

To ensure the operation is fail-safe, it is recommended to handle any potential exceptions within your application, as explained in Handling Failures.

Event Notifications on Counters

You can register cache events, key-based events, and data structure events on a data structure such as a counter. For behavior, refer to feature wise behavior.

The following code sample registers a cache event of ItemAdded and ItemUpdated as well as registers an event for ItemAdded and ItemUpdated on the counter in the cache. Once a counter is created in the cache, an ItemAdded cache-level event is fired. However, once an item is added to the counter, an ItemAdded data structure event is fired, and an ItemUpdated cache level event is fired.

Register Event on Counter Created

// Precondition: Cache is already connected

// Unique cache key for counter
string key = "SubscriptionCounter";

// Set initial value of counter
long initialValue = 15;

// Create counter
ICounter counter = cache.DataTypeManager.CreateCounter(key, initialValue);

// Register ItemAdded, ItemUpdated, ItemRemoved events on counter created
// DataTypeNotificationCallback is callback method specified
counter.RegisterNotification(DataTypeDataNotificationCallback, EventType.ItemAdded |
        EventType.ItemUpdated | EventType.ItemRemoved,
        DataTypeEventDataFilter.Data);

// Perform operations

Specify Callback for Event Notification

private void DataTypeDataNotificationCallback(string collectionName, DataTypeEventArg collectionEventArgs)
{
    switch (collectionEventArgs.EventType)
    {
        case EventType.ItemAdded:
            // Item has been added to the collection
        break;
        case EventType.ItemUpdated:
            if (collectionEventArgs.CollectionItem != null)
            {
                // Item has been updated in the collection
                // Perform operations
            }
        break;
        case EventType.ItemRemoved:
            // Item has been removed from the collection
        break;
    }
}

Locking Counter

Counters can be explicitly locked and unlocked to ensure data consistency. The following code sample creates a counter and locks it for a period of 10 seconds using Lock and then unlocks it using Unlock.

// Precondition: Cache is already connected

// Counter exists with key "SubscriptionCounter"
// Cache Key
string key = "SubscriptionCounter";

// Get counter against key
ICounter counter = cache.DataTypeManager.GetCounter(key);

// Lock counter for 10 seconds
bool isLocked = counter.Lock(TimeSpan.FromSeconds(10));
if (isLocked)
{
    // Counter is successfully locked for 10 seconds
    // Unless explicitly unlocked
}
else
{
    // Counter is not locked because either:
    // Counter is not present in the cache
    // Counter is already locked
}

counter.Unlock();

Additional Resources

NCache provides a sample application for the counter data structure on GitHub.

See Also

.NET: Alachisoft.NCache.Client.DataTypes namespace.
Java: com.alachisoft.ncache.client.datastructures namespace.
Node.js: Counter class.