From 3dd4d928265b2d8b80270d38fba8f7cf2c568ca4 Mon Sep 17 00:00:00 2001
From: Chris Simmons <gitlab.com@netchris.com>
Date: Sun, 11 Jan 2026 13:22:06 -0800
Subject: [PATCH 1/2] IApplicationAdvisoryLockService

---
 .../IApplicationAdvisoryLockService.cs        | 22 +++++++++++++++++++
 1 file changed, 22 insertions(+)
 create mode 100644 NetChris.Core/Patterns/IApplicationAdvisoryLockService.cs

diff --git a/NetChris.Core/Patterns/IApplicationAdvisoryLockService.cs b/NetChris.Core/Patterns/IApplicationAdvisoryLockService.cs
new file mode 100644
index 0000000..164a91e
--- /dev/null
+++ b/NetChris.Core/Patterns/IApplicationAdvisoryLockService.cs
@@ -0,0 +1,22 @@
+using System.Threading;
+using System.Threading.Tasks;
+
+namespace NetChris.Core.Patterns;
+
+/// <summary>
+/// Provides advisory lock services for a distributed application
+/// </summary>
+/// <remarks>
+/// This is inspired by Postgres advisory locks.  See the links below for more information.
+/// </remarks>
+/// <see href="https://www.postgresql.org/docs/current/explicit-locking.html#ADVISORY-LOCKS"/>
+/// <see href="https://www.postgresql.org/docs/current/functions-admin.html#FUNCTIONS-ADVISORY-LOCKS"/>
+public interface IApplicationAdvisoryLockService
+{
+    /// <summary>
+    /// Sets an advisory lock asynchronously for the specified value on the transaction
+    /// </summary>
+    /// <param name="lockId">The advisory lock ID</param>
+    /// <param name="cancellationToken">The cancellation token used when first acquiring the lock</param>
+    Task SetAdvisoryLockAsync(int lockId, CancellationToken cancellationToken);
+}
\ No newline at end of file

From 61a4c4246d1b86e02a2a6720a320daf5d928e23f Mon Sep 17 00:00:00 2001
From: Chris Simmons <gitlab.com@netchris.com>
Date: Sun, 11 Jan 2026 14:21:24 -0800
Subject: [PATCH 2/2] SetTransactionAdvisoryLockAsync

---
 .../Patterns/IApplicationAdvisoryLockService.cs        | 10 ++++++++--
 1 file changed, 8 insertions(+), 2 deletions(-)

diff --git a/NetChris.Core/Patterns/IApplicationAdvisoryLockService.cs b/NetChris.Core/Patterns/IApplicationAdvisoryLockService.cs
index 164a91e..74f3f79 100644
--- a/NetChris.Core/Patterns/IApplicationAdvisoryLockService.cs
+++ b/NetChris.Core/Patterns/IApplicationAdvisoryLockService.cs
@@ -14,9 +14,15 @@ namespace NetChris.Core.Patterns;
 public interface IApplicationAdvisoryLockService
 {
     /// <summary>
-    /// Sets an advisory lock asynchronously for the specified value on the transaction
+    /// Sets a transaction-level advisory lock for specified value
     /// </summary>
+    /// <remarks>
+    /// As the name implies, the lock is help for the duration of a transaction.  There is no prescription where that
+    /// transaction lives or how it is managed.  It is up to the application to ensure that the implementation uses some
+    /// mechanism (usually a database transaction), to ensure that the transaction is resolved (committed or rolled back)
+    /// in a timely manner.
+    /// </remarks>
     /// <param name="lockId">The advisory lock ID</param>
     /// <param name="cancellationToken">The cancellation token used when first acquiring the lock</param>
-    Task SetAdvisoryLockAsync(int lockId, CancellationToken cancellationToken);
+    Task SetTransactionAdvisoryLockAsync(int lockId, CancellationToken cancellationToken);
 }
\ No newline at end of file