Exclusive Locks on Items (Pessimistic Locking)
NCache provides a locking mechanism that exclusively locks the cached data. This mechanism locks the item using the lock handle due to which, all other users are blocked from performing any write operation on that cache item. A LockHandle is a handle associated with every locked item in the cache, which is returned by locking API.
A locked item can be fetched/updated or unlocked only when its lock
handle is provided at API level. However, you should do this with care to avoid
data integrity issues. Pessimistic locking is a very good approach if the
goal to be achieved is data consistency.
Once a lock is acquired using LockHandle, there are two mechanisms for releasing it. Both of these mechanisms are explained below.
Time based release of locks: You can also specify lock timeout while locking a
cached item. The lock timeout is the time interval after which the lock will
be automatically released if no explicit call is made for releasing the lock
during the timeout interval. This will prevent your data from being locked
for an infinite amount of time.
Forceful release of locks: Situations can arise in distributed
environments when an application which acquired the lock on a cache item
terminates abruptly or an application finalizes its
processing on locked data . In such a situation you would like to release all locks
acquired by such an application. NCache provides an unlock API, which
releases the cache item lock forcefully.
Note
It is recommended to use time based locking mechanism so that item is unlocked after the condition to be fulfilled so that resources remain acquired for minimum time.
When to Use Pessimistic Locking
Take the example discussed in the former chapter. If the same bank account is accessed by
two different users at the same instance for an update operation, a conflict might occur which
will lead to data inconsistency.
Pessimistic locking in this scenario will enable one user to access the account at one time.
On performing the operation successfully the user unlocks the item and the control is set free
which means the second user can now access the account and make amends accordingly.
Using this approach the data remains consistent and no conflict occurs.
A LockHandle is associated with an item to ensure that the particular item remains
inaccessible throughout the cache.
NCache provides method calls exclusively for locking as well as numerous
overloads that manipulate the locking mechanism.
Prerequisites
- Install either of the following NuGet packages in your application based on your NCahce edition:
- Include the following namespace in your application:
Alachisoft.NCache.ClientAlachisoft.NCache.Runtime.CachingAlachisoft.NCache.Runtime.Exceptions
- Cache must be running.
- The application must be connected to cache before performing the operation.
- For API details, refer to: ICache, Contains(), Count, Insert, Lock, LockHandle, Remove, TimeSpan, UnLock.
- Make sure that the data being added is serializable.
- To ensure the operation is fail safe, it is recommended to handle any potential exceptions within your application, as explained in Handling Failures.
- To handle any unseen exceptions, refer to the Troubleshooting section.
- Add the following Maven dependencies in your
pom.xml file:
<dependency>
<groupId>com.alachisoft.ncache</groupId>
<!--for NCache Enterprise Edition-->
<artifactId>ncache-client</artifactId>
<!--for NCache Professional Edition-->
<artifactId>ncache-professional-client</artifactId>
<version>x.x.x</version>
</dependency>
- Install and include either of the following modules in your application based on your NCache edition:
- Enterprise:
const ncache = require('ncache-client')
- Professional:
const ncache = require('ncache-professional-client')
- Cache must be running.
- The application must be connected to cache before performing the operation.
- For API details, refer to: Cache, contains(), getCount, insert, lock, LockHandle, remove, TimeSpan, unlock.
- To ensure the operation is fail safe, it is recommended to handle any potential exceptions within your application, as explained in Handling Failures.
- To handle any unseen exceptions, refer to the Troubleshooting section.
- Install the NCache Python client by executing the following command:
# Enterprise Client
pip install ncache-client
# Professional Client
pip install ncache-professional-client
- Import the NCache module in your application.
- Cache must be running.
- To ensure the operation is fail safe, it is recommended to handle any potential exceptions within your application, as explained in Handling Failures.
- To handle any unseen exceptions, refer to the Troubleshooting section.
- Add the following Maven dependencies in your
pom.xml file:
<dependency>
<groupId>com.alachisoft.ncache</groupId>
<!--for NCache Enterprise Edition-->
<artifactId>ncache-scala-client</artifactId>
<!--for NCache Professional Edition-->
<artifactId>ncache-scala-professional-client</artifactId>
<version>x.x.x</version>
</dependency>
- Import the following packages in your application:
import com.alachisoft.ncache.scala.client.*;import com.alachisoft.ncache.scala.runtime.caching.*;
- Cache must be running.
- The application must be connected to cache before performing the operation.
- Make sure that the data being added is serializable.
- To ensure the operation is fail safe, it is recommended to handle any potential exceptions within your application, as explained in Handling Failures.
- To handle any unseen exceptions, refer to the Troubleshooting section.
Lock an Item Explicitly
You can explicitly acquire lock on an item before performing any operation. Lock
method requires a TimeSpan to lock an item for a specified time. However, if
you do not want the acquired lock to expire simply specify TimeSpan.Zero.
Specifying no TimeSpan will lock an item for an infinite time.
The Lock method used in this example associates a LockHandle with a key.
Kindly ensure that the single LockHandle is associated with a single key.
Release the lock before reusing the handle; otherwise it might lead to
inconsistency of behavior.
- If an item is already locked, then ‘false’ value will be returned but you will get the updated
LockHandle.
Warning
Lock an item for the minimum TimeSpan for avoiding deadlock or starvation state.
The following example creates a LockHandle and then locks an item with the key Product:1001 for a timespan of 10 seconds which means item will be unlocked automatically after 10 seconds.
try
{
// Pre-Requisite: Cache is already connected
// Item is already added in the cache
// Specify the key of the item
string key = $"Product:1001";
//Create a new LockHandle
LockHandle lockHandle = null;
// Specify time span of 10 seconds for which the item remains locked
TimeSpan lockSpan = TimeSpan.FromSeconds(10);
// Lock the item for a time span of 10 seconds
bool lockAcquired = cache.Lock(key, lockSpan, out lockHandle);
// Verify if the item is locked successfully
if (lockAcquired == true)
{
// Item has been successfully locked
}
else
{
// Key does not exist
// Item is already locked with a different LockHandle
}
}
catch (OperationFailedException ex)
{
// NCache specific exception can occur due to:
// Connection failures
// Operation performed during state transfer
// Operation timeout
}
catch (Exception ex)
{
// Any generic exception like ArgumentNullException or ArgumentException
}
try
{
// Pre-Requisite: Cache is already connected
// Item is already added in the cache
// Specify the key of the item
String key = "Product:1001";
//Create a new LockHandle
LockHandle lockHandle = new LockHandle();
// Specify time span of 10 seconds for which the item remains locked
TimeSpan lockSpan = new TimeSpan(0, 0, 10);
// Lock the item for a time span of 10 seconds
boolean lockAcquired = cache.lock(key, lockSpan, lockHandle);
// Verify if the item is locked successfully
if (lockAcquired == true)
{
// Item has been successfully locked
}
else
{
// Key does not exist
// Item is already locked with a different LockHandle
}
}
catch (OperationFailedException ex)
{
// NCache specific exception can occur due to:
// Connection failures
// Operation performed during state transfer
// Operation timeout
}
catch(Exception ex)
{
// Any generic exception like IllegalArgumentException or NullPointerException
}
// This is an async method
try
{
// Pre-Requisite: Cache is already connected
// Item is already added in the cache
// Specify the key of the item
var key = "Product:1001";
//Create a new LockHandle
var lockHandle = new ncache.LockHandle();
// Specify time span of 10 seconds for which the item remains locked
var lockSpan = new ncache.TimeSpan(None,0,0,10);
// Lock the item for a time span of 10 seconds
var lockAcquired = await this.cache.lock(key, lockSpan, lockHandle);
// Verify if the item is locked successfully
if (lockAcquired == true)
{
// Item has been successfully locked
}
else
{
// Key does not exist
// Item is already locked with a different LockHandle
}
}
catch (error)
{
// Handle errors
}
try:
# Pre-Requisite: Cache is already connected
# Item is already added in the cache
# Specify the key of the item
key = "Product:1001"
# Create a new LockHandle
lock_handle = ncache.LockHandle()
# Specify time span of 10 seconds for which the item remains locked
lock_span = ncache.TimeSpan(None,0,0,10)
# Lock the item for a time span of 10 seconds
lock_acquired = cache.lock(key, lock_span, lock_handle)
# Verify if the item is locked successfully
if lock_acquired:
# Item has been successfully locked
print("Lock successful")
else:
# Key does not exist
# Item is already locked with a different LockHandle
print("Lock failed")
except Exception as exp:
# Handle errors
try {
// Pre-Requisite: Cache is already connected
// Item is already added in the cache
// Specify the key of the item
val key = "Product:1001"
//Create a new LockHandle
val lockHandle = new LockHandle
// Specify time span of 10 seconds for which the item remains locked
val lockSpan = new TimeSpan(0, 0, 10)
// Lock the item for a time span of 10 seconds
val lockAcquired = cache.lock(key, lockSpan, lockHandle)
// Verify if the item is locked successfully
if (lockAcquired) {
// Item has been successfully locked
}
else {
// Key does not exist
// Item is already locked with a different LockHandle
}
}
catch {
case exception: Exception => {
// Handle any errors
}
}
Recommendation: To ensure the operation is fail safe, it is recommended to handle any potential exceptions within your application, as explained in Handling Failures.
Lock an Item during Get Operation
An item can be locked during the process of its retrieval from the cache. This
means that the item will be inaccessible for others unless you release it. In
case of mismatch of key, null value is returned.
If an item is not locked and acquirelock is set true then you will get the item
along with the LockHandle.
If an item is locked and acquirelock is set false and if you pass incorrect or new empty LockHandle then null value is returned but you will get the LockHandle which was used to lock the item previously.
If an item is locked and acquirelock is set false and correct LockHandle is passed which was previously used to lock the item, then you will get the value.
Warning
Lock an item for the minimum TimeSpan for avoiding deadlock or thread starvation.
In this example a key and LockHandle is specified to fetch
the cached object and lock it. You need to specify “true” if you need to acquire
the lock. Here the item is locked with an expiration of 10 seconds which means item will be unlocked automatically after 10 seconds.
try
{
// Pre-Requisite: Cache is already connected
// Item is already added in the cache
// Specify the key of the item
string key = $"Product:1001";
// Set acquireLock flag as true
bool acquireLock = true;
// Specify time span of 10 seconds for which the item remains locked
TimeSpan lockSpan = TimeSpan.FromSeconds(10);
//Create a new LockHandle
LockHandle lockHandle = null;
// Lock the item for a time span of 10 seconds
var result = cache.Get<Product>(key, acquireLock, lockSpan, ref lockHandle);
// Verify if the item is locked successfully
if (result != null)
{
// Item has been successfully locked
}
else
{
// Key does not exist
// Item is already locked with a different LockHandle
}
}
catch (OperationFailedException ex)
{
// NCache specific exception can occur due to:
// Connection failures
// Operation performed during state transfer
// Operation timeout
}
catch (Exception ex)
{
// Any generic exception like ArgumentNullException or ArgumentException
}
try
{
// Pre-Requisite: Cache is already connected
// Item is already added in the cache
// Specify the key of the item
String key = "Product:1001";
// Set acquireLock flag as true
boolean acquireLock = true;
// Specify time span of 10 seconds for which the item remains locked
TimeSpan lockSpan = new TimeSpan(0, 0, 10);
//Create a new LockHandle
LockHandle lockHandle = new LockHandle();
// Lock the item for a time span of 10 seconds
Object result = cache.get(key, acquireLock, lockSpan, lockHandle, Object.class);
// Verify if the item is locked successfully
if (result != null)
{
// Item has been successfully locked
}
else
{
// Key does not exist
// Item is already locked with a different LockHandle
}
}
catch (OperationFailedException ex)
{
// NCache specific exception can occur due to:
// Connection failures
// Operation performed during state transfer
// Operation timeout
}
catch (Exception ex)
{
// Any generic exception like IllegalArgumentException or NullPointerException
}
// This is an async method
try
{
// Pre-Requisite: Cache is already connected
// Item is already added in the cache
// Specify the key of the item
var key = "Product:1001";
// Set acquireLock flag as true
var acquireLock = true;
// Specify time span of 10 seconds for which the item remains locked
var lockSpan = new ncache.TimeSpan(None,0,0,10);
//Create a new LockHandle
var lockHandle = new ncache.LockHandle();
// Lock the item for a time span of 10 seconds
//CacheItemVersion set to null and Readthrough Options set to null
var result = await this.cache.getCacheItem(key,null,null, acquireLock, lockSpan, lockHandle);
// Verify if the item is locked successfully
if (result != null)
{
// Item has been successfully locked
}
else
{
// Key does not exist
// Item is already locked with a different LockHandle
}
}
catch (error)
{
// Handle errors
}
try:
# Pre - Requisite: Cache is already connected
# Item is already added in the cache
# Specify the key of the item
key = "Product:1001"
# Set acquireLock flag as true
acquire_lock = True
# Specify time span of 10 seconds for which the item remains locked
lock_span = ncache.TimeSpan(None,0,0,10)
# Create a new LockHandle
lock_handle = ncache.LockHandle()
# Lock the item for a time span of 10 seconds
result = cache.get_cacheitem(key, acquirelock=acquire_lock, locktimeout=lock_span, lockhandle=lock_handle)
# Verify if the item is locked successfully
if result is not None:
# Item has been successfully locked
print("Lock successful")
else:
# Key does not exist
# Item is already locked with a different LockHandle
print("Lock failed")
except Exception as exp:
# Handle errors
try {
// Pre-Requisite: Cache is already connected
// Item is already added in the cache
// Specify the key of the item
val key = "Product:1001"
// Set acquireLock flag as true
val acquireLock = true
// Specify time span of 10 seconds for which the item remains locked
val lockSpan = new TimeSpan(0, 0, 10)
//Create a new LockHandle
val lockHandle = new LockHandle
// Lock the item for a time span of 10 seconds
val result = cache.get(key, acquireLock, lockSpan, lockHandle, classOf[Any])
// Verify if the item is locked successfully
if (result != null) {
// Item has been successfully locked
}
else {
// Key does not exist
// Item is already locked with a different LockHandle
}
}
catch {
case exception: Exception => {
// Handle any errors
}
}
Recommendation: To ensure the operation is fail safe, it is recommended to handle any potential exceptions within your application, as explained in Handling Failures.
Release Lock with Update Operation
While updating an item, you can release the lock allowing others to use the
cached data. In order to successfully release the locked item, you will need to
specify the LockHandle initially used to lock the item.
LockHandle should be the same which was used initially to lock the item otherwise you will get an exception message saying Item is Locked.
If releaseLock is set false still you have to pass the correct Lockhandle to update the item.
If an item is not locked then Lockhandle and releaseLock are of no use and they are ignored.
The following example locks an item in the cache and then gets the item using the lockHandle. The item is then updated and then reinserted in the cache using the Insert API.
try
{
// Pre-Requisite: Cache is already connected
// Item is already added in the cache
// Specify the key of the item
string key = $"Product:1001";
// Set acquireLock flag as true
bool acquireLock = true;
// Specify time span of 10 seconds for which the item remains locked
TimeSpan lockSpan = new TimeSpan(0, 0, 10);
// Initialize the lockHandle
LockHandle lockHandle = null;
CacheItem item = cache.GetCacheItem(key, acquireLock, lockSpan, ref lockHandle);
var product = new Product();
product = item.GetValue<Product>();
// Update the unitsinstock for the product
product.UnitsInStock = 200;
bool releaseLock = true;
// Item is already locked with a LockHandle
// Update the item and release the lock as well since releaseLock is set true
// Make sure that the LockHandle matches with the already added LockHandle
cache.Insert(key, item, null, lockHandle, releaseLock);
}
catch (OperationFailedException ex)
{
// NCache specific exception
if (ex.ErrorCode == NCacheErrorCodes.ITEM_LOCKED)
{
// Item is already locked with a different LockHandle
}
else
{
// NCache specific exception can occur due to:
// Connection failures
// Operation performed during state transfer
// Operation timeout
}
}
catch (Exception ex)
{
// Any generic exception like ArgumentNullException or ArgumentException
}
try
{
// Pre-Requisite: Cache is already connected
// Item is already added in the cache
// Specify the key of the item
String key = "Product:1001";
// Set acquireLock flag as true
boolean acquireLock = true;
// Specify time span of 10 seconds for which the item remains locked
TimeSpan lockSpan = new TimeSpan(0, 0, 10);
// Initialize the lockHandle
LockHandle lockHandle = new LockHandle();
CacheItem item = cache.getCacheItem(key, acquireLock, lockSpan, lockHandle);
// Update the value of item
product = item.getValue(Product.class);
product.setUnitsInStock(200);
boolean releaseLock = true;
// Item is already locked with a LockHandle
// Update the item and release the lock as well since releaseLock is set true
// Make sure that the LockHandle matches with the already added LockHandle
// writeThruOptions set to null
cache.insert(key, item, null, lockHandle,releaseLock);
}
catch (OperationFailedException ex)
{
// NCache specific exception can occur due to:
// Connection failures
// Operation performed during state transfer
// Operation timeout
}
catch (Exception ex)
{
// Any generic exception like IllegalArgumentException or NullPointerException
}
// This is an async method
try
{
// Pre-Requisite: Cache is already connected
// Item is already added in the cache
// Specify the key of the item
var key = "Product:1001";
// Set acquireLock flag as true
var acquireLock = true;
// Specify time span of 10 seconds for which the item remains locked
var lockSpan = new ncache.TimeSpan(None,0,0,10);
// Initialize the lockHandle
var lockHandle = new ncache.LockHandle();
// cacheItemVersion set to null and readThruOptions set to null;
var item = await this.cache.getCacheItem(key,null,null, acquireLock, lockSpan, lockHandle);
// Update the value of item
var product = item.getValue(ncache.JsonDataType.Object);
product.unitsInStock = 200;
var releaseLock = true;
// Item is already locked with a LockHandle
// Update the item and release the lock as well since releaseLock is set true
// Make sure that the LockHandle matches with the already added LockHandle
// writeThruOptions set to null
await this.cache.insert(key, item, null, lockHandle, releaseLock);
}
catch (error)
{
// Handle errors
}
try:
# Pre - Requisite: Cache is already connected
# Item is already added in the cache
# Specify the key of the item
key = "Product:1001"
# Set acquireLock flag as true
acquire_lock = True
# Specify time span of 10 seconds for which the item remains locked
lock_span = ncache.TimeSpan(None,0,0,10)
# Create a new LockHandle
lock_handle = ncache.LockHandle()
# Lock the item for a time span of 10 seconds
item = cache.get_cacheitem(key, acquirelock=acquire_lock, locktimeout=lock_span, lockhandle=lock_handle)
# Update the value of item
product = item.get_value(Product)
product.set_units_in_stock(20)
release_lock = True
# Item is already locked with a LockHandle
# Update the item and release the lock as well since release_lock is set True
# Make sure that the LockHandle matches with the already added LockHandle
cache.insert(key, item, lockhandle=lock_handle, releaselock=release_lock)
except Exception as exp:
# Handle errors
try {
// Pre-Requisite: Cache is already connected
// Item is already added in the cache
// Specify the key of the item
val key = "Product:1001"
// Set acquireLock flag as true
val acquireLock = true
// Specify time span of 10 seconds for which the item remains locked
val lockSpan = new TimeSpan(0, 0, 10)
// Initialize the lockHandle
val lockHandle = new LockHandle
val item = cache.getCacheItem(key, acquireLock, lockSpan, lockHandle)
// Update the value of item
var product = item.getValue(classOf[Product])
product.setUnitsInStock(200)
val releaseLock = true
// Item is already locked with a LockHandle
// Update the item and release the lock as well since releaseLock is set true
// Make sure that the LockHandle matches with the already added LockHandle
// writeThruOptions set to null
cache.insert(key, item, null, lockHandle, releaseLock)
}
catch {
case exception: Exception => {
// Handle any errors
}
}
Recommendation: To ensure the operation is fail safe, it is recommended to handle any potential exceptions within your application, as explained in Handling Failures.
Release Lock Explicitly
In order to release lock explicitly on a previously locked cached item; you will
need to specify the LockHandle initially used to lock the item.
If LockHandle is not saved, you can also use another overload of Unlock() which only takes the key to unlock the item.
Note
If invalid Lockhandle is passed then no exception will be thrown but the item will remain locked.
The following example gets an item already locked using the LockHandle and then unlocks it using the Unlock API using the Lockhandle saved before.
try
{
// Pre-Requisite: Cache is already connected
// Item is already added in the cache
// Specify the key of the item
string key = $"Product:1001";
// Set acquireLock flag as true
bool acquireLock = true;
// Specify time span of 10 seconds for which the item remains locked
TimeSpan lockSpan = TimeSpan.FromSeconds(10);
//Create a new LockHandle
LockHandle lockHandle = null;
Product result = cache.Get<Product>(key, acquireLock, lockSpan, ref lockHandle);
// Make sure that the item is already locked and the saved LockHandle is used
// Unlock locked item using saved LockHandle
cache.Unlock(key, lockHandle);
}
catch (OperationFailedException ex)
{
// NCache specific exception can occur due to:
// Connection failures
// Operation performed during state transfer
// Operation timeout
}
catch (Exception ex)
{
// Any generic exception like ArgumentNullException or ArgumentException
}
try
{
// Pre-Requisite: Cache is already connected
// Item is already added in the cache
// Specify the key of the item
String key = "Product:1001";
// Set acquireLock flag as true
boolean acquireLock = true;
// Specify time span of 10 seconds for which the item remains locked
TimeSpan lockSpan = new TimeSpan(0, 0, 10);
//Create a new LockHandle
LockHandle lockHandle = new LockHandle();
Object result = cache.get(key, acquireLock, lockSpan, lockHandle, Object.class);
// Make sure that the item is already locked and the saved LockHandle is used
// Unlock locked item using saved LockHandle
cache.unlock(key, lockHandle);
}
catch (OperationFailedException ex)
{
// NCache specific exception can occur due to:
// Connection failures
// Operation performed during state transfer
// Operation timeout
}
catch (Exception ex)
{
// Any generic exception like IllegalArgumentException or NullPointerException
}
// This is an async method
try
{
// Pre-Requisite: Cache is already connected
// Item is already added in the cache
// Specify the key of the item
var key = "Product:1001";
// Set acquireLock flag as true
var acquireLock = true;
// Specify time span of 10 seconds for which the item remains locked
var lockSpan = new ncache.TimeSpan(None,0,0,10);
//Create a new LockHandle
var lockHandle = new ncache.LockHandle();
// cacheItemVersion set to null and readThruOptions set to null;
var result = await this.cache.getCacheItem(key,null,null,acquireLock,lockSpan,lockHandle);
// Make sure that the item is already locked and the saved LockHandle is used
// Unlock locked item using saved LockHandle
await this.cache.unlock(key, lockHandle);
}
catch (error)
{
// Handle errors
}
try:
# Pre-Requisite: Cache is already connected
# Item is already added in the cache
# Specify the key of the item
key = "Product:1001"
# Set acquireLock flag as true
acquire_lock = True
# Specify time span of 10 seconds for which the item remains locked
lock_span = ncache.TimeSpan(None,0,0,10)
# Create a new LockHandle
lock_handle = ncache.LockHandle()
result = cache.get_cacheitem(key, acquirelock=acquire_lock, locktimeout=lock_span, lockhandle=lock_handle)
# Make sure that the item is already locked and the saved LockHandle is used
# Unlock locked item using saved LockHandle
cache.unlock(key, lock_handle)
except Exception as exp:
# Handle errors
try {
// Pre-Requisite: Cache is already connected
// Item is already added in the cache
// Specify the key of the item
val key = "Product:1001"
// Set acquireLock flag as true
val acquireLock = true
// Specify time span of 10 seconds for which the item remains locked
val lockSpan = TimeSpan(0, 0, 10)
//Create a new LockHandle
val lockHandle = LockHandle()
val result = cache.get(key, acquireLock, lockSpan, lockHandle, classOf[Any])
// Make sure that the item is already locked and the saved LockHandle is used
// Unlock locked item using saved LockHandle
cache.unlock(key, lockHandle)
}
catch {
case exception: Exception => {
// Handle any errors
}
}
Recommendation: To ensure the operation is fail safe, it is recommended to handle any potential exceptions within your application, as explained in Handling Failures.
Warning
NCache will ignore the locks if other overloads of Get, Insert and Remove
methods are called which do not take or use LockHandle.
Remove Item with LockHandle
The remove method is a basic method which removes the key from cache and returns the removed object to the client.
If a custom object is added to the cache, the remove method will return Object.
LockHandle should be same which was used initially to lock the item otherwise you will get the an exception message saying Item is locked.
If an item is not locked, then Lockhandle is of no use and its validity is not checked.
The following example gets an item which is previously locked using the LockHandle and then removes it by the saved LockHandle from the cache using the Remove API.
Tip
You can monitor/verify removal:
- "Cache Count" Counter in NCache Web Monitor or PerfMon Counters
- Using
cache.Contains() after expiration interval has elapsed
- Using
cache.Count before and after specifying expiration
try
{
// Pre-Requisite: Cache is already connected
// Item is already added in the cache
// Specify the key of the item
string key = $"Product:1001";
// Initialize the lockHandle
LockHandle lockHandle = null;
// Set acquireLock flag as true
bool acquireLock = true;
// Specify time span of 10 seconds for which the item remains locked
TimeSpan lockSpan = TimeSpan.FromSeconds(10);
// Get the item using the lockHandle
Product result = cache.Get<Product>(key, acquireLock, lockSpan, ref lockHandle);
// Removing locked item using saved lockHandle.
cache.Remove(key, lockHandle);
// Check if item is successfully removed
if (result != null)
{
if (result is Product)
{
Product product = (Product)result;
}
}
}
catch (OperationFailedException ex)
{
// NCache specific exception
if (ex.ErrorCode == NCacheErrorCodes.ITEM_LOCKED)
{
// Item is already locked with a different LockHandle
}
else
{
// NCache specific exception can occur due to:
// Connection failures
// Operation performed during state transfer
// Operation timeout
}
}
catch (Exception ex)
{
// Any generic exception like ArgumentNullException or ArgumentException
}
try
{
// Pre-Requisite: Cache is already connected
// Item is already added in the cache
// Specify the key of the item
String key = "Product:1001";
// Set acquireLock flag as true
boolean acquireLock = true;
// Specify time span of 10 seconds for which the item remains locked
TimeSpan lockSpan = new TimeSpan(0, 0, 10);
//Create a new LockHandle
LockHandle lockHandle = new LockHandle();
Object result = cache.get(key, acquireLock, lockSpan, lockHandle, Object.class);
// Removing locked item using saved lockHandle.
//cacheItemVersion and writeThruOptions set to null
cache.remove(key, lockHandle, null, null, Object.class);
Object test = cache.get(key, Object.class);
// check if item has been removed
if (test != null)
{
//Item has not been removed
}
else
{
// Item has been removed
}
}
catch (OperationFailedException ex)
{
if (ex.getErrorCode() == NCacheErrorCodes.ITEM_LOCKED)
{
// Item is already locked with a different LockHandle
}
else
{
// NCache specific exception can occur due to:
// Connection failures
// Operation performed during state transfer
// Operation timeout
}
}
catch (Exception ex)
{
// Any generic exception like IllegalArgumentException or NullPointerException
}
// This is an async method
try
{
// Pre-Requisite: Cache is already connected
// Item is already added in the cache
// Specify the key of the item
var key = "Product:1001";
// Set acquireLock flag as true
var acquireLock = true;
// Specify time span of 10 seconds for which the item remains locked
var lockSpan = new ncache.TimeSpan(None,0,0,10);
//Create a new LockHandle
var lockHandle = new ncache.LockHandle();
// CacheItemVersion and ReadThruOptions set to null
var result = await this.cache.getCacheItem(key,null,null, acquireLock, lockSpan, lockHandle, ncache.JsonDataType.Object);
// Removing locked item using saved lockHandle.
//cacheItemVersion and writeThruOptions set to null
await this.cache.remove(key,ncache.JsonDataType.Object, lockHandle, null, null);
var test = await this.cache.getCacheItem(key);
// check if item has been removed
if (test != null)
{
// Item has not been removed
}
else
{
// Item has been removed
}
}
catch (error)
{
// Handle errors
}
try:
# Pre-Requisite: Cache is already connected
# Item is already added in the cache
# Specify the key of the item
key = "Product:1001"
# Set acquireLock flag as true
acquire_lock = True
# Specify time span of 10 seconds for which the item remains locked
lock_span = ncache.TimeSpan(None,0,0,10)
# Create a new LockHandle
lock_handle = ncache.LockHandle()
result = cache.get_cacheitem(key, acquirelock=acquire_lock, locktimeout=lock_span, lockhandle=lock_handle)
# Removing locked item using saved lock_handle.
cache.remove(key, Product, lockhandle=lock_handle)
test = cache.get_cacheitem(key)
# Check if item has been removed
if test is not None:
# Item has not been removed
print("Remove with lock failed")
else:
# Item has been removed
print("Remove with lock successful")
except Exception as exp:
# Handle errors
try {
// Pre-Requisite: Cache is already connected
// Item is already added in the cache
// Specify the key of the item
val key = "Product:1001"
// Set acquireLock flag as true
val acquireLock = true
// Specify time span of 10 seconds for which the item remains locked
val lockSpan = new TimeSpan(0, 0, 10)
//Create a new LockHandle
val lockHandle = new LockHandle
val result = cache.get(key, acquireLock, lockSpan, lockHandle, classOf[Any])
// Removing locked item using saved lockHandle.
//cacheItemVersion and writeThruOptions set to null
cache.remove(key, lockHandle, null, null, classOf[Any])
val test = cache.get(key, classOf[Any])
// check if item has been removed
if (test != null) {
//Item has not been removed
}
else {
// Item has been removed
}
}
catch {
case exception: Exception => {
// Handle any errors
}
}
Recommendation: To ensure the operation is fail safe, it is recommended to handle any potential exceptions within your application, as explained in Handling Failures.
Warning
NCache will ignore the locks if other overloads of Get and Remove methods are called which do not take or use LockHandle.
Special Consideration while Using API Locking
NCache provides a set of APIs with and without LockHandle to fetch/update the
cache item. API's without a LockHandle ignore item locking. So you should use
all locking APIs for data manipulation. For example, if an item is locked and
you make an update API call which does not take the LockHandle as input
parameter, then the item will be updated in the cache irrespective of its
locking state.
Important
When using a locking feature, you should only use API
calls which take LockHandle as parameters. API's which do not take lock
handles can be used but should be done so with a lot of care so that it does not
affect data integrity.
Note
In case of eviction/expiration, NCache ignores locks which means that a locked
item can be removed as a result of expiration or eviction.
Topology Wise Behavior
- Mirrored and Replicated Topology
In mirror topology, for all lock operations lock is acquired on Active node and same LockHandle is then replicated to Passive node so that when Passive becomes Active, item will remain locked. Similarly unlock call is also replicated to passive node to unlock the item from passive node.
In replicated topology, client is connected to one node and for all lock operations LockHandle is generated which receives client lock operation and then same LockHandle will be replicated to all other nodes for data consistency, similarly unlock operation will also be replicated to all other nodes.
- Partitioned and Partitioned Replica Topology
In partitioned topology, LockHandle is generated and exists on the same node which contains the item and during state transfer LockHandle info is also transferred along with the item in case item moves to another node.
In partitioned-replica topology, LockHandle is generated on the active node which contains the item and same LockHandle is then replicated to its replica for data consistency and during state transfer LockHandle info is also transferred along with the item in case item moves to another node.
In Client Cache, all lock based operations are directly performed at clustered cache which means that LockHandle is generated and stored at clustered cache. No locking related information is maintained at Client Cache.
Additional Resources
NCache provides sample application for item locking on GitHub.
See Also
Cache Data Dependency on Database
Locking with Cache Item Versioning (Optimistic locking)
SQL Search in Cache