Add distributed LockAsync support to cache interfaces

Implemented LockAsync in IAdvancedDistributedCache, AdvancedMemoryCache, and AdvancedRedisCache to provide distributed locking with expiration. Updated documentation and bumped version to 1.0.21.

Author: RobK410

src/IAdvancedDistributedCache.cs

@@ -157,5 +157,18 @@ public interface IAdvancedDistributedCache : IDistributedCache, IDisposable
         /// <param name="token">Contains an optional cancellation token.</param>
         /// <returns>Returns a value indicating success.</returns>
         Task<bool> HashFieldsExpireAsync(string hashKey, string[] fieldNames, TimeSpan expiration, CancellationToken token = default);
+
+        /// <summary>
+        /// Attempts to acquire a distributed lock for the specified key with a given expiration time.
+        /// </summary>
+        /// <remarks>If the lock is already held by another process, the method returns <see
+        /// langword="false"/> immediately without waiting. The lock will be automatically released after the specified
+        /// expiration time if not released earlier.</remarks>
+        /// <param name="key">The unique identifier for the lock to acquire. Cannot be null or empty.</param>
+        /// <param name="expirationTime">The duration for which the lock will be held before it expires automatically.</param>
+        /// <param name="cancellationToken">A cancellation token that can be used to cancel the lock acquisition operation.</param>
+        /// <returns>A task that represents the asynchronous operation. The task result is <see langword="true"/> if the lock was
+        /// successfully acquired; otherwise, <see langword="false"/>.</returns>
+        Task<bool> LockAsync(string key, TimeSpan expirationTime, CancellationToken cancellationToken = default);
     }
 }

src/Memory/AdvancedMemoryCache.cs

@@ -422,6 +422,31 @@ public async Task<bool> HashFieldsExpireAsync(string hashKey, string[] fieldName
             return await Task.FromResult(result);
         }
 
+        /// <summary>
+        /// Attempts to acquire a lock for the specified key with a given expiration time, using an asynchronous
+        /// operation.
+        /// </summary>
+        /// <param name="key">The unique identifier for the lock to acquire. Cannot be null.</param>
+        /// <param name="expirationTime">The duration for which the lock should be held before it expires.</param>
+        /// <param name="cancellationToken">A cancellation token that can be used to cancel the asynchronous operation.</param>
+        /// <returns>A task that represents the asynchronous operation. The task result is <see langword="true"/> if the lock was
+        /// successfully acquired; otherwise, <see langword="false"/>.</returns>
+        /// <exception cref="ArgumentNullException">Thrown if <paramref name="key"/> is null.</exception>
+        public async Task<bool> LockAsync(string key, TimeSpan expirationTime, CancellationToken cancellationToken = default)
+        {
+            bool result = false;
+            if (key == null)
+            {
+                throw new ArgumentNullException(nameof(key));
+            }
+            if (!memoryDictionary.ContainsKey(key))
+            {
+                memoryDictionary[key] = "LOCKED";
+                result = true;
+            }
+            return await Task.FromResult(result);
+        }
+
         #region IDisposeable Methods
 
             /// <summary>

src/Redis/AdvancedRedisCache.cs

@@ -591,7 +591,7 @@ public async Task<bool> HashSetAsync(string hashKey, string fieldName, string va
                 token.ThrowIfCancellationRequested();
                 await this.Cache.KeyExpireAsync(hashKey, expiration);
             }
-
+            
             return result;
         }
 
@@ -720,13 +720,36 @@ public async Task<bool> HashFieldsExpireAsync(string hashKey, string[] fieldName
 
             return result;
         }
+
+        /// <summary>
+        /// Attempts to acquire a distributed lock for the specified key with a given expiration time.
+        /// </summary>
+        /// <remarks>If the lock is already held by another process, the method returns <see
+        /// langword="false"/> immediately without waiting. The lock will be automatically released after the specified
+        /// expiration time if not released earlier.</remarks>
+        /// <param name="key">The unique identifier for the lock to acquire. Cannot be null or empty.</param>
+        /// <param name="expirationTime">The duration for which the lock will be held before it expires automatically.</param>
+        /// <param name="cancellationToken">A cancellation token that can be used to cancel the lock acquisition operation.</param>
+        /// <returns>A task that represents the asynchronous operation. The task result is <see langword="true"/> if the lock was
+        /// successfully acquired; otherwise, <see langword="false"/>.</returns>
+        public async Task<bool> LockAsync(string key, TimeSpan expirationTime, CancellationToken cancellationToken = default)
+        {
+            if (string.IsNullOrEmpty(key))
+            {
+                throw new ArgumentNullException(nameof(key));
+            }
+            await this.ConnectAsync(cancellationToken);
+            cancellationToken.ThrowIfCancellationRequested();
+            var result = await this.Cache.ExecuteAsync("SET", this.instance + key, "1", "NX", "PX", (long)expirationTime.TotalMilliseconds);
+            return result.ToString() == "OK";
+        }
         #endregion
 
         #region IDisposeable Methods
 
-            /// <summary>
-            /// This method is used to dispose of the internal disposable objects.
-            /// </summary>
+        /// <summary>
+        /// This method is used to dispose of the internal disposable objects.
+        /// </summary>
         public void Dispose()
         {
             Dispose(true);

src/Talegen.AspNetCore.AdvancedCache.csproj

@@ -6,7 +6,7 @@
     <ApplicationIcon>Assets\logo.ico</ApplicationIcon>
     <GeneratePackageOnBuild>True</GeneratePackageOnBuild>
     <Title>Talegen ASP.net Core Advanced Cache Library</Title>
-    <Version>1.0.20</Version>
+    <Version>1.0.21</Version>
     <Authors>Talegen, LLC</Authors>
     <Description>A simple advanced IDistributedCache extension implementing Redis cache client.</Description>
     <Copyright>Copyright (c) Talegen, LLC.</Copyright>