Add initial support for fdb_transaction_get_versionstamp and add SetStampedKey() / SetStampedValue() mutations

Author: KrzysFR

FoundationDB.Client/Core/IFdbTransactionHandler.cs

@@ -61,6 +61,9 @@ public interface IFdbTransactionHandler : IDisposable
 		/// </remarks>
 		long GetCommittedVersion();
 
+		/// <summary>Returns the <see cref="VersionStamp"/> which was used by versionstamps operations in this transaction.</summary>
+		Task<VersionStamp> GetVersionStampAsync(CancellationToken ct);
+
 		/// <summary>Sets the snapshot read version used by a transaction. This is not needed in simple cases.</summary>
 		/// <param name="version">Read version to use in this transaction</param>
 		/// <remarks>

FoundationDB.Client/FdbMutationType.cs

@@ -91,7 +91,13 @@ public enum FdbMutationType
 		/// If ``param`` is shorter than the existing value in the database, the existing value is truncated to match the length of ``param``.
 		/// The smaller of the two values is then stored in the database.
 		/// </summary>
-		Min = 13
+		Min = 13,
+
+		//TODO: XML Comments!
+		VersionStampedKey = 14,
+
+		//TODO: XML Comments!
+		VersionStampedValue = 15,
 
 	}
 

FoundationDB.Client/FdbTransaction.cs

@@ -284,6 +284,19 @@ public void SetReadVersion(long version)
 			m_handler.SetReadVersion(version);
 		}
 
+		/// <summary>Returns the <see cref="VersionStamp"/> which was used by versionstamps operations in this transaction.</summary>
+		/// <remarks>
+		/// The Task will be ready only after the successful completion of a call to <see cref="CommitAsync"/> on this transaction.
+		/// Read-only transactions do not modify the database when committed and will result in the Task completing with an error.
+		/// Keep in mind that a transaction which reads keys and then sets them to their current values may be optimized to a read-only transaction.
+		/// </remarks>
+		public Task<VersionStamp> GetVersionStampAsync()
+		{
+			EnsureNotFailedOrDisposed();
+
+			return m_handler.GetVersionStampAsync(m_cancellation);
+		}
+
 		#endregion
 
 		#region Get...
@@ -513,6 +526,23 @@ private static void EnsureMutationTypeIsSupported(FdbMutationType mutation, int
 				return;
 			}
 
+			if (mutation == FdbMutationType.VersionStampedKey || mutation == FdbMutationType.VersionStampedValue)
+			{
+				if (selectedApiVersion < 400)
+				{
+					if (Fdb.GetMaxApiVersion() >= 400)
+					{
+						throw new FdbException(FdbError.InvalidMutationType, "Atomic mutations for VersionStamps are only supported starting from API level 400. You need to select API level 400 or more at the start of your process.");
+					}
+					else
+					{
+						throw new FdbException(FdbError.InvalidMutationType, "Atomic mutations Max and Min are only supported starting from client version 4.x. You need to update the version of the client, and select API level 400 or more at the start of your process..");
+					}
+				}
+				// ok!
+				return;
+			}
+
 			// this could be a new mutation type, or an invalid value.
 			throw new FdbException(FdbError.InvalidMutationType, "An invalid mutation type was issued. If you are attempting to call a new mutation type, you will need to update the version of this assembly, and select the latest API level.");
 		}

FoundationDB.Client/FdbTransactionExtensions.cs

@@ -425,6 +425,22 @@ public static void AtomicMin([NotNull] this IFdbTransaction trans, Slice key, Sl
 			trans.Atomic(key, value, FdbMutationType.Min);
 		}
 
+		//TODO: XML Comments!
+		public static void SetVersionStampedKey([NotNull] this IFdbTransaction trans, Slice key, Slice value)
+		{
+			Contract.NotNull(trans, nameof(trans));
+
+			trans.Atomic(key, value, FdbMutationType.VersionStampedKey);
+		}
+
+		//TODO: XML Comments!
+		public static void SetVersionStampedValue([NotNull] this IFdbTransaction trans, Slice key, Slice value)
+		{
+			Contract.NotNull(trans, nameof(trans));
+
+			trans.Atomic(key, value, FdbMutationType.VersionStampedValue);
+		}
+
 		#endregion
 
 		#region GetRange...

FoundationDB.Client/Filters/FdbTransactionFilter.cs

@@ -251,6 +251,12 @@ public virtual long GetCommittedVersion()
 			return m_transaction.GetCommittedVersion();
 		}
 
+		public virtual Task<VersionStamp> GetVersionStampAsync()
+		{
+			ThrowIfDisposed();
+			return m_transaction.GetVersionStampAsync();
+		}
+
 		public virtual void SetReadVersion(long version)
 		{
 			ThrowIfDisposed();

FoundationDB.Client/Filters/Logging/FdbLoggedTransaction.cs

@@ -312,6 +312,14 @@ public override Task OnErrorAsync(FdbError code)
 			);
 		}
 
