5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | -------------------------------------------------------------------------------- /IdGenTests/ConfigTests.cs: -------------------------------------------------------------------------------- 1 | using IdGen; 2 | using IdGen.Configuration; 3 | using Microsoft.VisualStudio.TestTools.UnitTesting; 4 | using System; 5 | using System.Collections.Generic; 6 | 7 | namespace IdGenTests; 8 | 9 | [TestClass] 10 | public class ConfigTests 11 | { 12 | [TestMethod] 13 | public void IdGenerator_GetFromConfig_CreatesCorrectGenerator1() 14 | { 15 | var target = AppConfigFactory.GetFromConfig("foo"); 16 | 17 | Assert.AreEqual(123, target.Id); 18 | Assert.AreEqual(new DateTime(2016, 1, 2, 12, 34, 56, DateTimeKind.Utc), target.Options.TimeSource.Epoch); 19 | Assert.AreEqual(39, target.Options.IdStructure.TimestampBits); 20 | Assert.AreEqual(11, target.Options.IdStructure.GeneratorIdBits); 21 | Assert.AreEqual(13, target.Options.IdStructure.SequenceBits); 22 | Assert.AreEqual(TimeSpan.FromMilliseconds(50), target.Options.TimeSource.TickDuration); 23 | Assert.AreEqual(SequenceOverflowStrategy.Throw, target.Options.SequenceOverflowStrategy); 24 | } 25 | 26 | [TestMethod] 27 | public void IdGenerator_GetFromConfig_CreatesCorrectGenerator2() 28 | { 29 | var target = AppConfigFactory.GetFromConfig("baz"); 30 | 31 | Assert.AreEqual(2047, target.Id); 32 | Assert.AreEqual(new DateTime(2016, 2, 29, 0, 0, 0, DateTimeKind.Utc), target.Options.TimeSource.Epoch); 33 | Assert.AreEqual(21, target.Options.IdStructure.TimestampBits); 34 | Assert.AreEqual(21, target.Options.IdStructure.GeneratorIdBits); 35 | Assert.AreEqual(21, target.Options.IdStructure.SequenceBits); 36 | Assert.AreEqual(TimeSpan.FromTicks(7), target.Options.TimeSource.TickDuration); 37 | Assert.AreEqual(SequenceOverflowStrategy.SpinWait, target.Options.SequenceOverflowStrategy); 38 | } 39 | 40 | [TestMethod] 41 | [ExpectedException(typeof(KeyNotFoundException))] 42 | public void IdGenerator_GetFromConfig_IsCaseSensitive() => AppConfigFactory.GetFromConfig("Foo"); 43 | 44 | [TestMethod] 45 | [ExpectedException(typeof(KeyNotFoundException))] 46 | public void IdGenerator_GetFromConfig_ThrowsOnNonExisting() => AppConfigFactory.GetFromConfig("xxx"); 47 | 48 | 49 | [TestMethod] 50 | [ExpectedException(typeof(InvalidOperationException))] 51 | public void IdGenerator_GetFromConfig_ThrowsOnInvalidIdStructure() => AppConfigFactory.GetFromConfig("e1"); 52 | 53 | [TestMethod] 54 | [ExpectedException(typeof(FormatException))] 55 | public void IdGenerator_GetFromConfig_ThrowsOnInvalidEpoch() => AppConfigFactory.GetFromConfig("e2"); 56 | 57 | [TestMethod] 58 | public void IdGenerator_GetFromConfig_ReturnsSameInstanceForSameName() 59 | { 60 | var target1 = AppConfigFactory.GetFromConfig("foo"); 61 | var target2 = AppConfigFactory.GetFromConfig("foo"); 62 | 63 | Assert.IsTrue(ReferenceEquals(target1, target2)); 64 | } 65 | 66 | [TestMethod] 67 | public void IdGenerator_GetFromConfig_ParsesEpochCorrectly() 68 | { 69 | Assert.AreEqual(new DateTime(2016, 1, 2, 12, 34, 56, DateTimeKind.Utc), AppConfigFactory.GetFromConfig("foo").Options.TimeSource.Epoch); 70 | Assert.AreEqual(new DateTime(2016, 2, 1, 1, 23, 45, DateTimeKind.Utc), AppConfigFactory.GetFromConfig("bar").Options.TimeSource.Epoch); 71 | Assert.AreEqual(new DateTime(2016, 2, 29, 0, 0, 0, DateTimeKind.Utc), AppConfigFactory.GetFromConfig("baz").Options.TimeSource.Epoch); 72 | Assert.AreEqual(IdGeneratorOptions.DefaultEpoch, AppConfigFactory.GetFromConfig("nt").Options.TimeSource.Epoch); 73 | } 74 | 75 | [TestMethod] 76 | public void IdGenerator_GetFromConfig_ParsesTickDurationCorrectly() 77 | { 78 | Assert.AreEqual(TimeSpan.FromMilliseconds(50), AppConfigFactory.GetFromConfig("foo").Options.TimeSource.TickDuration); 79 | Assert.AreEqual(new TimeSpan(1, 2, 3), AppConfigFactory.GetFromConfig("bar").Options.TimeSource.TickDuration); 80 | Assert.AreEqual(TimeSpan.FromTicks(7), AppConfigFactory.GetFromConfig("baz").Options.TimeSource.TickDuration); 81 | 82 | // Make sure the default tickduration is 1 ms 83 | Assert.AreEqual(TimeSpan.FromMilliseconds(1), AppConfigFactory.GetFromConfig("nt").Options.TimeSource.TickDuration); 84 | } 85 | 86 | [TestMethod] 87 | public void IdGeneratorElement_Property_Setters() 88 | { 89 | // We create an IdGeneratorElement from code and compare it to an IdGeneratorElement from config. 90 | var target = new IdGeneratorElement() 91 | { 92 | Name = "newfoo", 93 | Id = 123, 94 | Epoch = new DateTime(2016, 1, 2, 12, 34, 56, DateTimeKind.Utc), 95 | TimestampBits = 39, 96 | GeneratorIdBits = 11, 97 | SequenceBits = 13, 98 | TickDuration = TimeSpan.FromMilliseconds(50), 99 | SequenceOverflowStrategy = SequenceOverflowStrategy.Throw 100 | }; 101 | var expected = AppConfigFactory.GetFromConfig("foo"); 102 | 103 | Assert.AreEqual(expected.Id, target.Id); 104 | Assert.AreEqual(expected.Options.TimeSource.Epoch, target.Epoch); 105 | Assert.AreEqual(expected.Options.IdStructure.TimestampBits, target.TimestampBits); 106 | Assert.AreEqual(expected.Options.IdStructure.GeneratorIdBits, target.GeneratorIdBits); 107 | Assert.AreEqual(expected.Options.IdStructure.SequenceBits, target.SequenceBits); 108 | Assert.AreEqual(expected.Options.TimeSource.TickDuration, target.TickDuration); 109 | Assert.AreEqual(expected.Options.SequenceOverflowStrategy, target.SequenceOverflowStrategy); 110 | } 111 | } -------------------------------------------------------------------------------- /IdGenTests/DependencyInjectionTests.cs: -------------------------------------------------------------------------------- 1 | using IdGen; 2 | using IdGen.DependencyInjection; 3 | using IdGenTests.Mocks; 4 | using Microsoft.Extensions.DependencyInjection; 5 | using Microsoft.VisualStudio.TestTools.UnitTesting; 6 | using System; 7 | 8 | namespace IdGenTests; 9 | 10 | [TestClass] 11 | public class DependencyInjectionTests 12 | { 13 | [TestMethod] 14 | public void DependencyInjection_Resolves_IdGenerator() 15 | { 16 | var serviceProvider = new ServiceCollection() 17 | .AddIdGen(123) 18 | .BuildServiceProvider(); 19 | 20 | var idgenerator = serviceProvider.GetRequiredService(); 21 | Assert.IsNotNull(idgenerator); 22 | 23 | var id = idgenerator.CreateId(); 24 | var target = idgenerator.FromId(id); 25 | 26 | Assert.AreEqual(123, target.GeneratorId); 27 | } 28 | 29 | [TestMethod] 30 | public void DependencyInjection_Resolves_IIdGenerator() 31 | { 32 | var serviceProvider = new ServiceCollection() 33 | .AddIdGen(456) 34 | .BuildServiceProvider(); 35 | 36 | var idgenerator = serviceProvider.GetRequiredService>(); 37 | Assert.IsNotNull(idgenerator); 38 | } 39 | 40 | [TestMethod] 41 | public void DependencyInjection_Resolves_Singleton() 42 | { 43 | var serviceProvider = new ServiceCollection() 44 | .AddIdGen(789) 45 | .AddIdGen(654) // This should be a no-op 46 | .BuildServiceProvider(); 47 | 48 | var idgen1 = serviceProvider.GetRequiredService>(); 49 | var idgen2 = serviceProvider.GetRequiredService(); 50 | 51 | Assert.ReferenceEquals(idgen1, idgen2); 52 | Assert.AreEqual(789, idgen2.FromId(idgen1.CreateId()).GeneratorId); 53 | Assert.AreEqual(789, idgen2.FromId(idgen2.CreateId()).GeneratorId); 54 | } 55 | 56 | [TestMethod] 57 | public void DependencyInjection_AppliesOptions() 58 | { 59 | var epoch = new DateTimeOffset(2022, 5, 18, 0, 0, 0, TimeSpan.Zero); 60 | var idstruct = new IdStructure(39, 11, 13); 61 | var ts = new MockTimeSource(69, TimeSpan.FromMinutes(1), epoch); 62 | 63 | var serviceProvider = new ServiceCollection() 64 | .AddIdGen(420, () => new IdGeneratorOptions(idstruct, ts)) 65 | .BuildServiceProvider(); 66 | 67 | var idgen = serviceProvider.GetRequiredService(); 68 | var id = idgen.FromId(idgen.CreateId()); 69 | 70 | Assert.AreEqual(0, id.SequenceNumber); 71 | Assert.AreEqual(420, id.GeneratorId); 72 | Assert.AreEqual(epoch.AddMinutes(69), id.DateTimeOffset); 73 | } 74 | } 75 | -------------------------------------------------------------------------------- /IdGenTests/IDTests.cs: -------------------------------------------------------------------------------- 1 | using IdGen; 2 | using Microsoft.VisualStudio.TestTools.UnitTesting; 3 | 4 | namespace IdGenTests; 5 | 6 | [TestClass] 7 | public class IDTests 8 | { 9 | [TestMethod] 10 | public void ID_DoesNotEqual_RandomObject() 11 | { 12 | var g = new IdGenerator(0); 13 | var i = g.FromId(0); 14 | Assert.IsFalse(i.Equals(new object())); 15 | Assert.IsTrue(i.Equals((object)g.FromId(0))); 16 | Assert.IsTrue(i != g.FromId(1)); 17 | Assert.IsTrue(i == g.FromId(0)); 18 | Assert.AreEqual(i.GetHashCode(), g.FromId(0).GetHashCode()); 19 | } 20 | 21 | [TestMethod] 22 | public void ID_Equals_OtherId() 23 | { 24 | var g = new IdGenerator(0); 25 | var i = g.FromId(1234567890); 26 | Assert.IsTrue(i.Equals(g.FromId(1234567890))); 27 | Assert.IsTrue(i.Equals((object)g.FromId(1234567890))); 28 | Assert.IsTrue(i != g.FromId(0)); 29 | Assert.IsTrue(i == g.FromId(1234567890)); 30 | Assert.AreEqual(i.GetHashCode(), g.FromId(1234567890).GetHashCode()); 31 | } 32 | 33 | [TestMethod] 34 | public void ID_FromZeroInt_HasCorrectValue() 35 | { 36 | var g = new IdGenerator(0); 37 | var i = g.FromId(0); 38 | 39 | Assert.AreEqual(0, i.SequenceNumber); 40 | Assert.AreEqual(0, i.GeneratorId); 41 | Assert.AreEqual(g.Options.TimeSource.Epoch, i.DateTimeOffset); 42 | } 43 | 44 | 45 | [TestMethod] 46 | public void ID_FromOneInt_HasCorrectValue() 47 | { 48 | var g = new IdGenerator(0); 49 | var i = g.FromId(1); 50 | 51 | Assert.AreEqual(1, i.SequenceNumber); 52 | Assert.AreEqual(0, i.GeneratorId); 53 | Assert.AreEqual(g.Options.TimeSource.Epoch, i.DateTimeOffset); 54 | } 55 | 56 | } 57 | -------------------------------------------------------------------------------- /IdGenTests/IdGenTests.csproj: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | net48;net9 5 | enable 6 | latest 7 | false 8 | Debug;Release 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | all 18 | runtime; build; native; contentfiles; analyzers; buildtransitive 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 | 30 | 31 | testhost.dll.config 32 | PreserveNewest 33 | 34 | 35 | -------------------------------------------------------------------------------- /IdGenTests/IdGeneratorTests.cs: -------------------------------------------------------------------------------- 1 | using IdGen; 2 | using IdGenTests.Mocks; 3 | using Microsoft.VisualStudio.TestTools.UnitTesting; 4 | using System; 5 | using System.Collections; 6 | using System.Linq; 7 | 8 | namespace IdGenTests; 9 | 10 | [TestClass] 11 | public class IdGeneratorTests 12 | { 13 | [TestMethod] 14 | public void Sequence_ShouldIncrease_EveryInvocation() 15 | { 16 | // We setup our generator so that the time is 0, generator id 0 and we're only left with the sequence 17 | // increasing each invocation of CreateId(); 18 | var ts = new MockTimeSource(0); 19 | var g = new IdGenerator(0, new IdGeneratorOptions(timeSource: ts)); 20 | 21 | Assert.AreEqual(0, g.CreateId()); 22 | Assert.AreEqual(1, g.CreateId()); 23 | Assert.AreEqual(2, g.CreateId()); 24 | } 25 | 26 | [TestMethod] 27 | public void Sequence_ShouldReset_EveryNewTick() 28 | { 29 | // We setup our generator so that the time is 0, generator id 0 and we're only left with the sequence 30 | // increasing each invocation of CreateId(); 31 | var ts = new MockTimeSource(0); 32 | var g = new IdGenerator(0, new IdGeneratorOptions(timeSource: ts)); 33 | 34 | Assert.AreEqual(0, g.CreateId()); 35 | Assert.AreEqual(1, g.CreateId()); 36 | ts.NextTick(); 37 | // Since the timestamp has increased, we should now have a much higher value (since the timestamp is 38 | // shifted left a number of bits (specifically GeneratorIdBits + SequenceBits) 39 | Assert.AreEqual((1 << (g.Options.IdStructure.GeneratorIdBits + g.Options.IdStructure.SequenceBits)) + 0, g.CreateId()); 40 | Assert.AreEqual((1 << (g.Options.IdStructure.GeneratorIdBits + g.Options.IdStructure.SequenceBits)) + 1, g.CreateId()); 41 | } 42 | 43 | [TestMethod] 44 | public void GeneratorId_ShouldBePresent_InID1() 45 | { 46 | // We setup our generator so that the time is 0 and generator id equals 1023 so that all 10 bits are set 47 | // for the generator. 48 | var ts = new MockTimeSource(0); 49 | var g = new IdGenerator(1023, new IdGeneratorOptions(timeSource: ts)); 50 | 51 | // Make sure all expected bits are set 52 | Assert.AreEqual(((1 << g.Options.IdStructure.GeneratorIdBits) - 1) << g.Options.IdStructure.SequenceBits, g.CreateId()); 53 | } 54 | 55 | [TestMethod] 56 | public void GeneratorId_ShouldBePresent_InID2() 57 | { 58 | // We setup our generator so that the time is 0 and generator id equals 4095 so that all 12 bits are set 59 | // for the generator. 60 | var ts = new MockTimeSource(); 61 | var s = new IdStructure(40, 12, 11); // We use a custom IdStructure with 12 bits for the generator this time 62 | var g = new IdGenerator(4095, new IdGeneratorOptions(s, ts)); 63 | 64 | // Make sure all expected bits are set 65 | Assert.AreEqual(-1 & ((1 << 12) - 1), g.Id); 66 | Assert.AreEqual(((1 << 12) - 1) << 11, g.CreateId()); 67 | } 68 | 69 | [TestMethod] 70 | public void GeneratorId_ShouldBeMasked_WhenReadFromProperty() 71 | { 72 | // We setup our generator so that the time is 0 and generator id equals 1023 so that all 10 bits are set 73 | // for the generator. 74 | var ts = new MockTimeSource(); 75 | var g = new IdGenerator(1023, new IdGeneratorOptions(timeSource: ts)); 76 | 77 | // Make sure all expected bits are set 78 | Assert.AreEqual((1 << g.Options.IdStructure.GeneratorIdBits) - 1, g.Id); 79 | } 80 | 81 | [TestMethod] 82 | public void Constructor_DoesNotThrow_OnMaxGeneratorId() 83 | { 84 | var structure = new IdStructure(41, 10, 12); 85 | // 1023 is the max generator id for 10 bits. 86 | var maxgeneratorid = 1023; 87 | _ = new IdGenerator(maxgeneratorid, new IdGeneratorOptions(structure)); 88 | } 89 | 90 | [TestMethod] 91 | public void Constructor_DoesNotThrow_OnGeneratorId_0() 92 | => _ = new IdGenerator(0, new IdGeneratorOptions(new IdStructure(41, 10, 12))); 93 | 94 | [TestMethod] 95 | [ExpectedException(typeof(ArgumentNullException))] 96 | public void Constructor_Throws_OnNull_Options() 97 | => new IdGenerator(1024, null!); 98 | 99 | [TestMethod] 100 | [ExpectedException(typeof(ArgumentOutOfRangeException))] 101 | public void Constructor_Throws_OnInvalidGeneratorId_Positive_MaxPlusOne() 102 | { 103 | var structure = new IdStructure(41, 10, 12); 104 | // 1023 is the max generator id for 10 bits. 105 | var maxgeneratorid = 1023; 106 | var maxPlusOne = maxgeneratorid + 1; 107 | _ = new IdGenerator(maxPlusOne, new IdGeneratorOptions(structure)); 108 | } 109 | 110 | [TestMethod] 111 | [ExpectedException(typeof(ArgumentOutOfRangeException))] 112 | public void Constructor_Throws_OnInvalidGeneratorId_Negative() 113 | => new IdGenerator(-1); 114 | 115 | [TestMethod] 116 | public void Constructor_DoesNotThrow_OnMaxValidatorId() 117 | => _ = new IdGenerator(int.MaxValue, new IdGeneratorOptions { IdStructure = new IdStructure(16, 31, 16) }); 118 | 119 | [TestMethod] 120 | public void Constructor_UsesCorrectId() 121 | => Assert.AreEqual(42, new IdGenerator(42).Id); 122 | 123 | [TestMethod] 124 | [ExpectedException(typeof(SequenceOverflowException))] 125 | public void CreateId_Throws_OnSequenceOverflow() 126 | { 127 | var ts = new MockTimeSource(); 128 | var s = new IdStructure(41, 20, 2); 129 | var g = new IdGenerator(0, new IdGeneratorOptions(idStructure: s, timeSource: ts)); 130 | 131 | // We have a 2-bit sequence; generating 4 id's shouldn't be a problem 132 | for (var i = 0; i < 4; i++) 133 | { 134 | Assert.AreEqual(i, g.CreateId()); 135 | } 136 | 137 | // However, if we invoke once more we should get an SequenceOverflowException 138 | g.CreateId(); 139 | } 140 | 141 | [TestMethod] 142 | public void TryCreateId_Returns_False_OnSequenceOverflow() 143 | { 144 | var ts = new MockTimeSource(); 145 | var s = new IdStructure(41, 20, 2); 146 | var g = new IdGenerator(0, new IdGeneratorOptions(idStructure: s, timeSource: ts)); 147 | 148 | // We have a 2-bit sequence; generating 4 id's shouldn't be a problem 149 | for (var i = 0; i < 4; i++) 150 | { 151 | Assert.IsTrue(g.TryCreateId(out var _)); 152 | } 153 | 154 | // However, if we invoke once more we should get an SequenceOverflowException 155 | // which should be indicated by the false return value 156 | Assert.IsFalse(g.TryCreateId(out var _)); 157 | } 158 | 159 | [TestMethod] 160 | public void Enumerable_ShoudReturn_Ids() 161 | { 162 | var g = new IdGenerator(0, IdGeneratorOptions.Default); 163 | var ids = g.Take(1000).ToArray(); 164 | 165 | Assert.AreEqual(1000, ids.Distinct().Count()); 166 | } 167 | 168 | [TestMethod] 169 | public void Enumerable_ShoudReturn_Ids_InterfaceExplicit() 170 | { 171 | var g = (IEnumerable)new IdGenerator(0, IdGeneratorOptions.Default); 172 | var ids = g.OfType().Take(1000).ToArray(); 173 | Assert.AreEqual(1000, ids.Distinct().Count()); 174 | } 175 | 176 | [TestMethod] 177 | [ExpectedException(typeof(InvalidSystemClockException))] 178 | public void CreateId_Throws_OnClockBackwards() 179 | { 180 | var ts = new MockTimeSource(100); 181 | var g = new IdGenerator(0, new IdGeneratorOptions(timeSource: ts)); 182 | 183 | g.CreateId(); 184 | ts.PreviousTick(); // Set clock back 1 'tick', this results in the time going from "100" to "99" 185 | g.CreateId(); 186 | } 187 | 188 | [TestMethod] 189 | public void TryCreateId_Returns_False_OnClockBackwards() 190 | { 191 | var ts = new MockTimeSource(100); 192 | var g = new IdGenerator(0, new IdGeneratorOptions(timeSource: ts)); 193 | 194 | Assert.IsTrue(g.TryCreateId(out var _)); 195 | ts.PreviousTick(); // Set clock back 1 'tick', this results in the time going from "100" to "99" 196 | Assert.IsFalse(g.TryCreateId(out var _)); 197 | } 198 | 199 | [TestMethod] 200 | [ExpectedException(typeof(InvalidSystemClockException))] 201 | public void CreateId_Throws_OnTimestampWraparound() 202 | { 203 | var ts = new MockTimeSource(long.MaxValue); // Set clock to 1 'tick' before wraparound 204 | var g = new IdGenerator(0, new IdGeneratorOptions(timeSource: ts)); 205 | 206 | Assert.IsTrue(g.CreateId() > 0); // Should succeed; 207 | ts.NextTick(); 208 | g.CreateId(); // Should fail 209 | } 210 | 211 | [TestMethod] 212 | public void TryCreateId_Returns_False_OnTimestampWraparound() 213 | { 214 | var ts = new MockTimeSource(long.MaxValue); // Set clock to 1 'tick' before wraparound 215 | var g = new IdGenerator(0, new IdGeneratorOptions(timeSource: ts)); 216 | 217 | Assert.IsTrue(g.TryCreateId(out var _)); // Should succeed; 218 | ts.NextTick(); 219 | Assert.IsFalse(g.TryCreateId(out var _)); // Should fail 220 | } 221 | 222 | [TestMethod] 223 | public void FromId_Returns_CorrectValue() 224 | { 225 | var s = new IdStructure(42, 8, 13); 226 | var epoch = new DateTimeOffset(2018, 7, 31, 14, 48, 2, TimeSpan.FromHours(2)); // Just some "random" epoch... 227 | var ts = new MockTimeSource(5, TimeSpan.FromSeconds(7), epoch); // Set clock at 5 ticks; each tick being 7 seconds... 228 | // Set generator ID to 234 229 | var g = new IdGenerator(234, new IdGeneratorOptions(s, ts)); 230 | 231 | // Generate a bunch of id's 232 | long id = 0; 233 | for (var i = 0; i < 35; i++) 234 | { 235 | id = g.CreateId(); 236 | } 237 | 238 | var target = g.FromId(id); 239 | 240 | 241 | Assert.AreEqual(34, target.SequenceNumber); // We generated 35 id's in the same tick, so sequence should be at 34. 242 | Assert.AreEqual(234, target.GeneratorId); // With generator id 234 243 | Assert.AreEqual(epoch.Add(TimeSpan.FromSeconds(5 * 7)), target.DateTimeOffset); // And the clock was at 5 ticks, with each tick being 244 | // 7 seconds (so 35 seconds from epoch) 245 | // And epoch was 2018-7-31 14:48:02 +02:00... 246 | } 247 | 248 | [TestMethod] 249 | public void CreateId_Waits_OnSequenceOverflow() 250 | { 251 | // Use timesource that generates a new tick every 10 calls to GetTicks() 252 | var ts = new MockAutoIncrementingIntervalTimeSource(10); 253 | var s = new IdStructure(61, 0, 2); 254 | var g = new IdGenerator(0, new IdGeneratorOptions(idStructure: s, timeSource: ts, sequenceOverflowStrategy: SequenceOverflowStrategy.SpinWait)); 255 | 256 | // We have a 2-bit sequence; generating 4 id's in a single time slot - wait for other then 257 | Assert.AreEqual(0, g.CreateId()); 258 | Assert.AreEqual(1, g.CreateId()); 259 | Assert.AreEqual(2, g.CreateId()); 260 | Assert.AreEqual(3, g.CreateId()); 261 | Assert.AreEqual(4, g.CreateId()); // This should trigger a spinwait and return the next ID 262 | Assert.AreEqual(5, g.CreateId()); 263 | } 264 | } -------------------------------------------------------------------------------- /IdGenTests/IdStructureTests.cs: -------------------------------------------------------------------------------- 1 | using IdGen; 2 | using IdGenTests.Mocks; 3 | using Microsoft.VisualStudio.TestTools.UnitTesting; 4 | using System; 5 | 6 | namespace IdGenTests; 7 | 8 | [TestClass] 9 | public class IdStructureTests 10 | { 11 | [TestMethod] 12 | public void DefaultIdStructure_Matches_Expectations() 13 | { 14 | var s = IdStructure.Default; 15 | 16 | Assert.AreEqual(41, s.TimestampBits); 17 | Assert.AreEqual(10, s.GeneratorIdBits); 18 | Assert.AreEqual(12, s.SequenceBits); 19 | 20 | // We should be able to generate a total of 63 bits worth of Id's 21 | Assert.AreEqual(long.MaxValue, (s.MaxGenerators * s.MaxIntervals * s.MaxSequenceIds) - 1); 22 | } 23 | 24 | [TestMethod] 25 | [ExpectedException(typeof(InvalidOperationException))] 26 | public void Constructor_Throws_OnIdStructureNotExactly63Bits() => new IdStructure(41, 10, 11); 27 | 28 | [TestMethod] 29 | [ExpectedException(typeof(ArgumentOutOfRangeException))] 30 | public void Constructor_Throws_OnGeneratorIdMoreThan31Bits() => new IdStructure(21, 32, 10); 31 | 32 | [TestMethod] 33 | [ExpectedException(typeof(ArgumentOutOfRangeException))] 34 | public void Constructor_Throws_OnSequenceMoreThan31Bits() => new IdStructure(21, 10, 32); 35 | 36 | [TestMethod] 37 | public void IdStructure_CalculatesWraparoundInterval_Correctly() 38 | { 39 | var mc_ms = new MockTimeSource(); 40 | 41 | // 40 bits of Timestamp should give us about 34 years worth of Id's 42 | Assert.AreEqual(34, (int)(new IdStructure(40, 11, 12).WraparoundInterval(mc_ms).TotalDays / 365.25)); 43 | // 41 bits of Timestamp should give us about 69 years worth of Id's 44 | Assert.AreEqual(69, (int)(new IdStructure(41, 11, 11).WraparoundInterval(mc_ms).TotalDays / 365.25)); 45 | // 42 bits of Timestamp should give us about 139 years worth of Id's 46 | Assert.AreEqual(139, (int)(new IdStructure(42, 11, 10).WraparoundInterval(mc_ms).TotalDays / 365.25)); 47 | 48 | var mc_s = new MockTimeSource(TimeSpan.FromSeconds(0.1)); 49 | 50 | // 40 bits of Timestamp should give us about 3484 years worth of Id's 51 | Assert.AreEqual(3484, (int)(new IdStructure(40, 11, 12).WraparoundInterval(mc_s).TotalDays / 365.25)); 52 | // 41 bits of Timestamp should give us about 6968 years worth of Id's 53 | Assert.AreEqual(6968, (int)(new IdStructure(41, 11, 11).WraparoundInterval(mc_s).TotalDays / 365.25)); 54 | // 42 bits of Timestamp should give us about 13936 years worth of Id's 55 | Assert.AreEqual(13936, (int)(new IdStructure(42, 11, 10).WraparoundInterval(mc_s).TotalDays / 365.25)); 56 | 57 | var mc_d = new MockTimeSource(TimeSpan.FromDays(1)); 58 | 59 | // 21 bits of Timestamp should give us about 5741 years worth of Id's 60 | Assert.AreEqual(5741, (int)(new IdStructure(21, 11, 31).WraparoundInterval(mc_d).TotalDays / 365.25)); 61 | // 22 bits of Timestamp should give us about 11483 years worth of Id's 62 | Assert.AreEqual(11483, (int)(new IdStructure(22, 11, 30).WraparoundInterval(mc_d).TotalDays / 365.25)); 63 | // 23 bits of Timestamp should give us about 22966 years worth of Id's 64 | Assert.AreEqual(22966, (int)(new IdStructure(23, 11, 29).WraparoundInterval(mc_d).TotalDays / 365.25)); 65 | } 66 | 67 | [TestMethod] 68 | public void IdStructure_Calculates_WraparoundDate_Correctly() 69 | { 70 | var s = IdStructure.Default; 71 | var mc = new MockTimeSource(TimeSpan.FromMilliseconds(1)); 72 | var d = s.WraparoundDate(new DateTime(1970, 1, 1, 0, 0, 0, DateTimeKind.Utc), mc); 73 | 74 | 75 | #if NETCOREAPP3_0_OR_GREATER 76 | Assert.AreEqual(new DateTime(643346200555519999, DateTimeKind.Utc), d); 77 | #else //https://learn.microsoft.com/en-us/dotnet/core/compatibility/3.0#floating-point-formatting-and-parsing-behavior-changed 78 | Assert.AreEqual(new DateTime(643346200555520000, DateTimeKind.Utc), d); 79 | #endif 80 | } 81 | 82 | [TestMethod] 83 | [ExpectedException(typeof(ArgumentNullException))] 84 | public void WraparoundDate_ThrowsOnNullTimeSource() => IdStructure.Default.WraparoundDate(IdGeneratorOptions.DefaultEpoch, null!); 85 | 86 | [TestMethod] 87 | [ExpectedException(typeof(ArgumentNullException))] 88 | public void WraparoundInterval_ThrowsOnNullTimeSource() => IdStructure.Default.WraparoundInterval(null!); 89 | } 90 | -------------------------------------------------------------------------------- /IdGenTests/Mocks/MockAutoIncrementingIntervalTimeSource.cs: -------------------------------------------------------------------------------- 1 | using System; 2 | using System.Threading; 3 | 4 | namespace IdGenTests.Mocks; 5 | 6 | public class MockAutoIncrementingIntervalTimeSource(int incrementEvery, long? current = null, TimeSpan? tickDuration = null, DateTimeOffset? epoch = null) 7 | : MockTimeSource(current ?? 0, tickDuration ?? TimeSpan.FromMilliseconds(1), epoch ?? DateTimeOffset.MinValue) 8 | { 9 | private int _count = 0; 10 | 11 | public override long GetTicks() 12 | { 13 | if (_count == incrementEvery) 14 | { 15 | NextTick(); 16 | _count = 0; 17 | } 18 | Interlocked.Increment(ref _count); 19 | 20 | return base.GetTicks(); 21 | } 22 | } 23 | -------------------------------------------------------------------------------- /IdGenTests/Mocks/MockTimeSource.cs: -------------------------------------------------------------------------------- 1 | using IdGen; 2 | using System; 3 | using System.Threading; 4 | 5 | namespace IdGenTests.Mocks; 6 | 7 | public class MockTimeSource(long current, TimeSpan tickDuration, DateTimeOffset epoch) : ITimeSource 8 | { 9 | public MockTimeSource() 10 | : this(0) { } 11 | 12 | public DateTimeOffset Epoch { get; private set; } = epoch; 13 | 14 | public TimeSpan TickDuration { get; } = tickDuration; 15 | 16 | public MockTimeSource(long current) 17 | : this(current, TimeSpan.FromMilliseconds(1), DateTimeOffset.MinValue) { } 18 | 19 | public MockTimeSource(TimeSpan tickDuration) 20 | : this(0, tickDuration, DateTimeOffset.MinValue) { } 21 | 22 | public virtual long GetTicks() => current; 23 | 24 | public void NextTick() => Interlocked.Increment(ref current); 25 | 26 | public void PreviousTick() => Interlocked.Decrement(ref current); 27 | } 28 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | The MIT License (MIT) 2 | 3 | Copyright (c) 2015 Rob Janssen 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | 23 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # ![Logo](https://raw.githubusercontent.com/RobThree/IdGen/master/logo.png) IdGen 2 | 3 | ![Build Status](https://img.shields.io/github/actions/workflow/status/RobThree/IdGen/test.yml?branch=master&style=flat-square) [![Nuget version](https://img.shields.io/nuget/v/IdGen.svg?style=flat-square)](https://www.nuget.org/packages/IdGen/) 4 | 5 | Twitter Snowflake-alike ID generator for .Net. Available as [Nuget package](https://www.nuget.org/packages/IdGen) 6 | 7 | ## Why 8 | 9 | In certain situations you need a low-latency, distributed, uncoordinated, (roughly) time ordered, compact and highly available Id generation system. This project was inspired by [Twitter's Snowflake](https://github.com/twitter/snowflake) project which has been retired. Note that this project was inspired by Snowflake but is not an *exact* implementation. This library provides a basis for Id generation; it does **not** provide a service for handing out these Id's nor does it provide generator-id ('worker-id') coordination. 10 | 11 | ## How it works 12 | 13 | IdGen generates, like Snowflake, 64 bit Id's. The [Sign Bit](https://en.wikipedia.org/wiki/Sign_bit) is unused since this can cause incorrect ordering on some systems that cannot use unsigned types and/or make it hard to get correct ordering. So, in effect, IdGen generates 63 bit Id's. An Id consists of 3 parts: 14 | 15 | * Timestamp 16 | * Generator-id 17 | * Sequence 18 | 19 | An Id generated with a **Default** `IdStructure` is structured as follows: 20 | 21 | ![Id structure](https://raw.githubusercontent.com/RobThree/IdGen/master/structure.png) 22 | 23 | However, using the `IdStructure` class you can tune the structure of the created Id's to your own needs; you can use 45 bits for the timestamp, 2 bits for the generator-id and 16 bits for the sequence if you prefer. As long as all 3 parts (timestamp, generator and sequence) add up to 63 bits you're good to go! 24 | 25 | The **timestamp**-part of the Id should speak for itself; by default this is incremented every millisecond and represents the number of milliseconds since a certain epoch. However, IdGen relies on an [`ITimeSource`](IdGen/ITimeSource.cs) which uses a 'tick' that can be defined to be anything; be it a millisecond (default), a second or even a day or nanosecond (hardware support etc. permitting). By default IdGen uses 2015-01-01 0:00:00Z as epoch, but you can specify a custom epoch too. 26 | 27 | The **generator-id**-part of the Id is the part that you 'configure'; it could correspond to a host, thread, datacenter or continent: it's up to you. However, the generator-id should be unique in the system: if you have several hosts or threads generating Id's, each host or thread should have it's own generator-id. This could be based on the hostname, a config-file value or even be retrieved from an coordinating service. Remember: a generator-id should be unique within the entire system to avoid collisions! 28 | 29 | The **sequence**-part is simply a value that is incremented each time a new Id is generated within the same tick (again, by default, a millisecond but can be anything); it is reset every time the tick changes. 30 | 31 | ## System Clock Dependency 32 | 33 | We recommend you use NTP to keep your system clock accurate. IdGen protects from non-monotonic clocks, i.e. clocks that run backwards. The [`DefaultTimeSource`](IdGen/DefaultTimeSource.cs) relies on a 64bit monotonic, increasing only, system counter. However, we still recommend you use NTP to keep your system clock accurate; this will prevent duplicate Id's between system restarts for example. 34 | 35 | The [`DefaultTimeSource`](IdGen/DefaultTimeSource.cs) relies on a [`Stopwatch`](https://msdn.microsoft.com/en-us/library/system.diagnostics.stopwatch.aspx) for calculating the 'ticks' but you can implement your own time source by simply implementing the [`ITimeSource`](IdGen/ITimeSource.cs) interface. 36 | 37 | 38 | ## Getting started 39 | 40 | Install the [Nuget package](https://www.nuget.org/packages/IdGen) and write the following code: 41 | 42 | ```c# 43 | using IdGen; 44 | using System.Linq; 45 | 46 | class Program 47 | { 48 | static void Main(string[] args) 49 | { 50 | var generator = new IdGenerator(0); 51 | var id = generator.CreateId(); 52 | // Example id: 862817670527975424 53 | } 54 | } 55 | ``` 56 | 57 | Voila. You have created your first Id! Want to create 100 Id's? Instead of: 58 | 59 | `var id = generator.CreateId();` 60 | 61 | write: 62 | 63 | `var id = generator.Take(100);` 64 | 65 | This is because the `IdGenerator()` implements `IEnumerable` providing you with a never-ending stream of Id's (so you might want to be careful doing a `.Select(...)` or `Count()` on it!). 66 | 67 | The above example creates a default `IdGenerator` with the GeneratorId (or: 'Worker Id') set to 0 and using a [`DefaultTimeSource`](IdGen/DefaultTimeSource.cs). If you're using multiple generators (across machines or in separate threads or...) you'll want to make sure each generator is assigned it's own unique Id. One way of doing this is by simply storing a value in your configuration file for example, another way may involve a service handing out GeneratorId's to machines/threads. IdGen **does not** provide a solution for this since each project or setup may have different requirements or infrastructure to provide these generator-id's. 68 | 69 | The below sample is a bit more complicated; we set a custom epoch, define our own id-structure for generated Id's and then display some information about the setup: 70 | 71 | ```c# 72 | using IdGen; 73 | using System; 74 | 75 | class Program 76 | { 77 | static void Main(string[] args) 78 | { 79 | // Let's say we take april 1st 2020 as our epoch 80 | var epoch = new DateTime(2020, 4, 1, 0, 0, 0, DateTimeKind.Utc); 81 | 82 | // Create an ID with 45 bits for timestamp, 2 for generator-id 83 | // and 16 for sequence 84 | var structure = new IdStructure(45, 2, 16); 85 | 86 | // Prepare options 87 | var options = new IdGeneratorOptions(structure, new DefaultTimeSource(epoch)); 88 | 89 | // Create an IdGenerator with it's generator-id set to 0, our custom epoch 90 | // and id-structure 91 | var generator = new IdGenerator(0, options); 92 | 93 | // Let's ask the id-structure how many generators we could instantiate 94 | // in this setup (2 bits) 95 | Console.WriteLine("Max. generators : {0}", structure.MaxGenerators); 96 | 97 | // Let's ask the id-structure how many sequential Id's we could generate 98 | // in a single ms in this setup (16 bits) 99 | Console.WriteLine("Id's/ms per generator : {0}", structure.MaxSequenceIds); 100 | 101 | // Let's calculate the number of Id's we could generate, per ms, should we use 102 | // the maximum number of generators 103 | Console.WriteLine("Id's/ms total : {0}", structure.MaxGenerators * structure.MaxSequenceIds); 104 | 105 | 106 | // Let's ask the id-structure configuration for how long we could generate Id's before 107 | // we experience a 'wraparound' of the timestamp 108 | Console.WriteLine("Wraparound interval : {0}", structure.WraparoundInterval(generator.Options.TimeSource)); 109 | 110 | // And finally: let's ask the id-structure when this wraparound will happen 111 | // (we'll have to tell it the generator's epoch) 112 | Console.WriteLine("Wraparound date : {0}", structure.WraparoundDate(generator.Options.TimeSource.Epoch, generator.Options.TimeSource).ToString("O")); 113 | } 114 | } 115 | ``` 116 | 117 | Output: 118 | ``` 119 | Max. generators : 4 120 | Id's/ms per generator : 65536 121 | Id's/ms total : 262144 122 | Wraparound interval : 407226.12:41:28.8320000 (about 1114 years) 123 | Wraparound date : 3135-03-14T12:41:28.8320000+00:00 124 | ``` 125 | 126 | IdGen also provides an `ITimeSouce` interface; this can be handy for [unittesting](IdGenTests/IdGeneratorTests.cs) purposes or if you want to provide a time-source for the timestamp part of your Id's that is not based on the system time. For unittesting we use our own [`MockTimeSource`](IdGenTests/Mocks/MockTimeSource.cs). 127 | 128 | ## Configuration 129 | 130 | A configuration package for .Net Framework projects can be found in [IdGen.Configuration](https://www.nuget.org/packages/IdGen.Configuration). This package allows you to configure your IdGenerators in your `app.config` or `web.config` file. The configuration section looks like this: 131 | 132 | ```xml 133 | 134 | 135 |

136 | 137 | 138 | 139 | 140 | 141 | 142 | 143 | 144 | 145 | 146 | 147 | ``` 148 | 149 | The attributes (`name`, `id`, `epoch`, `timestampBits`, `generatorIdBits` and `sequenceBits`) are required. The `tickDuration` is optional and defaults to the default tickduration from a `DefaultTimeSource`. The `sequenceOverflowStrategy` is optional too and defaults to `Throw`. Valid DateTime notations for the epoch are: 150 | 151 | * `yyyy-MM-ddTHH:mm:ss` 152 | * `yyyy-MM-dd HH:mm:ss` 153 | * `yyyy-MM-dd` 154 | 155 | You can get the IdGenerator from the config using the following code: 156 | 157 | `var generator = AppConfigFactory.GetFromConfig("foo");` 158 | 159 | ## Dependency Injection 160 | 161 | There is an [IdGen.DependencyInjection NuGet package](https://www.nuget.org/packages/IdGen.DependencyInjection) available that allows for easy integration with the commonly used [Microsoft.Extensions.DependencyInjection](https://docs.microsoft.com/en-us/dotnet/core/extensions/dependency-injection). 162 | 163 | Usage is straightforward: 164 | 165 | ```c# 166 | services.AddIdGen(123); // Where 123 is the generator-id 167 | ``` 168 | 169 | Or, when you want to use non-default options: 170 | 171 | ```c# 172 | services.AddIdGen(123, () => new IdGeneratorOptions(...)); // Where 123 is the generator-id 173 | ``` 174 | 175 | This registers both an `IdGenerator` as well as an `IIdGenerator`, both pointing to the same singleton generator. 176 | 177 | ## Upgrading from 2.x to 3.x 178 | 179 | Upgrading from 2.x to 3.x should be pretty straightforward. The following things have changed: 180 | 181 | * Most of the constructor overloads for the `IdGenerator` have been replaced with a single constructor which accepts `IdGeneratorOptions` that contains the `ITimeSource`, `IdStructure` and `SequenceOverflowStrategy` 182 | * The `MaskConfig` class is now more appropriately named `IdStructure` since it describes the structure of the generated ID's. 183 | * The `UseSpinWait` property has moved to the `IdGeneratorOptions` and is now an enum of type `SequenceOverflowStrategy` instead of a boolean value. Note that this property has also been renamed in the config file (from `useSpinWait` to `sequenceOverflowStrategy`) and is no longer a boolean but requires one of the values from `SequenceOverflowStrategy`. 184 | * `ID` is now `Id` (only used as return value by the `FromId()` method) 185 | 186 | The generated 2.x ID's are still compatible with 3.x ID's. This release is mostly better and more consistent naming of objects. 187 | 188 | # FAQ 189 | 190 | **Q**: Help, I'm getting duplicate ID's or collisions? 191 | 192 | **A**: Then you're probably not using IdGen as intended: It should be a singleton (per thread/process/host/...), and if you insist on having multiple instances around they should all have their own unique GeneratorId. 193 | 194 | **A**: Also: Don't change the structure; once you've picked an `IdStructure` and go into production commit to it, stick with it. This means that careful planning is needed to ensure enough ID's can be generated by enough generators for long enough. Although changing the structure at a later stage isn't impossible, careful consideration is needed to ensure no collisions will occur. 195 | 196 | **Q**: I'm experiencing weird results when these ID's are used in Javascript? 197 | 198 | **A**: Remember that generated ID's are 64 (actually 63) bits wide. Javascript uses floats to store all numbers and the [maximum integer value you can safely store](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/MAX_SAFE_INTEGER) is 53 bits. If you need to handle these ID's in Javascript, treat them as `strings`. 199 | 200 |

201 | 202 | Icon made by [Freepik](http://www.flaticon.com/authors/freepik) from [www.flaticon.com](http://www.flaticon.com) is licensed by [CC 3.0](http://creativecommons.org/licenses/by/3.0/). 203 | -------------------------------------------------------------------------------- /logo.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RobThree/IdGen/e084d23b1ec6883e0d18cf733430aacbfce71d1d/logo.png -------------------------------------------------------------------------------- /structure.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RobThree/IdGen/e084d23b1ec6883e0d18cf733430aacbfce71d1d/structure.png --------------------------------------------------------------------------------