Add the logic on transactions to generate custom placeholder stamps (using a random token)

- Each transaction generate a random token (and on each retry).
- tr.CreateVersionStamp() can be used to get a stamp specific to this transaction

Author: KrzysFR

FoundationDB.Client/FdbTransaction.cs

@@ -90,6 +90,9 @@ public sealed partial class FdbTransaction : IFdbTransaction
 		/// <summary>CancellationToken that should be used for all async operations executing inside this transaction</summary>
 		private CancellationToken m_cancellation;
 
+		/// <summary>Random token (but constant per transaction retry) used to generate incomplete VersionStamps</summary>
+		private ulong m_versionStampToken;
+
 		#endregion
 
 		#region Constructors...
@@ -297,6 +300,68 @@ public Task<VersionStamp> GetVersionStampAsync()
 			return m_handler.GetVersionStampAsync(m_cancellation);
 		}
 
+		private ulong GenerateNewVersionStampToken()
+		{
+			// We need to generate a 80-bits stamp, and also need to mark it as 'incomplete' by forcing the highest bit to 1.
+			// Since this is supposed to be a version number with a ~1M tickrate per seconds, we will play it safe, and force the 8 highest bits to 1,
+			// meaning that we only reduce the database potential lifetime but 1/256th, before getting into trouble.
+			//
+			// By doing some empirical testing, it also seems that the last 16 bits are a transction batch order which is usually a low number.
+			// Again, we will force the 4 highest bit to 1 to reduce the change of collision with a complete version stamp.
+			//
+			// So the final token will look like:  'FF xx xx xx xx xx xx xx Fy yy', were 'x' is the random token, and 'y' will lowest 12 bits of the transaction retry count
+
+			var rnd = new Random(); //TODO: singleton? (need locking!!)
+			ulong x;
+			unsafe
+			{
+				double r = rnd.NextDouble();
+				x = *(ulong*) &r;
+			}
+			x |= 0xFF00000000000000UL;
+
+			lock (this)
+			{
+				ulong token = m_versionStampToken;
+				if (token == 0)
+				{
+					token = x;
+					m_versionStampToken = x;
+				}
+				return token;
+			}
+		}
+
+		/// <summary>Return a place-holder 80-bit VersionStamp, whose value is not yet known, but will be filled by the database at commit time.</summary>
+		/// <returns>This value can used to generate temporary keys or value, for use with the <see cref="FdbMutationType.VersionStampedKey"/> or <see cref="FdbMutationType.VersionStampedValue"/> mutations</returns>
+		/// <remarks>
+		/// The generate placeholder will use a random value that is unique per transaction (and changes at reach retry).
+		/// If the key contains the exact 80-bit byte signature of this token, the corresponding location will be tagged and replaced with the actual VersionStamp at commit time.
+		/// If another part of the key contains (by random chance) the same exact byte sequence, then an error will be triggered, and hopefully the transaction will retry with another byte sequence.
+		/// </remarks>
+		[Pure]
+		public VersionStamp CreateVersionStamp()
+		{
+			var token = m_versionStampToken;
+			if (token == 0) token = GenerateNewVersionStampToken();
+			return VersionStamp.Custom(token, (ushort) (m_context.Retries | 0xF000), incomplete: true);
+		}
+
+		/// <summary>Return a place-holder 96-bit VersionStamp with an attached user version, whose value is not yet known, but will be filled by the database at commit time.</summary>
+		/// <returns>This value can used to generate temporary keys or value, for use with the <see cref="FdbMutationType.VersionStampedKey"/> or <see cref="FdbMutationType.VersionStampedValue"/> mutations</returns>
+		/// <remarks>
+		/// The generate placeholder will use a random value that is unique per transaction (and changes at reach retry).
+		/// If the key contains the exact 80-bit byte signature of this token, the corresponding location will be tagged and replaced with the actual VersionStamp at commit time.
+		/// If another part of the key contains (by random chance) the same exact byte sequence, then an error will be triggered, and hopefully the transaction will retry with another byte sequence.
+		/// </remarks>
+		public VersionStamp CreateVersionStamp(int userVersion)
+		{
+			var token = m_versionStampToken;
+			if (token == 0) token = GenerateNewVersionStampToken();
+
+			return VersionStamp.Custom(token, (ushort) (m_context.Retries | 0xF000), userVersion, incomplete: true);
+		}
+
 		#endregion
 
 		#region Get...
@@ -785,6 +850,11 @@ private void RestoreDefaultSettings()
 			{
 				this.Timeout = m_database.DefaultTimeout;
 			}
+
+			// if we have used a random token for versionstamps, we need to clear it (and generate a new one)
+			// => this ensure that if the error was due to a collision between the token and another part of the key,
+			//    a transaction retry will hopefully use a different token that does not collide.
+			m_versionStampToken = 0;
 		}
 
 		/// <summary>Reset the transaction to its initial state.</summary>

