Version bumps and readme update

Author: madelson

README.md

@@ -141,6 +141,8 @@ Contributions are welcome! If you are interested in contributing towards a new o
 Setup steps for working with the repository locally are documented [here](docs/Developing%20DistributedLock.md).
 
 ## Release notes
+- 2.6
+	- Add support for acquiring transaction-scoped Postgres locks using externally-owned transactions. Thanks [@Tzachi009](https://github.com/Tzachi009) for implementing! ([#213](https://github.com/madelson/DistributedLock/issues/213), DistributedLock.Postgres 1.3)
 - 2.5.1
 	- Increase efficiency of Azure blob locks when the blob does not exist. Thanks [@richardkooiman](https://github.com/richardkooiman) for implementing! ([#227](https://github.com/madelson/DistributedLock/pull/227), DistributedLock.Azure 1.0.2)
 	- Improve error handling in race condition scenarios for Azure blobs. Thanks [@MartinDembergerR9](https://github.com/MartinDembergerR9) for implementing! ([#228](https://github.com/madelson/DistributedLock/pull/228), DistributedLock.Azure 1.0.2)

docs/DistributedLock.Postgres.md

@@ -18,6 +18,17 @@ await using (await @lock.AcquireAsync())
 - The `PostgresDistributedReaderWriterLock` class implements the `IDistributedReaderWriterLock` interface.
 - The `PostgresDistributedSynchronizationProvider` class implements the `IDistributedLockProvider` and `IDistributedReaderWriterLockProvider` interfaces.
 
+As of version 1.3, an additional set of static APIs on `PostgresDistributedLock` allows you to leverage transaction-scoped locking with an existing `IDbTransaction` instance. Since Postgres offers no way to explicitly release transaction-scoped locks and the caller controls the transaction, these locks are acquire-only and do not need a using block. For example:
+```C#
+using (var transaction = connection.BeginTransaction())
+{
+   ...
+   // acquires the lock; it will be held until the transaction ends
+   await PostgresDistributedLock.AcquireWithTransactionAsync(key, transaction);
+   ...
+}
+```
+
 ## Implementation notes
 
 Under the hood, [Postgres advisory locks can be based on either one 64-bit integer value or a pair of 32-bit integer values](https://www.postgresql.org/docs/12/functions-admin.html#FUNCTIONS-ADVISORY-LOCKS). Because of this, rather than taking in a name the lock constructors take a `PostgresAdvisoryLockKey` object which can be constructed in several ways:

src/DistributedLock.Postgres/DistributedLock.Postgres.csproj

@@ -11,7 +11,7 @@
   </PropertyGroup>
 
   <PropertyGroup>
-    <Version>1.2.1</Version>
+    <Version>1.3.0</Version>
     <AssemblyVersion>1.0.0.0</AssemblyVersion>
     <Authors>Michael Adelson</Authors>
     <Description>Provides a distributed lock implementation based on Postgresql</Description>

src/DistributedLock.Postgres/PostgresAdvisoryLock.cs

@@ -211,15 +211,15 @@ private DatabaseCommand CreateAcquireCommand(DatabaseConnection connection, Post
         var capturedTimeoutSettings = new CapturedTimeoutSettings(statementTimeout!, lockTimeout!);
 
         return capturedTimeoutSettings;
-    }
 
-    private static async ValueTask<string?> GetCurrentSetting(string settingName, DatabaseConnection connection, CancellationToken cancellationToken)
-    {
-        using var getCurrentSettingCommand = connection.CreateCommand();
+        async ValueTask<string?> GetCurrentSetting(string settingName, DatabaseConnection connection, CancellationToken cancellationToken)
+        {
+            using var getCurrentSettingCommand = connection.CreateCommand();
 
-        getCurrentSettingCommand.SetCommandText($"SELECT current_setting('{settingName}', 'true') AS {settingName};");
+            getCurrentSettingCommand.SetCommandText($"SELECT current_setting('{settingName}', 'true') AS {settingName};");
 
-        return (string?) await getCurrentSettingCommand.ExecuteScalarAsync(cancellationToken).ConfigureAwait(false);
+            return (string?)await getCurrentSettingCommand.ExecuteScalarAsync(cancellationToken).ConfigureAwait(false);
+        }
     }
 
     private static async ValueTask<bool> ShouldDefineSavePoint(DatabaseConnection connection)
@@ -240,13 +240,13 @@ private static async ValueTask<bool> ShouldDefineSavePoint(DatabaseConnection co
         }
         catch (InvalidOperationException)
         {
-            // If we reached this point, it means the externally-owned connection has a transaction, therefore we need to define a save point.
+            // Externally-owned connection with a transaction => we need to define a save point.
             return true;
         }
 
         await connection.DisposeTransactionAsync().ConfigureAwait(false);
 
-        // If we reached this point, it means the externally-owned connection has no transaction, therefore we can't define a save point.
+        // Externally-owned connection with no transaction => no save point
         return false;
     }
 
@@ -257,8 +257,7 @@ private static async ValueTask RestoreTimeoutSettingsIfNeededAsync(CapturedTimeo
 
         using var restoreTimeoutSettingsCommand = connection.CreateCommand();
 
-        var commandText = new StringBuilder();
-
+        StringBuilder commandText = new();
         commandText.AppendLine($"SET LOCAL statement_timeout = {settings.Value.StatementTimeout};");
         commandText.AppendLine($"SET LOCAL lock_timeout = {settings.Value.LockTimeout};");
 

src/DistributedLock.Postgres/PostgresDistributedLock.Transactions.cs

@@ -127,7 +127,6 @@ internal static ValueTask AcquireWithTransactionAsyncInternal(PostgresAdvisoryLo
         async ValueTask AcquireAsync()
         {
             var connection = new PostgresDatabaseConnection(transaction);
-
             await using (connection.ConfigureAwait(false))
             {
                 await PostgresAdvisoryLock.ExclusiveLock.TryAcquireAsync(connection, key.ToString(), timeout, cancellationToken).ThrowTimeoutIfNull().ConfigureAwait(false);

src/DistributedLock.Postgres/PublicAPI.Shipped.txt

@@ -46,4 +46,8 @@ override Medallion.Threading.Postgres.PostgresAdvisoryLockKey.Equals(object? obj
 override Medallion.Threading.Postgres.PostgresAdvisoryLockKey.GetHashCode() -> int
 override Medallion.Threading.Postgres.PostgresAdvisoryLockKey.ToString() -> string!
 static Medallion.Threading.Postgres.PostgresAdvisoryLockKey.operator !=(Medallion.Threading.Postgres.PostgresAdvisoryLockKey a, Medallion.Threading.Postgres.PostgresAdvisoryLockKey b) -> bool
-static Medallion.Threading.Postgres.PostgresAdvisoryLockKey.operator ==(Medallion.Threading.Postgres.PostgresAdvisoryLockKey a, Medallion.Threading.Postgres.PostgresAdvisoryLockKey b) -> bool
+static Medallion.Threading.Postgres.PostgresAdvisoryLockKey.operator ==(Medallion.Threading.Postgres.PostgresAdvisoryLockKey a, Medallion.Threading.Postgres.PostgresAdvisoryLockKey b) -> bool
+static Medallion.Threading.Postgres.PostgresDistributedLock.AcquireWithTransaction(Medallion.Threading.Postgres.PostgresAdvisoryLockKey key, System.Data.IDbTransaction! transaction, System.TimeSpan? timeout = null, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> void
+static Medallion.Threading.Postgres.PostgresDistributedLock.AcquireWithTransactionAsync(Medallion.Threading.Postgres.PostgresAdvisoryLockKey key, System.Data.IDbTransaction! transaction, System.TimeSpan? timeout = null, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.ValueTask
+static Medallion.Threading.Postgres.PostgresDistributedLock.TryAcquireWithTransaction(Medallion.Threading.Postgres.PostgresAdvisoryLockKey key, System.Data.IDbTransaction! transaction, System.TimeSpan timeout = default(System.TimeSpan), System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> bool
+static Medallion.Threading.Postgres.PostgresDistributedLock.TryAcquireWithTransactionAsync(Medallion.Threading.Postgres.PostgresAdvisoryLockKey key, System.Data.IDbTransaction! transaction, System.TimeSpan timeout = default(System.TimeSpan), System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.ValueTask<bool>

src/DistributedLock.Postgres/PublicAPI.Unshipped.txt

@@ -1,5 +0,0 @@
-#nullable enable
-static Medallion.Threading.Postgres.PostgresDistributedLock.AcquireWithTransaction(Medallion.Threading.Postgres.PostgresAdvisoryLockKey key, System.Data.IDbTransaction! transaction, System.TimeSpan? timeout = null, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> void
-static Medallion.Threading.Postgres.PostgresDistributedLock.AcquireWithTransactionAsync(Medallion.Threading.Postgres.PostgresAdvisoryLockKey key, System.Data.IDbTransaction! transaction, System.TimeSpan? timeout = null, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.ValueTask
-static Medallion.Threading.Postgres.PostgresDistributedLock.TryAcquireWithTransaction(Medallion.Threading.Postgres.PostgresAdvisoryLockKey key, System.Data.IDbTransaction! transaction, System.TimeSpan timeout = default(System.TimeSpan), System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> bool
-static Medallion.Threading.Postgres.PostgresDistributedLock.TryAcquireWithTransactionAsync(Medallion.Threading.Postgres.PostgresAdvisoryLockKey key, System.Data.IDbTransaction! transaction, System.TimeSpan timeout = default(System.TimeSpan), System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.ValueTask<bool>

src/DistributedLock/DistributedLock.csproj

@@ -10,7 +10,7 @@
   </PropertyGroup>
 
   <PropertyGroup>
-    <Version>2.5.1</Version>
+    <Version>2.6.0</Version>
     <AssemblyVersion>2.0.0.0</AssemblyVersion>
     <Authors>Michael Adelson</Authors>
     <Description>Provides easy-to-use mutexes, reader-writer locks, and semaphores that can synchronize across processes and machines. This is an umbrella package that brings in the entire family of DistributedLock.* packages (e. g. DistributedLock.SqlServer) as references. Those packages can also be installed individually.