NCache as DistributedLock.Core Provider

NCacheDistributedSynchronizationProvider creates named distributed synchronization primitives backed by an NCache cluster. It creates implementations of IDistributedLock, IDistributedSemaphore, and IDistributedReaderWriterLock. For each primitive, NCache forms the cache key by adding a primitive-specific prefix before the caller-provided name, which keeps the state of different primitive types separate even when they use the same name. Creating a primitive does not acquire synchronization ownership. The application acquires ownership by calling the applicable acquisition method on the created primitive, while NCache maintains the acquisition state shared across application instances.

Note

This feature is currently supported in the NCache OpenSource edition.

Important

The DistributedLock.Core integration is supported in NCache OSS 5.3.6.2 and later.

Prerequisites

Before configuring NCache as a DistributedLock.Core provider, make sure the following prerequisites are fulfilled:

  • Install the following NuGet package in your .NET application:
  • Include the following namespaces in your application:
    • Alachisoft.NCache.Client
    • NCache.DistributedLock.Providers
  • Ensure that all application instances coordinating access to the same resource connect to the same NCache cache and use the same synchronization primitive name.
  • The NCache cache must already exist and must be running.

Configure NCache with DistributedLock.Core

The following example connects to an NCache cache, initializes NCacheDistributedSynchronizationProvider, and creates the supported synchronization primitives.

using Alachisoft.NCache.Client;
using NCache.DistributedLock.Providers;

ICache cache = CacheManager.GetCache("demoCache");

NCacheDistributedSynchronizationProvider provider = new NCacheDistributedSynchronizationProvider(
    cache,
    expirationTime: TimeSpan.FromSeconds(30));

IDistributedLock distributedLock = provider.CreateLock("invoice-processing");

IDistributedSemaphore semaphore = provider.CreateSemaphore(
    name: "email-sending",
    maxCount: 5);

IDistributedReaderWriterLock readerWriterLock = provider.CreateReaderWriterLock("product-catalog");

In this configuration:

  • CacheManager.GetCache("demoCache") returns the NCache cache instance used to store synchronization state.
  • NCacheDistributedSynchronizationProvider creates distributed synchronization primitives backed by the connected cache.
  • expirationTime specifies how long an acquisition remains valid. If the parameter is omitted, the default expiration time is 15 seconds.
  • CreateLock() creates a distributed lock that provides exclusive ownership.
  • CreateSemaphore() creates a distributed semaphore with the specified concurrency limit.
  • CreateReaderWriterLock() creates a reader-writer lock that supports concurrent readers and exclusive writers.
Important

All application instances using the same named semaphore should use the same maxCount and provider expirationTime values. The first successful creation initializes the semaphore record with its capacity and expiration configuration. Later creation calls for the same semaphore name reuse the existing values and do not update the record.

Provider Parameters

The following parameters configure NCacheDistributedSynchronizationProvider.

Parameter Description
cache* Specifies the ICache instance used to store synchronization state. The cache must already exist and must be running.
expirationTime Optional nullable TimeSpan that specifies how long an acquisition remains valid. If omitted or set to null, the default expiration time is 15 seconds.
Note

The parameter marked with an asterisk (*) is required.

Important

Acquisition expiration is not automatically renewed. Configure expirationTime to be longer than the expected maximum duration of the protected operation. If an operation continues after its acquisition expires, another application instance may acquire the same synchronization primitive while the original holder is still executing. Actual reclamation can take up to the configured expiration time plus the NCache clean interval.

Primitive Creation Parameters

The following parameters identify and configure the synchronization primitives created by the provider.

Parameter Applies To Description
name* Lock, semaphore, and reader-writer lock Specifies the logical name of the synchronization primitive. All application instances must use the same name to coordinate access to the same resource.
maxCount* Semaphore Specifies the maximum number of concurrent semaphore holders.
Note

The parameters marked with an asterisk (*) are required for the applicable creation method.

See Also

DistributedLock.Core with NCache
DistributedLock.Core API Usage