FoundationDB.Client/Filters/FdbTransactionFilter.cs

@@ -257,6 +257,18 @@ public virtual Task<VersionStamp> GetVersionStampAsync()
 			return m_transaction.GetVersionStampAsync();
 		}
 
+		public virtual VersionStamp CreateVersionStamp()
+		{
+			ThrowIfDisposed();
+			return m_transaction.CreateVersionStamp();
+		}
+
+		public virtual VersionStamp CreateVersionStamp(int userVersion)
+		{
+			ThrowIfDisposed();
+			return m_transaction.CreateVersionStamp(userVersion);
+		}
+
 		public virtual void SetReadVersion(long version)
 		{
 			ThrowIfDisposed();

FoundationDB.Client/IFdbTransaction.cs

@@ -120,6 +120,24 @@ public interface IFdbTransaction : IFdbReadOnlyTransaction
 		/// </remarks>
 		Task<VersionStamp> GetVersionStampAsync();
 
+		/// <summary>Return a place-holder 80-bit VersionStamp, whose value is not yet known, but will be filled by the database at commit time.</summary>
+		/// <returns>This value can used to generate temporary keys or value, for use with the <see cref="FdbMutationType.VersionStampedKey"/> or <see cref="FdbMutationType.VersionStampedValue"/> mutations</returns>
+		/// <remarks>
+		/// The generate placeholder will use a random value that is unique per transaction (and changes at reach retry).
+		/// If the key contains the exact 80-bit byte signature of this token, the corresponding location will be tagged and replaced with the actual VersionStamp at commit time.
+		/// If another part of the key contains (by random chance) the same exact byte sequence, then an error will be triggered, and hopefully the transaction will retry with another byte sequence.
+		/// </remarks>
+		VersionStamp CreateVersionStamp();
+
+		/// <summary>Return a place-holder 96-bit VersionStamp with an attached user version, whose value is not yet known, but will be filled by the database at commit time.</summary>
+		/// <returns>This value can used to generate temporary keys or value, for use with the <see cref="FdbMutationType.VersionStampedKey"/> or <see cref="FdbMutationType.VersionStampedValue"/> mutations</returns>
+		/// <remarks>
+		/// The generate placeholder will use a random value that is unique per transaction (and changes at reach retry).
+		/// If the key contains the exact 80-bit byte signature of this token, the corresponding location will be tagged and replaced with the actual VersionStamp at commit time.
+		/// If another part of the key contains (by random chance) the same exact byte sequence, then an error will be triggered, and hopefully the transaction will retry with another byte sequence.
+		/// </remarks>
+		VersionStamp CreateVersionStamp(int userVersion);
+
 		/// <summary>
 		/// Watch a key for any change in the database.
 		/// </summary>

FoundationDB.Client/VersionStamp.cs

@@ -115,6 +115,19 @@ public static VersionStamp Incomplete(ushort userVersion)
 			return new VersionStamp(PLACEHOLDER_VERSION, PLACEHOLDER_ORDER, userVersion, FLAGS_IS_INCOMPLETE | FLAGS_HAS_VERSION);
 		}
 
+		[Pure, MethodImpl(MethodImplOptions.AggressiveInlining)]
+		internal static VersionStamp Custom(ulong version, ushort order, bool incomplete)
+		{
+			return new VersionStamp(version, order, NO_USER_VERSION, incomplete ? FLAGS_IS_INCOMPLETE : FLAGS_NONE);
+		}
+
+		[Pure, MethodImpl(MethodImplOptions.AggressiveInlining)]
+		internal static VersionStamp Custom(ulong version, ushort order, int userVersion, bool incomplete)
+		{
+			Contract.Between(userVersion, 0, 0xFFFF, nameof(userVersion), "Local version must fit in 16-bits.");
+			return new VersionStamp(version, order, (ushort) userVersion, incomplete ? (ushort) (FLAGS_IS_INCOMPLETE | FLAGS_HAS_VERSION) : FLAGS_HAS_VERSION);
+		}
+
 		/// <summary>Creates a 80-bit <see cref="VersionStamp"/>, obtained from the database.</summary>
 		/// <returns>Complete stamp, without user version.</returns>
 		[Pure, MethodImpl(MethodImplOptions.AggressiveInlining)]

FoundationDB.Tests/TransactionFacts.cs

@@ -37,6 +37,7 @@ namespace FoundationDB.Client.Tests
 	using System.Threading;
 	using System.Threading.Tasks;
 	using Doxense.Collections.Tuples;
+	using Doxense.Memory;
 
 	[TestFixture]
 	public class TransactionFacts : FdbTest