+		public override Task<VersionStamp> GetVersionStampAsync()
+		{
+			return ExecuteAsync(
+				new FdbTransactionLog.GetVersionStampCommand(),
+				(tr, cmd) => tr.GetVersionStampAsync()
+			);
+		}
+
 		public override void Set(Slice key, Slice value)
 		{
 			Execute(

FoundationDB.Client/Filters/Logging/FdbTransactionLog.Commands.cs

@@ -832,6 +832,12 @@ public override string GetResult(KeyResolver resolver)
 
 		}
 
+		public sealed class GetVersionStampCommand : Command<VersionStamp>
+		{
+			public override Operation Op { get { return Operation.GetVersionStamp; } }
+
+		}
+
 		public sealed class GetReadVersionCommand : Command<long>
 		{
 			public override Operation Op { get { return Operation.GetReadVersion; } }

FoundationDB.Client/Filters/Logging/FdbTransactionLog.cs

@@ -552,6 +552,7 @@ public enum Operation
 			Reset,
 			OnError,
 			SetOption,
+			GetVersionStamp,
 
 			Log,
 		}

FoundationDB.Client/IFdbTransaction.cs

@@ -112,6 +112,14 @@ public interface IFdbTransaction : IFdbReadOnlyTransaction
 		/// </remarks>
 		long GetCommittedVersion();
 
+		/// <summary>Returns the <see cref="VersionStamp"/> which was used by versionstamps operations in this transaction.</summary>
+		/// <remarks>
+		/// The Task will be ready only after the successful completion of a call to <see cref="CommitAsync"/> on this transaction.
+		/// Read-only transactions do not modify the database when committed and will result in the Task completing with an error.
+		/// Keep in mind that a transaction which reads keys and then sets them to their current values may be optimized to a read-only transaction.
+		/// </remarks>
+		Task<VersionStamp> GetVersionStampAsync();
+
 		/// <summary>
 		/// Watch a key for any change in the database.
 		/// </summary>

FoundationDB.Client/Native/FdbNative.cs

@@ -51,7 +51,6 @@ internal static unsafe class FdbNative
 		private const string FDB_C_DLL = "fdb_c.dll";
 #endif
 
-
 		/// <summary>Handle on the native FDB C API library</summary>
 		private static readonly UnmanagedLibrary FdbCLib;
 
@@ -169,6 +168,9 @@ public static extern void fdb_transaction_clear_range(
 			[DllImport(FDB_C_DLL, CallingConvention = CallingConvention.Cdecl)]
 			public static extern FdbError fdb_transaction_get_committed_version(TransactionHandle transaction, out long version);
 
+			[DllImport(FDB_C_DLL, CallingConvention = CallingConvention.Cdecl)]
+			public static extern FutureHandle fdb_transaction_get_versionstamp(TransactionHandle transaction);
+
 			[DllImport(FDB_C_DLL, CallingConvention = CallingConvention.Cdecl)]
 			public static extern FutureHandle fdb_transaction_watch(TransactionHandle transaction, byte* keyName, int keyNameLength);
 
@@ -531,6 +533,16 @@ public static FutureHandle TransactionCommit(TransactionHandle transaction)
 			return future;
 		}
 
+		public static FutureHandle TransactionGetVersionStamp(TransactionHandle transaction)
+		{
+			var future = NativeMethods.fdb_transaction_get_versionstamp(transaction);
+			Contract.Assert(future != null);
+#if DEBUG_NATIVE_CALLS
+			Debug.WriteLine("fdb_transaction_get_versionstamp(0x" + transaction.Handle.ToString("x") + ") => 0x" + future.Handle.ToString("x"));
+#endif
+			return future;
+		}
+
 		public static FutureHandle TransactionWatch(TransactionHandle transaction, Slice key)
 		{
 			if (key.IsNullOrEmpty) throw new ArgumentException("Key cannot be null or empty", "key");
@@ -822,6 +834,27 @@ public static FdbError FutureGetStringArray(FutureHandle future, out string[] re
 			return err;
 		}
 
+		public static FdbError FutureGetVersionStamp(FutureHandle future, out VersionStamp stamp)
+		{
+			byte* ptr;
+			int keyLength;
+			var err = NativeMethods.fdb_future_get_key(future, out ptr, out keyLength);
+#if DEBUG_NATIVE_CALLS
+			Debug.WriteLine("fdb_future_get_key(0x" + future.Handle.ToString("x") + ") => err=" + err + ", keyLength=" + keyLength);
+#endif
+
+			if (keyLength != 10 || ptr == null)
+			{
+				stamp = default;
+				return err;
+			}
+			//note: we assume that this is a complete stamp read from the database.
+			//BUGBUG: if the code serialize an incomplete stamp into a tuple, and unpacks it (logging?) it MAY be changed into a complete one!
+			// => we could check for the 'all FF' signature, but this only works for default incomplete tokens, not custom incomplete tokens !
+			VersionStamp.ReadUnsafe(ptr, 10, /*FLAGS_NONE*/0, out stamp);
+			return err;
+		}
+
 		public static void TransactionSet(TransactionHandle transaction, Slice key, Slice value)
 		{
 			fixed (byte* pKey = key.Array)