RobThree/IdGen: Twitter Snowflake-alike ID generator for .Net

Twitter Snowflake-alike ID generator for .Net. Contribute to RobThree/IdGen development by creating an account on GitHub. Skiptocontent {{message}} RobThree / IdGen Public Notifications Fork 112 Star 768 TwitterSnowflake-alikeIDgeneratorfor.Net License MITlicense 768 stars 112 forks Star Notifications Code Issues 0 Pullrequests 0 Actions Projects 0 Wiki Security Insights More Code Issues Pullrequests Actions Projects Wiki Security Insights Thiscommitdoesnotbelongtoanybranchonthisrepository,andmaybelongtoaforkoutsideoftherepository. master Branches Tags Couldnotloadbranches Nothingtoshow {{refName}} default Couldnotloadtags Nothingtoshow {{refName}} default 1 branch 10 tags Code Latestcommit   Gitstats 113 commits Files Permalink Failedtoloadlatestcommitinformation. Type Name Latestcommitmessage Committime .github CreateFUNDING.yml Feb4,2021 IdGen.Configuration AddedIdGen.DependencyInjectionproject May28,2022 IdGen.DependencyInjection Keepmajorversionsinsync May28,2022 IdGen Updateddocumentation May28,2022 IdGenDocumentation Updateddocumentation May28,2022 IdGenTests AddedIdGen.DependencyInjectionproject May28,2022 .editorconfig Somecleanupandinternalrefactoring May28,2022 .gitignore *Addmissingfile Apr2,2015 IdGen.sln AddedIdGen.DependencyInjectionproject May28,2022 LICENSE Initialcommit Apr2,2015 README.md AddremarkinREADME May28,2022 logo.png MovedtoNetStandard1.1.Droppedconfigurationfilesupport(GetFrom… Feb18,2020 Viewcode IdGen Why Howitworks SystemClockDependency Gettingstarted DependencyInjection Upgradingfrom2.xto3.x FAQ README.md IdGen TwitterSnowflake-alikeIDgeneratorfor.Net.AvailableasNugetpackage Why Incertainsituationsyouneedalow-latency,distributed,uncoordinated,(roughly)timeordered,compactandhighlyavailableIdgenerationsystem.ThisprojectwasinspiredbyTwitter'sSnowflakeprojectwhichhasbeenretired.NotethatthisprojectwasinspiredbySnowflakebutisnotanexactimplementation.ThislibraryprovidesabasisforIdgeneration;itdoesnotprovideaserviceforhandingouttheseId'snordoesitprovidegenerator-id('worker-id')coordination. Howitworks IdGengenerates,likeSnowflake,64bitId's.TheSignBitisunusedsincethiscancauseincorrectorderingonsomesystemsthatcannotuseunsignedtypesand/ormakeithardtogetcorrectordering.So,ineffect,IdGengenerates63bitId's.AnIdconsistsof3parts: Timestamp Generator-id Sequence AnIdgeneratedwithaDefaultIdStructureisstructuredasfollows: However,usingtheIdStructureclassyoucantunethestructureofthecreatedId'stoyourownneeds;youcanuse45bitsforthetimestamp,2bitsforthegenerator-idand16bitsforthesequenceifyouprefer.Aslongasall3parts(timestamp,generatorandsequence)addupto63bitsyou'regoodtogo! Thetimestamp-partoftheIdshouldspeakforitself;bydefaultthisisincrementedeverymillisecondandrepresentsthenumberofmillisecondssinceacertainepoch.However,IdGenreliesonanITimeSourcewhichusesa'tick'thatcanbedefinedtobeanything;beitamillisecond(default),asecondorevenadayornanosecond(hardwaresupportetc.permitting).BydefaultIdGenuses2015-01-010:00:00Zasepoch,butyoucanspecifyacustomepochtoo. Thegenerator-id-partoftheIdisthepartthatyou'configure';itcouldcorrespondtoahost,thread,datacenterorcontinent:it'suptoyou.However,thegenerator-idshouldbeuniqueinthesystem:ifyouhaveseveralhostsorthreadsgeneratingId's,eachhostorthreadshouldhaveit'sowngenerator-id.Thiscouldbebasedonthehostname,aconfig-filevalueorevenberetrievedfromancoordinatingservice.Remember:agenerator-idshouldbeuniquewithintheentiresystemtoavoidcollisions! Thesequence-partissimplyavaluethatisincrementedeachtimeanewIdisgeneratedwithinthesametick(again,bydefault,amillisecondbutcanbeanything);itisreseteverytimethetickchanges. SystemClockDependency WerecommendyouuseNTPtokeepyoursystemclockaccurate.IdGenprotectsfromnon-monotonicclocks,i.e.clocksthatrunbackwards.TheDefaultTimeSourcereliesona64bitmonotonic,increasingonly,systemcounter.However,westillrecommendyouuseNTPtokeepyoursystemclockaccurate;thiswillpreventduplicateId'sbetweensystemrestartsforexample. TheDefaultTimeSourcereliesonaStopwatchforcalculatingthe'ticks'butyoucanimplementyourowntimesourcebysimplyimplementingtheITimeSourceinterface. Gettingstarted InstalltheNugetpackageandwritethefollowingcode: usingIdGen; usingSystem.Linq; classProgram { staticvoidMain(string[]args) { vargenerator=newIdGenerator(0); varid=generator.CreateId(); //Exampleid:862817670527975424 } } Voila.YouhavecreatedyourfirstId!Wanttocreate100Id's?Insteadof: varid=generator.CreateId(); write: varid=generator.Take(100); ThisisbecausetheIdGenerator()implementsIEnumerableprovidingyouwithanever-endingstreamofId's(soyoumightwanttobecarefuldoinga.Select(...)orCount()onit!). TheaboveexamplecreatesadefaultIdGeneratorwiththeGeneratorId(or:'WorkerId')setto0andusingaDefaultTimeSource.Ifyou'reusingmultiplegenerators(acrossmachinesorinseparatethreadsor...)you'llwanttomakesureeachgeneratorisassignedit'sownuniqueId.Onewayofdoingthisisbysimplystoringavalueinyourconfigurationfileforexample,anotherwaymayinvolveaservicehandingoutGeneratorId'stomachines/threads.IdGendoesnotprovideasolutionforthissinceeachprojectorsetupmayhavedifferentrequirementsorinfrastructuretoprovidethesegenerator-id's. Thebelowsampleisabitmorecomplicated;wesetacustomepoch,defineourownid-structureforgeneratedId'sandthendisplaysomeinformationaboutthesetup: usingIdGen; usingSystem; classProgram { staticvoidMain(string[]args) { //Let'ssaywetakeapril1st2020asourepoch varepoch=newDateTime(2020,4,1,0,0,0,DateTimeKind.Utc); //CreateanIDwith45bitsfortimestamp,2forgenerator-id //and16forsequence varstructure=newIdStructure(45,2,16); //Prepareoptions varoptions=newIdGeneratorOptions(structure,newDefaultTimeSource(epoch)); //CreateanIdGeneratorwithit'sgenerator-idsetto0,ourcustomepoch //andid-structure vargenerator=newIdGenerator(0,options); //Let'sasktheid-structurehowmanygeneratorswecouldinstantiate //inthissetup(2bits) Console.WriteLine("Max.generators:{0}",structure.MaxGenerators); //Let'sasktheid-structurehowmanysequentialId'swecouldgenerate //inasinglemsinthissetup(16bits) Console.WriteLine("Id's/mspergenerator:{0}",structure.MaxSequenceIds); //Let'scalculatethenumberofId'swecouldgenerate,perms,shouldweuse //themaximumnumberofgenerators Console.WriteLine("Id's/mstotal:{0}",structure.MaxGenerators*structure.MaxSequenceIds); //Let'sasktheid-structureconfigurationforhowlongwecouldgenerateId'sbefore //weexperiencea'wraparound'ofthetimestamp Console.WriteLine("Wraparoundinterval:{0}",structure.WraparoundInterval(generator.Options.TimeSource)); //Andfinally:let'sasktheid-structurewhenthiswraparoundwillhappen //(we'llhavetotellitthegenerator'sepoch) Console.WriteLine("Wraparounddate:{0}",structure.WraparoundDate(generator.Options.TimeSource.Epoch,generator.Options.TimeSource).ToString("O")); } } Output: Max.generators:4 Id's/mspergenerator:65536 Id's/mstotal:262144 Wraparoundinterval:407226.12:41:28.8320000(about1114years) Wraparounddate:3135-03-14T12:41:28.8320000+00:00 IdGenalsoprovidesanITimeSouceinterface;thiscanbehandyforunittestingpurposesorifyouwanttoprovideatime-sourceforthetimestamppartofyourId'sthatisnotbasedonthesystemtime.ForunittestingweuseourownMockTimeSource. Theattributes(name,id,epoch,timestampBits,generatorIdBitsandsequenceBits)arerequired.ThetickDurationisoptionalanddefaultstothedefaulttickdurationfromaDefaultTimeSource.ThesequenceOverflowStrategyisoptionaltooanddefaultstoThrow.ValidDateTimenotationsfortheepochare: yyyy-MM-ddTHH:mm:ss yyyy-MM-ddHH:mm:ss yyyy-MM-dd YoucangettheIdGeneratorfromtheconfigusingthefollowingcode: vargenerator=AppConfigFactory.GetFromConfig("foo"); DependencyInjection ThereisanIdGen.DependencyInjectionNuGetpackageavailablethatallowsforeasyintegrationwiththecommonlyusedMicrosoft.Extensions.DependencyInjection. Usageisstraightforward: services.AddIdGen(123);//Where123isthegenerator-id Or,whenyouwanttousenon-defaultoptions: services.AddIdGen(123,()=>newIdGeneratorOptions(...));//Where123isthegenerator-id ThisregistersbothanIdGeneratoraswellasanIIdGenerator,bothpointingtothesamesingletongenerator. Upgradingfrom2.xto3.x Upgradingfrom2.xto3.xshouldbeprettystraightforward.Thefollowingthingshavechanged: MostoftheconstructoroverloadsfortheIdGeneratorhavebeenreplacedwithasingleconstructorwhichacceptsIdGeneratorOptionsthatcontainstheITimeSource,IdStructureandSequenceOverflowStrategy TheMaskConfigclassisnowmoreappropriatelynamedIdStructuresinceitdescribesthestructureofthegeneratedID's. TheUseSpinWaitpropertyhasmovedtotheIdGeneratorOptionsandisnowanenumoftypeSequenceOverflowStrategyinsteadofabooleanvalue.Notethatthispropertyhasalsobeenrenamedintheconfigfile(fromuseSpinWaittosequenceOverflowStrategy)andisnolongerabooleanbutrequiresoneofthevaluesfromSequenceOverflowStrategy. IDisnowId(onlyusedasreturnvaluebytheFromId()method) Thegenerated2.xID'sarestillcompatiblewith3.xID's.Thisreleaseismostlybetterandmoreconsistentnamingofobjects. FAQ Q:Help,I'mgettingduplicateID's? A:Thenyou'reprobablynotusingIdGenasintended:Itshouldbeasingleton,andifyouinsistonhavingmultipleinstancesaroundtheyshouldallhavetheirownuniqueGeneratorId Q:I'mexperiencingweirdresultswhentheseID'sareusedinJavascript? A:RememberthatgeneratedID'sare64(actually63)bitswide.Javascriptusesfloatstostoreallnumbersandthemaximumintegervalueyoucansafelystoreis53bits.IfyouneedtohandletheseID'sinJavascript,treatthemasstrings. IconmadebyFreepikfromwww.flaticon.comislicensedbyCC3.0. About TwitterSnowflake-alikeIDgeneratorfor.Net Topics c-sharp dotnet snowflake twitter-snowflake idgenerator unique-id Resources Readme License MITlicense Stars 768 stars Watchers 25 watching Forks 112 forks Releases 10 Minorinternalchanges Latest May28,2022 +9releases Sponsorthisproject   https://paypal.me/robiii LearnmoreaboutGitHubSponsors Packages0 Nopackagespublished Usedby206 +198 Languages C# 100.0% Youcan’tperformthatactionatthistime. Yousignedinwithanothertaborwindow.Reloadtorefreshyoursession. Yousignedoutinanothertaborwindow.Reloadtorefreshyoursession.