@@ -1993,37 +1994,140 @@ public async Task Test_Simple_Read_Transaction()
 		[Test]
 		public async Task Test_VersionStamp_Operations()
 		{
-			Fdb.Start(510);
+			// Veryify that we can set versionstamped keys inside a transaction
+
 			using (var db = await OpenTestDatabaseAsync())
 			{
-				Log("API Version: " + Fdb.ApiVersion);
-
 				var location = db.Partition.ByKey("versionstamps");
 
 				await db.ClearRangeAsync(location, this.Cancellation);
 
+				VersionStamp vsActual; // will contain the actual version stamp used by the database
+
+				Log("Inserting keys with version stamps:");
 				using (var tr = db.BeginTransaction(this.Cancellation))
 				{
-					Slice HACKHACK_Packify(VersionStamp stamp)
+					//TODO: HACKACK: until we add support to he transaction itself, we have to 'patch' the versionstamps by hand!
+					Slice HACKHACK_Stampify(Slice key)
 					{
-						var x = location.Keys.Encode(stamp);
-						x =  x.Concat(Slice.FromFixed16((short) (location.GetPrefix().Count + 1)));
-						Log(x.ToHexaString(' ') + " | " + location.Keys.Dump(x));
-						return x;
+						// find the stamp byte sequence in the key
+						var x = tr.CreateVersionStamp().ToSlice();
+						int p = key.IndexOf(x);
+						Assert.That(p, Is.GreaterThan(0), "Stamp pattern was not found in the key!");
+
+						// append the offset at the end
+						var writer = new SliceWriter(key.Count + 2);
+						writer.WriteBytes(key);
+						writer.WriteFixed16((ushort) p); //note: the offset is Little Endian!
+						var y = writer.ToSlice();
+
+						//Log(y.ToHexaString(' ') + " | " + location.Keys.Dump(y));
+						return y;
 					}
 
-					tr.SetVersionStampedKey(HACKHACK_Packify(VersionStamp.Incomplete()), Slice.FromString("Hello, World!"));
-					tr.SetVersionStampedKey(HACKHACK_Packify(VersionStamp.Incomplete(0)), Slice.FromString("Zero"));
-					tr.SetVersionStampedKey(HACKHACK_Packify(VersionStamp.Incomplete(1)), Slice.FromString("One"));
-					tr.SetVersionStampedKey(HACKHACK_Packify(VersionStamp.Incomplete(2)), Slice.FromString("Two"));
-
+					var vs = tr.CreateVersionStamp();
+					Log($"> placeholder stamp: {vs} with token '{vs.ToSlice():X}'");
+					Assert.That(vs.IsIncomplete, Is.True, "Placeholder token should be incomplete");
+					Assert.That(vs.HasUserVersion, Is.False);
+					Assert.That(vs.UserVersion, Is.Zero);
+					Assert.That(vs.TransactionVersion >> 56, Is.EqualTo(0xFF), "Highest 8 bit of Transaction Version should be set to 1");
+					Assert.That(vs.TransactionOrder >> 12, Is.EqualTo(0xF), "Hight 4 bits of Transaction Order should be set to 1");
+
+					var vs0 = tr.CreateVersionStamp(0);
+					Assert.That(vs0.IsIncomplete, Is.True, "Placeholder token should be incomplete");
+					Assert.That(vs0.TransactionVersion, Is.EqualTo(vs.TransactionVersion), "All generated stamps by one transaction should share the random token value ");
+					Assert.That(vs0.TransactionOrder, Is.EqualTo(vs.TransactionOrder), "All generated stamps by one transaction should share the random token value ");
+					Assert.That(vs0.HasUserVersion, Is.True);
+					Assert.That(vs0.UserVersion, Is.EqualTo(0));
+
+					var vs1 = tr.CreateVersionStamp(1);
+					Assert.That(vs1.IsIncomplete, Is.True, "Placeholder token should be incomplete");
+					Assert.That(vs1.TransactionVersion, Is.EqualTo(vs.TransactionVersion), "All generated stamps by one transaction should share the random token value ");
+					Assert.That(vs1.TransactionOrder, Is.EqualTo(vs.TransactionOrder), "All generated stamps by one transaction should share the random token value ");
+					Assert.That(vs1.HasUserVersion, Is.True);
+					Assert.That(vs1.UserVersion, Is.EqualTo(1));
+
+					var vs42 = tr.CreateVersionStamp(42);
+					Assert.That(vs42.IsIncomplete, Is.True, "Placeholder token should be incomplete");
+					Assert.That(vs42.TransactionVersion, Is.EqualTo(vs.TransactionVersion), "All generated stamps by one transaction should share the random token value ");
+					Assert.That(vs42.TransactionOrder, Is.EqualTo(vs.TransactionOrder), "All generated stamps by one transaction should share the random token value ");
+					Assert.That(vs42.HasUserVersion, Is.True);
+					Assert.That(vs42.UserVersion, Is.EqualTo(42));
+
+					// a single key using the 80-bit stamp
+					tr.SetVersionStampedKey(HACKHACK_Stampify(location.Keys.Encode("foo", vs, 123)), Slice.FromString("Hello, World!"));
+
+					// simulate a batch of 3 keys, using 96-bits stamps
+					tr.SetVersionStampedKey(HACKHACK_Stampify(location.Keys.Encode("bar", vs0)), Slice.FromString("Zero"));
+					tr.SetVersionStampedKey(HACKHACK_Stampify(location.Keys.Encode("bar", vs1)), Slice.FromString("One"));
+					tr.SetVersionStampedKey(HACKHACK_Stampify(location.Keys.Encode("bar", vs42)), Slice.FromString("FortyTwo"));
+
+					// need to be request BEFORE the commit
 					var vsTask = tr.GetVersionStampAsync();
 
 					await tr.CommitAsync();
 					Log(tr.GetCommittedVersion());
 
-					var vs = await vsTask;
-					Log(vs);
+					// need to be resolved AFTER the commit
+					vsActual = await vsTask;
+					Log($"> actual stamp: {vsActual} with token '{vsActual.ToSlice():X}'");
+				}
+
+				Log("Checking database content:");
+				using (var tr = db.BeginReadOnlyTransaction(this.Cancellation))
+				{
+					{
+						var foo = await tr.GetRange(location.Keys.ToKeyRange("foo")).SingleAsync();
+						Log("> Found 1 result under (foo,)");
+						Log($"- {location.ExtractKey(foo.Key):K} = {foo.Value:V}");
+						Assert.That(foo.Value.ToString(), Is.EqualTo("Hello, World!"));
+
+						var t = location.Keys.Unpack(foo.Key);
+						Assert.That(t.Get<string>(0), Is.EqualTo("foo"));
+						Assert.That(t.Get<int>(2), Is.EqualTo(123));
+
+						var vs = t.Get<VersionStamp>(1);
+						Assert.That(vs.IsIncomplete, Is.False);
+						Assert.That(vs.HasUserVersion, Is.False);
+						Assert.That(vs.UserVersion, Is.Zero);
+						Assert.That(vs.TransactionVersion, Is.EqualTo(vsActual.TransactionVersion));
+						Assert.That(vs.TransactionOrder, Is.EqualTo(vsActual.TransactionOrder));
+					}
+
+					{
+						var items = await tr.GetRange(location.Keys.ToKeyRange("bar")).ToListAsync();
+						Log($"> Found {items.Count} results under (bar,)");
+						foreach (var item in items)
+						{
+							Log($"- {location.ExtractKey(item.Key):K} = {item.Value:V}");
+						}
+
+						Assert.That(items.Count, Is.EqualTo(3), "Should have found 3 keys under 'foo'");
+
+						Assert.That(items[0].Value.ToString(), Is.EqualTo("Zero"));
+						var vs0 = location.Keys.DecodeLast<VersionStamp>(items[0].Key);
+						Assert.That(vs0.IsIncomplete, Is.False);
+						Assert.That(vs0.HasUserVersion, Is.True);
+						Assert.That(vs0.UserVersion, Is.EqualTo(0));
+						Assert.That(vs0.TransactionVersion, Is.EqualTo(vsActual.TransactionVersion));
+						Assert.That(vs0.TransactionOrder, Is.EqualTo(vsActual.TransactionOrder));
+
+						Assert.That(items[1].Value.ToString(), Is.EqualTo("One"));
+						var vs1 = location.Keys.DecodeLast<VersionStamp>(items[1].Key);
+						Assert.That(vs1.IsIncomplete, Is.False);
+						Assert.That(vs1.HasUserVersion, Is.True);
+						Assert.That(vs1.UserVersion, Is.EqualTo(1));
+						Assert.That(vs1.TransactionVersion, Is.EqualTo(vsActual.TransactionVersion));
+						Assert.That(vs1.TransactionOrder, Is.EqualTo(vsActual.TransactionOrder));
+
+						Assert.That(items[2].Value.ToString(), Is.EqualTo("FortyTwo"));
+						var vs42 = location.Keys.DecodeLast<VersionStamp>(items[2].Key);
+						Assert.That(vs42.IsIncomplete, Is.False);
+						Assert.That(vs42.HasUserVersion, Is.True);
+						Assert.That(vs42.UserVersion, Is.EqualTo(42));
+						Assert.That(vs42.TransactionVersion, Is.EqualTo(vsActual.TransactionVersion));
+						Assert.That(vs42.TransactionOrder, Is.EqualTo(vsActual.TransactionOrder));
+					}
 				}
 
 				await DumpSubspace(db, location);