From 39d53a0bfc68e3aca403da0c1f7bb0d3ab6908a5 Mon Sep 17 00:00:00 2001 From: joaquintides Date: Thu, 24 Nov 2022 20:06:05 +0100 Subject: [PATCH] added "Open Addressing Implementation" section --- doc/diagrams/foa-metadata-interleaving.png | Bin 0 -> 24176 bytes doc/diagrams/foa-metadata.png | Bin 0 -> 5896 bytes doc/diagrams/foa.png | Bin 0 -> 3324 bytes doc/unordered/buckets.adoc | 67 ++++++++++++++++++++- 4 files changed, 66 insertions(+), 1 deletion(-) create mode 100644 doc/diagrams/foa-metadata-interleaving.png create mode 100644 doc/diagrams/foa-metadata.png create mode 100644 doc/diagrams/foa.png diff --git a/doc/diagrams/foa-metadata-interleaving.png b/doc/diagrams/foa-metadata-interleaving.png new file mode 100644 index 0000000000000000000000000000000000000000..0c751922d08c2a03ee8e359f3596da9de24baa34 GIT binary patch literal 24176 zcmeAS@N?(olHy`uVBq!ia0y~yU@~A}VCdmsVqjo+%fcehz`(#*9OUlAuNSs54@I14-?iy0XB4ude`@%$Aj3=DCso-U3d6>)F(o-UR-KK0vK zdsjp4e6=L8IEyc>*S{5s_1)a_n8UqB?ycIsa?^)P@6WutT3hqATlC`7Cl;wjZc6QB z;h3br*~G%}foYCd;;{JFs#iKecIgGC zTPNoplJdPUV^^P8yvWLRGX|8qE*{{OlAs~IXU?d$3u9RL3NzpJJM@~tS2|c^G3%De)~%+q78sU3jFr`u<9M&-(S1~2@YC&hxgQtn_x;S~ zw7$18s3QDwE#t%9w_h17M1qw6|2x!JZ*k+ReyHfbl|dEBE&743iaP%sn9PLaxHd16 z|NFji!Jn)3whMlw*@tpfdJ6`9u*`Du-=Z;^smY3q)C?^ zDXh|HIVx}J>AxdSr6px!h=+&#|33%z|NArlY4Mwuc^QFPvKRWSUY_~Z!EtH<$d5-e zE+XvVQYm?m?*8SunqW{fEUpBC6&5nvzr8d++R-D$sjGtNV#^Zy7v}>+>VL|72zVR2 ztV3++rM8<(81IMMS1)FPr-RVz7lYDt#p*4Jo`|#a{du(gljV)P@V|4yT)KlKyWMIT zk7{UzbUQ1ywP^i|wPU~icGY}aShV%unrU97aB^Cf(1HnFcK^25^Z13@yDxX|$OzQZ zopCne^Ul|;;#n{Dy?*dnzeM$8{o<&m^XKjV*Q^a=_l$Bd?7Eb}cr8&x>YCEIJrnk3 zn=HE8D?ephkou$x9n;o1c+X|`nGkup;`%{x5x#3zCr5gJF!Y_?a$;R;Uf{YVxrW{L zIfmsXSKj4Se7;0$dYC_Av#5JNbfA29hW)+$sHX(TZzt{c$0?$8l^;n^@tWYsw zZu+b9dv?d}+2=O<(xI>O{VnGf3i?z(iR4N*I%bJR5ZO7AI&|iVX{KC!#gqi zqCMx@X-iy{y<~e;qF#UT>TuiAvei7?TQqdO(8O5pRj))hWqZDRAJrk&ZJ)zgZc-!r z^{2S~@2C1fKKDDtmKyO*+_$9qqiIpV691#hyQh`t?{mm3)JTaxB+L7F>-^*YS+%&l z7A!T{{eFrVJ2d6W3B3q8dCO6JLYS#4m)-l~soFu4gCe=B)F(Y|R#t9epMSPV!(>hC zVh7JOU4^wu2VVZ&Ea(w1CCYoRT6P3?XKRhuwJ8f+m4oK4i?8=^NYg#2Zl(O9>TR;l zrfk6_AD1xd)*R?&Nc`gMmZrNbg*4Neku>Y*I zBqP45`Ir7aH|H*fXL-F*S0+wtT6;DP_6K zFRokp{}J~Tv393Pts$Nj9>&3&V3lp6w}tg|OIs%=Rl8p4qJRVTX`8QQKVjP%uy@hk zBbCzmx(C9({9&|X^Z0Z;dg9fLiMcNpB$;KC>wu9M-T$|21!93dlHa>0>Z zw&X&J#wkOAz%P^M|8a@E2NrQ;_dQU2-gddhafckHicg;oT|Bt+?(yoPiu%I#!|N9Q zTsv32fBu_Z-@H?2ZogdJZLVgn-=lZ>;l;+A_q4lh4}X4TFy-;#&&T!HRO9*2$QhsV zwY1%I#eSEK#kQh%we%;|gUL;OOtj%!UVU#;q{HFcra(~PelUI%E-SUK&3;{i>+r)!!c zoP?wT*cDq^&ed&JN!hULYsBXZPouN7XZNqW8`-{b$&({XD}OBhUo~|_!r~1d&X{|P z#kvNG*q9q^Gx~D()zsVB;`?ITde?9ZRB(%$FW;v2T)sqORWn~y-_&aBa`tfde@5v- zJttmX-~YaH<+79q&DG5EZ;C}@jBagp;JwhfPu6I$i`M)-Tii}|hQC{L)@F)OMyC*m z58uHMvF}RR&&`q+KBsO=&hGr8yr`3Kxo)KXEl=#Z@cyh?V7~DB>2<8DGk+mYif$q=T@z| zd$*z8O5~~|yDs}jSw4kA#mBHp6x{`!%KRz(YT#jAq!fobYWBxAp-mF`H z-rZAM8Exdc@XNnPd?KoBvxfr9S0bn z_y{|%e*E|Jtb75x!@`p`O<;Rz!?tcw-9^<0I#Ub0o;@YGb*6k4DYgYV`vytNn+u1ua?mTFo8YsKl;(B%I$1f*>&a2LzZ@?D3aOwN! zaz45?4L=PUgnZkVC8V@3vU;Ildm@(O@8jp;9ABJxqAd1&IeF&l{&R8vKIh!OZTiRL z!#|OkmtS4sJIUL!c>dBM_Zk3$}8A3x`WfTwEPHNn_ zeL_NJP)qPxomD*^&i0coACUjhTgnynYfI42ML|Co7jp$!My{0M*F2>qzf$jmfUKfu z*0kUyUNaV6uUjBLSJ%-yOe1#Pxd%IE3cL&Go2KC+eCbTkhE~R~fa6OaFj3&l-d6Syrrk59s4*GO{a^O<&x@k>qDPyS z#Yn_H)7w#ymnweE(=)IlcViB_?4R1C>YsuyJ9euwDlQN{l|MgvUtv+;a#N)X43Qk> zPMk{=?&!rR9nw7EsmT%Eu)^KXF=xYcZ~hqNN{R4QO3X(6?pt5oV7S$4eRnU9fSikJ zy5ad#yP`OCTI)KlEK$4A&r;&OK+J;e)`Rt>T#YvWq~4i6VA2*|v~8VN>V}}563eX9 zo~jrwKQzU4GM6sb_ZQh0Ow;BZ^_y8XIXLh0WXsOVm}gC^EK=8LNp`5IWHfm2wysEK zcPY^8NLjOXu6mJ}sXy z>RD}UyytPiTn(Pg7wkP;{wUatEtu zSf1y%h0A$=3fR_$J(ZT}+1*g~fay$!lZm3>_s&Dl&asNK6mnjx32@!2a83A8sl)Y| z6WDlIRvvIG;=OY8YuJu|UaF^2=e(42GB7;Uy`vP77(Yd#%W_>G@hyrvF$<>!;lk zfsBUk)aG_IYp6&OrNAI(%`z-qT=FoB>cEx zgWryxkdr=nIt~W2)DtG2&`xABPJC3waV%;9)5J{SBL&4--j^l59u|msCd6s}NZhoT zv9s^Yzn!bSHpo6bWKy+nB7eqm0c&fKs|WcxSYn!V0;Tyj+-UV-ZF+d+)LvOnz8#ZZ zteO7T)ndtnm{UFq4^)Djfv$^PO{RO#KS2`sQbjNr;E&Mrofu17cn<*`4 zZtYBO)CpMLS&;ZdBuU5Q?*XnOk#o~$D19*&aVvWgG(+jdU#4Xo-V=`q?3jKy%d>Nh zPWyuMsVasqM7@_E+O4y$X~hLsRlNmzewoZ0B#(8S$uw{d?^flk=~bPy@o0)Y*95Wa z0qG)(I6aLzcU(EnqBui)XPoSDhF6m=`0wcV-t%D6F3!mfJZ)Yc*-yL#wR43$79E}{ z_OZZl+TuQL1!;|z(;u3OJ{z@2YqsxwU@$o?C`crIXPdU^_RQ zI&}1jUX`OO%PS?l;+d|TA9!2Swi@tG5jZY$VaC20+Gp2`9d*oL6Z7<2$k11yI&alu zi3L+mf8e+l=xVq?wq@^+YV&umy)s|4J1vy2Xg%XLt-!-YC(f}YYR9B0PBWTME#%VM zmi26c!+FiUub9mX#8ndGPNsWl^e6M>O*fSj>|j(@{weNn=%aVIDBJKPEAOGH6Jm_= z3&QleLHWS5b9tti_le{dCl9ZXK%NJjzKSj%T4a<`53zjvHt(S7Vqxi7$6Qv(Z`v4A z;9+|uC$@*|-C^^QfZ+H|Y^SL=-hR+$dr25X!HWlfkjsWQe*oRGz} zllvx5VdQfCng;^MHmSW+;9u7>XWOj38#TR+lrkQEYZ2(Tt@7-QQMYuw*buuz?vsac z>9k1`8hlPY%t>KNZ@S~L+cSHOubq##eawN>m^~8bssv9dubE7z*}ii_S?Tq&5d_7UAmDgBtW~F78TmGS6_S;WzO$g~b*3#|k;8Z03b@d__kFe=#ubB?@{Rurj zaRFn;%jBs`-?9H?zq;q?jqGm!dpCm(MK-=@pDx#?aE&|pBv+SaOX($9i5I^Mws{?3 z=U8c<^_)pH5)9SmUZSrk6>jL_W7z8Y?nXK+9{EINq}d2N8*(^ zY(}9HqHh;*dUB}!-G5I}rnvU}(pD42sRI0>o)&EeuP#Z5&oG%h!GN>m){>e2Dn_|X zG5S-SUnQS?6UZFXR6dL2X_A-1LXWY)`hpj2P9Fcq{!|wLD zFiTBVU3X)r5&I#-((olL5qi2C_CIUUR{Xo-%@VU~@ArPr`E%h^r#SQEb9>AT?`~cA zf?Z(o&TftO&rCQjZc|TDSZDs&?#O}I30*D8!7JFMJ&e{|Yt7to^iD}bg8EdKcL5t1 zR?qzYY38Jq18baO4YIw;7%%bt@#XZqvZ%tOX#&UM7FVauR(|Y@49W$++|`ibbTStA z=1{Y`-n%D;p*OSdppC}zcWcC>9*d>b#pcXRz5Bh*t|J8MQFlAN|PkwcuKe|06LY zmE!1F6^`#07H*pmJ!$1>CLcB9-jGFIK@LHCTQUzz*{od?Tdnawqvqj>X>+qWPIU44 zIP37eWI6uz$m0*UFW+{TySZJVB|M00=g}rlMEzZJQBO2ni4DK5-4)mMLY~3L-EEz3U-r_y@%toau7xuvh%Sr2Z}B;4LhM9?yLMal ze1D$q*rya+cFp^YVke(r6nnX@id%@sG2!iRd9!yOSfZ!1q~+6;jdImH;_mac7v`7D zSjl?sREqMgovOAk3@^66`qHp4Ij>Veg-I!}-(h`UaPtN|#TgxIx`G-iv~G$rEfq|> z+UX*2_G}Ahn6krl-x(|uGldtEx5)rIAO|@uhNSwtIl#d zT;k)=e{oSxb z^P{1vdB%be|A>jlRdfU+6{e(n%wWlQn6%@_A}-I_kBlT3xA=b9|K^Wy#6z|d%t-}j z7x*QbhD4Zm73kj-4cmDqP07~vA&2<#{PTQWjEN;?b>2)nnKs%b8hL%on%ptRwef55H(zZ>?r+edLcTc-5<-41atg`{hIr(X)%a$9|}FW#*_|DAiW z?gnl~sjjYU??+teidx-&4BFOc|BaEHz{@@9jzS2>-lcDx^$z>(oap9pzFun5iwF6$ zRL-=#Xmycw5tuZAYt4c_TStK>Wj9n+wKEEA1;dJTB$$k^bc$rCBnmkgTuJaf`;heu zL+gs}qz0umOOKi?&uUay$#|{jOq528?gy!)?kA#o$0wfr@OX!82?tlv-Fkqw*_ zqSnaop{CF?@6_GxVNc8c-Lu^yb%$?y$19cuQN@U+9bz*WHeZ}wrV_x)oAfMH;=xgk zm^Cvcj@L@EKH&boZ+=qgDc0Phd;gRQIC`+?JQAPiEnCeLH}R%{5r60t=BC}}Dpnlt z4hi5j>?n(6R*k#D;aSi<)y#2n0h^$`WiAuTubngMnYf<@=uSP7YJY<>bV5a8T zpt4ypMK~)_YOX^@<^D|tDu1@UIbDA3nDBR(1BOn?Tc^IM`%&^_!>wCV@nWx*kXwD;m6${9e0!Ztllk|aV_CX%&dtpXx!%nVpCuix7wB8AXy$NAI^ehE z(R!Iv(J(Dt}GOF%KP+#UC0E?}~ZUw578m_o=PsWwk~D9+B)z z(uWjVO^n1>crQK>c}w82@3gB;s#VDAF^qFv+Wi6U0T2>&?2 z+~Br4?yy5H6I2hSdCXvGsgBuvNv&texi4?JmA4pt-LaD2)HzDP;qJ>*y>AnmEvg>! zOxAS$Fumvpr>kbV-Q{4Bt4_T!Yu^2_W&pL4`!!lepX@)y|Ih z`%KrhSDaaOBF7+f?l;CG&COL?JF|lQ_}?|}(9||Ba5lZRe$P(j`(|^0-K`3k)K}MZ z!(C+Z+8Ynk%w8>=^e}wc(pw8A1jigm%{+5t+s0FQ-!Jc*-YoL`+rrdPe!=+;nm*Gm z-F>fp+qS=rKXm`PFQ>kIi|%joswvlqIN;>8|4ff!fskgxHu1i+iB&b_rMo9QX}cv= z((Co23KT3m6yKT1WlQ*ahZ@Y$I@R^@r7maRpQoF(zPj{rPF66=J>;~0i>E`j@S}~# zABkoyu8TAYntqJA`hnc5g*O-SZkB7ArP;oBgKj1Fe9k=%rfdgZ+rL?pDMFb?#^~{S}=Ew-)1Sj<+p0nFZJ(c zw3>2OdG}s@_N#sJv7GDt8MqdU>UKK1bMc<;wPeQ8U8)Xzr4$=kj?b5=ajI#0Ks zRa7IcOe5ovMa)dQJ%!J%KDap{#OU!FHCwjy8JS`(vn>xEQodVtA-XwVJ4~f> z&Z+@xnmL>%aV|Z>*}{2friVLe?-BVT zJf(PA_KqUUg7~l)H|6@dFB~Pxc1j$&(EV-MgyJvlCIXk(Vx2=x(khC1GT2_p7^SV= zBEZXe;mWpUVq0EZ{`HtMBzX2y{dSSIu!&(tOD0@99N8xOF!!ayjAe4Z(u8tbZ7j|EoQ`vP0;2r3)i+rGSI(E|Cr_VzVdt`|IJ zPno~yRi0-9!=6L7b1wdf%M}+;JoZ9`Eo}F+ck5;jGPmtAqKsCMLQ>Ip-I1 zze$zqthC^s?<&Zqv#vN^V{_d+FKdUxyNVv!Nl7z)S?oF2?2O`0j@Jv#cIdV{#GTav zwGUhbN++;$IEQ!ys1>bT#O7e-G)=)RNL?^;?g_3($`ehFw|ELnHxvAx$a;SZXTZWE zwdVQ<(=I9OP^n!r{nifF`?1@c7YMBIPUANI@PfZ}5r;#Schk%r9TmBr28@}8@63wD zS^hPcDeU=TTrIXku-Yf@^RMGvg$EpE9ah$S`?Sm}%gMxI%M87iLnaWaNE%UDm8w@m0WwGmi zShS+ygt0(bmB2O0_{m#M_Ng9ZS>rIt(IvZJ{Wk6_wSTjAzuz#~%2;?dTNrPB$lt7s ztA!`OZ;ux#J=$LP?cmfW=FC$kZg0|kT&wSU?N49xy)NIH@AGF!z2~gg`*v8=diSFV zS*hjC{24wE`%n5`&q-3=lzwZWL!L{U%GuM&8~*cLFnZR;I!oLs*XHwrtxHW;%oIDp zeWC41bV*p;gg;kbmd~ERF}H>7(I%^NoJV3jMUHK%yKg46#C_Av#-7G4$F%<)JLomT zKw9sl>UQQW%seiC#kw7CZ17HtQoVCoq@Z*5>i{Q9ui9cejYg}?&>tsbH4fFC%vb2o zxv6sQl#uwGC)}^cXJ)Owy zJwNQ2Jy*u#Bd5#FmK$&73~~Ht5^%UcDLJ22&u4DLdAXXz^@_JY-EMErKRvIqcG1C! zEvrf;{8oA$P*;PaP(pW{H;PwiC%xcm6+XI<@p!%$lnWohz@+{Ii9# zbHU+kf0uycJDUPLp0cdZNq)t0VDT&)1H1JtY#xVHOqGAC`7q5ji)`F?aEoWdUkM+9 z?L|gx>;W7T=Po<#Q1@lQ1a`Mw#cdo@C-Y8DPHfn9Tz(eo#{0hiTo&k6#b{*x`^S89 zQo_1T9bfiW=dVehIOE<4J`)a}w#{n4E~r*-m5w>V$l~~B`cWQ1yTb*U&5J$luRU_t z@V|F+_up@u{`d!_eEH0}e}ngF&%Z9hduQGdX|i6mzJ0pw*Wb3EY7K6vuL|m4%@oz- z)REM0Q@4K)+YX0I&QGh($}7&2wiZcYIeh;^TU(=5(6oSy-=h25?uQ&!ewF_uFhrsL z>e`lI-s|bjzgl1Ians6d*c$Ts!g5~^7lF7UwwJFg@&zJQI-VHqO>5%n+%u^~@FwTe zS1xi5jVof(WL-I$TpUWR>;?9nG+y(dJFcnv@vDyaU-ZwUr`0Ka;m~?;G$)38`6(g6 zzpumk0_^!k=N?LZHP1(3`)cpN<5kQ0YfbO|y?N!Qe)>M^`Ckt6W^NGP8ZNDvdU9L1 zwa{jBv#&|aPLEhmUOl#LEP6~5e3{c~r`^(dR<(#tM<0l)Qtl00xRAPVoJ_=(Vd(aE_CHl#%}J3#SG6b(w#)XPd^mEztT2~TOVmth zZ?LQ05m^tXV-KP(c(bw9tLSlf$_1xinrhIyRcxx$q9X^7oXS+%Xn)$T>d&N~8iF^P zo~^2VA)$Ej{UzlI^W)h#KX`xVyL&goprf(EvDkER-Av9Wj4N7wJ$NQpHgdYX+QFGH zN3W8HF};!RuW#ucKjb_htKQ>Ut=z*HGW`^$@7&i(wHqS^`-B2 zD);=;^&I;gwk%TJw7J8&W!sc!p$xqs+pNQ%PL%L=F40(V?(S;e1SfsNy&rXRr9xV* z)owekTXAE)gYd71OH(6w*&`IARod!&1pL3gQPomnl286-ov0d;nj7wXL0fBw+SfY9 zy|KMBR(G-3IBt;LYRT>7c%?0a^G+h)M7E7BE!|g~4NRqd%QOP!{nA`!y+YpolG?!- zSN9p0dn%@Q+`cex-oI3ZNm;){-k*uRd(*6N31e<6*Dc*xu2;M(=c}!1_4U}ZbkDjy z=U?rxoY3i*vGO46Bo=||9FK%*71TAn=AIA@JLK|1`OUL)^-=VXdJ#XFaqOZ43UESQxJb#5{x$Y4TiKd3Q z^pYF}Uf0t3b6);BePyHa>X4u>hmd99X4u1dD|UFBJihcsFJF;d>j@lnJ$U`pl}?Wk`z znf4ppz7^dV6mlVEro!ov9_d#qMwk*kb$m!_% zxk2=kfRR9^(2Md{=~Du@XHQUZFtL#FV@|YNx4UYnf2CuU4jKldfw;%V}Qzw_B~3=&w4#^zl|s z=og{%zl`07?_Wwy`6GB(LBdJf$@{SFRF++CZv1|~CaG7j1swbg4v%*xKj!wEG_m6meZaMth7`}2p3F@*iK1K(ZSfB(Lx?@B+@BMQ^|g1_`*tPX3;msQ zzaCeP57{5}<lXGstaTQ=VqCIn7VF1}huePkmph(cKgoRcT#Fsf zuTQRE?N#wS%XYRy&tj$K;_q4+dKZJZXHR$%niHg!$f$cr_~*NhZkEEx^J@@HX-zL6t^RmF!%Vq!<;(aU!(t1+f92wqy1_e1Q^0SWW0*Seh7>KI$LPh6;xzi;dA zo_)efEuWQEI#nC zuGGJ#zc24ka_e-p)xJ)Bt`M)DK4_L=!-wX2kx_^gJ0@t#R zjgHfPxt@qh==c*gbxu!uC|f$u>@;@st@|A(n;B+=DjH{gh~IpfWs;4Ep$(`MG5QqB ze)f3G;r)-FvpOxA_qa)==!~3_;pQ#DHHTDgbp4WF&l0fb*s43Z4b3a3UC4R6$Kk`T zPhY35ZuWMr@BH!C>gJ>a*7LJm%~_5K|2=u^fz#dD%MuP>m0lgLuN!Y;b=`YY>Wb`? z_1jcBPKuQN`Sa)Gyq)XLFW>b~VvXzEs;BQ>ENtC+UXE?C-@=w->d`A2H+Xb8KPy!E zlXX$?Yp*v;*p0t`G6nXuy#2(w>V3+bxk{Zaj7{k^+;roS#%yx?)9ojIX! z?YqCH?scX=TEA<}Ns0H|`|edgd)j%od>$K{!1~OGGR6C%KGg8luThKD-*2?}Z{Ut2 z5ez4ymdus(5n*_FHtLFi(0Unt(L`@qai&EQUXnk>gjar?*r2qhd-)OZ(nXmWiHBG| zh+iweyo@^%)B{~mn3nha)CsTmKYuP}{w>A)a<=U~+spTj&8=R1Kg@fwK|LWpYU}$V zmw#7k%f99OKXk%e+k5rOx^2p025NwyBHy-Vz>M7etJ*3Yr2&U*JIz(wfr z<66tJ^_^G0C~pqBwy9EM_x^gTp9iDLM#QZTMfh^k4b=%KF%o z+&1|dsW$=-99iJdX0g>a+S!BWc4cBk^p(Ou1w9WY#~A^xtqgV-I=LAaN#t!1QcDth z>227vg7NzShYu6XoLTx>HU>#0=Xp*jcjLa}u<%bov*o74<+o(&@6NRK(m1ZQE-?If zvlVCkp4DPMdH2}6?%8lJdXvMdrDrQQs2ZEOzIb@;%C$Q`4$r-~ob!t?$MSPw-`eJ% zjk_W9^YcIZFpJN}SdO{;OJ<#!uq1S{Mpi}QhfAl{9$fody?omLFDJsdcs=x(yw|d_ zESP@(gZX>~)i>HA8JX%?bGSM!v*xx<@i@k4n*A?MK`zj8O|sU~zbCyvm_LhbXb7zO zxcK)g3-<(m-?cL(ye)W|)x3`0bX#f8x25^TQ~fpZtW~A`%m410r2nG!i_x{rTQ(^y zE$_4EuaDuloP0lW;So(aCFMlla=VtZryt=KXpHH3(yFOV#M`&4P>}o~MM~2~t0_J|( ze?3I-&BYltCUvFRB?-wN?sV-wD{EPsSoq=5skIl^{to`VpUeNt^?jFb?W@XlNJ&v) zK6ggqQ|6472iQBMUhrjh-LCyNn~S677$2+Z{PwkT7a7fB+RIaQrBH9is;92Aj^4ba zc7Iyyv`xCs$C^4;S2Id4IwoQB)2V$+W!bNOmRBh(ZjZ$|CI3p?G+Uvl!lb0n%$!~t zqvO$kflu3{dVM2zkn>&}yDxXMCb9|0bN;P*aAy*D#AmL2q}09*6^3cvOb0s{lOHcO z+r8uUorizkmOgmK#$xIG<-@i{W?woA>2-oB#J|)$+akxxI1sCHBbu zUH#$s@8^A`{^hkr@1M+ncUR(^)lOfT#j*y6lbBczd$2B8Q8KYi{pa@+%8qB>@v*u+ zof7bF^2>?hi+*kT_wlA%L)<07zab~uT7NY3?_ZJTFzx&zzW2QSs$PM-+6EjQ?D;eQ zg_)kOztz59ucfWhl#A_c&%LPW*&LmQn*DaoVWlw^DI3n*ebk3R1E+t49nZG8Fj)h`D&?zHCpQ{XIh;Q02u{4enlFWznbZ+`dW zznu?PpAO#K`G1SiI-I&`LFA)zw5PA+0L`wsx+%%WBKW@?}N*1=@p79Cj+_qj;e96Z<5T> zxqknnH$PKj+~?=5`Z@Y@+*S*zxkYbMJ^1U=i;vge&H3rQL3QEn8@rKX@YylZ?ZBjb ze|=pY_Wj=*Prp-He!|Z6?!CypUo0L-%jUXvSZ`rAJW=20+uWhEy6wo*2(v@(Hy0*s zWm8+Y_aW!sjqT8@61jwgtpcBam$um7oa7*t;wH1J?aj?w{SE>tUoM=uC4F)JiELf3uc7rR zC%7sPzB;{i?ZSmu=QYlnxpy8nx3hX!e(lb!e?BV5|GIc1uFj=-#uOiGf!{vT9x(}z zE=Eg>ue-9P`NYe8M^D>kH%i9#%YA>(x_H0OPxfAYZZ?iY^CGt?7aLTH_iPiNNhGj#9ttrxTpvj$zA*5H2hVw|%F zPjzKScg&6cmNPPwWS&?vd}o^C@L}q9siG`V&uC8JX$hgv(r(7wn9EhaU$4lU>8a*+ zl?m>b6jIopWwnRjI&!*M&uKQ_ZjSky3v2#gO=59ZP|h;gRQ7D&HoFR=pFf+k_r6}P ze`6>2A75v~WuBX5I2ad%JWF)R=-u7Cny2NeC_~a@eddYnlHLl^@^<_F-#mBY`s{<> zS{$q2w*Q+nrL|nkck_W7o?WF)9@#3cl83aFYn5`gre+94^6#!H`+LZN$JO-P>JOW^ zCAqVu+Vhk)M9I2vIVCc$j9_Y+@MCq~>!#%%VO}mTjvTo<%S1q0Vqb;M0;jrLJZ-+b z>0J$slWh$4*v&}ceK1ME+hWGWRT`%+cQejNT+lWlMQg#2N-c4x-j=D;bQWbCV7KyJ zSjaWQs+*!KpDZZTugR=YEa%hmu>Nth5XaUOk7cIIph@jQ2An*IxdpGuo{W~|C!?&d} zYwe6vm5CfHS@g3XaW8BsI+wH|kxlD`_#s>WZaKG%g)N^FymVi+-|N(|vRs_KX!@Fq zM|Vv6bAA?=aCOGCTbhnrE;weSe0i{~r(>DMI-j~jsw~1kngY39I^Rbmy$x7UzG1^j zZXu(Yk@d%X%yeFqumnGRZgs0i!|_-CoDf*}|5p0v%gfEm zejQ%Q=l{!-O;)8i^1`;vo*T`r_wU8*z7+jgKP+?F&4Xw6zCPc?$)dD7mF>`KZ9#eO zAa|2nEVD$szo={w%W0mkaB<_st()sZ=DM!G$=LdR+6pgiPYYw;MTHiu6PL41QC7Ri zckRt;u@&4*n>D*=<9@}5}_dB;GajS&$oU@uuA4E8Vo!E@-ZF=&iU_*Oq(XWHA<{sCw+`LBV z%Y5GC?7G7>x0dUlkn;J)!U>EUTU_qBJ)ZGcI^$&f zhFV766I+VEoMZB6boW?f?=P}=rrP3v*QXkInw4BRH+3t6iA3554^S0T`QwTsCxd7r z|CT8>lLI6=)Ml|&R9{}>Z^Fq_FP4`d`#S!Wt!4EWC)0v2XUpo%N+0#^o)|5}#h|ZV z_0=g`q5a)Fi=y@4D{^NQB|d!h@#}B*a=G&Nn!hsBPAm}Q5Swn#8@$E2eE0p?FMcNd za>?)YJaMzwdvUGw_xAF#ceZB>f7^ibpplo_ri@yqxXrA5P2iw4YJe zf4O}B_UXXly&u!h&SSqEAY!`Fv?TNEo7Pz;BXpY=*X`$;ub;ARjoL-^Z?mMuIEtV2 zwQia5r0+t*-Ur8n*RGuS;{Km@FNXq;U%M_jWbn6%-p%C85YTB{&ih7K=;74oJ&m)i z^w?GO8`-=jZBK0bw=3xUQr5P6uUtM0ZdYCS`{~Ev_&es8Cr;7!+1aqXzAEAIt@+QY z<5xy5-u2_u-`(wD=J#(+6)$?fIlWk2zK<_=j@-JFJbET?>-T)xu|DRmYlrmdkuGTBzc$3a@#qQ?_^0)mvXoF37u9Ycjr$+=7X)XQdjMpu68^wTICVDU|3j8p4*<@Epi*<%olLTG<^J! z@h#wVL4{VpuFp>&e=H9(aFb@U_WPUn_hfqYL5HtZU&3;t_*Yk)xpP$RX6J?*H|!f( zzg#)He!AZtk&>l-+8nlJ0Z#8EItqjO$(s2W>S+oj#R zI)4XLzZMc)qvVnx%4B)AFJ~2x(RE!>UPq}@9x2~BJKNpnDVD}a8Qhv=%j&vJIr9Mb z%4YFE<>`*vho8Uv@cp&WHWiom`&TuY&lgD03p7}BZr=;hOa2bJ%eAcQ>wF^QD@*n{6p6CGk>hjd#Y%YQs{7NOXrKj9sIWy_J41VXPZ@5%lz)* zwy%4wDt|wI`gWoFKIag*oxdyp2;X3cF%7OPD$M`0SM+bN;9_?1Ci&OaLhA~8mc|+^ zcDzt+{B!@2w%>cqB&%W&w`||$D>+Hr*mE5NiPWiLr!>dx$e&@UT$}VH%m(ES) zQU1o+`Fuuu+lvK#r&%`kvhVWT>5=B(6fkj5z6;BvR;!21mlQJ861@+-={?I6Eu^5h z!Xw8yNY#h!?+KF=_pHyKs5nvmD}LQf^*8m8@0~qAeVX1=Gf)35M{TmRjeNcSEczar z)l|vzWbWD<-uZSrzTMih?4+>%eaXMCoz5~jGcV}Q^jyez*{nrvX{)6A%{!i}4@}{? zv7bk30*9)7PIJ#5!|jzd<{uV4+-S4L`7{S(L{Fc`m*Y9}Ja60VlDMrRma%a6$@8lW zMc5{lcKprMs9&;NetQczuo>lym+>J`nf&Z&Ob7d{h1mZZ}w}}w>>r4zMIN)W5u7h>#e_MwSViM z?e5k4!?T@Ia;lyc{P_EF>Tchj;1ZL&USE!HJMqH4A~SVOe(|Sn_SN#OovfegZhYOa z*f?XF>%@KKYMlpVa&O(ACt4 z_(%J8E$51?cwt+yeI>uj1KE}Sfy~^^>fy)s-Al39RP*TKIB{Al_w%=CS_S6;x$#?!boGuQ=WaPg-fq+UMch{eiYsZnIT7i~2Cq|NvF z*t)#7fY2!a-?=vr9guEmWnpCgx_?~=Pn*;29$&HFEk~@K)6=6_HF<36KLzYMyvr!T z`p@58r}uK-eSYP=T1l^2An!%^1XIIX>8glK@gP!+?D)Zhf={|ZQSl%yg*N&2p$5xqcKCY-~S7`sA zea4DI-MYmJQLC&)?wHo!JY;UQ(J?D2N~6f=&-s>~KO2mHziZ~1v8wdp=~IuTt50Wt ztt;C8ZvCO>+`Ibf#JLxjm45E?-k~nFVo_M5JCm~HEQ`h5$7XrPhikFzc{$_weXVbt zo!?v5>839*R}Aj9X=>f4{_#SzP{|RVCrdxRJHM=tk0syx`_Z2t-xtTue0+1#k*0{r zO?4#&&u1#@uD-dy{KdPI>zD0b9l!Ri)U5QFNzcy-`bD7gWYxYnhf2>a^!$+xs>4 z(_F<{jyG(%;Zx(;v!T7Mbb6WIk3YgUGEVTZp7!fm;#s@zVBw+<(X4InYMY^0>*axFG+YCkOj7 zc~*3^Ge&v+`o7~V8?Q#?o{b*K2mkC6I=C=W*sL(YpuO@-sp#((6>SsMpYu6RPB4_M zkDjzvSU@~4e`5dZvs0ot+@4KikqY*4&A8WNY$o>i$~h6u&PDQ!8z(97#YbIkyWzQO z*?lpiWXXvg6AA>JH@}frobvhDr$tHqhN)Zhk9f%lS}%6k%^I0j`lju}p$oT8>YF*X ze@LlSJf@%f=&daGXX9>*%z~PO%I!vs{LI@tZ-1J8ewMy6<41wZ8@=8)8Ln;J!m;4% zeMdRYdnrDq@@zL3I_x|+<)vely0X^Hj6-a4oDv#FkAj^n(|0br*x^{^XmhFW!jCUb zNj%S=9y*u!`1|S9gFSnKh3wc=ryb;2%(&6g+V$cFtLn#w>&!1MHE$D!UFYsqhkisy4d0dsi!q$RQ^4|qiWe{wX;)t7B2>qG0?(^%pd{(2dw ztQLNH`9gn-hwQbv)4SDs8u=$4_0c~P!d3a;(X?pEKS>L>=uXl~e6;n+%1LW)9C0}v z(oz)1xyWa)>@F6ms32i=`HX`5*O|o^1Wi&g*1GslC8(t3Z-sZTaH`H}OO>UID<9{o zoig}zA=7Z$?{}*vd=+w1ac0zROEShc=g-GBRC^`tw7FrjLu(c5 zTCM0G2BG$HQ3mrO&Y$++UM^cIsQ1wCviPE)KMwa=ygl?@WaxLTve!OvSb?9jzH&xz z!*-uzYk1g011C=KbnP(CY}nF2YrS@@S?~oh#d*;^DlQ=#{XH(FzgqC+0i#f}Wd5o} zF^)SFmp$LA$|y8R)vD!tW&Ihx=}VT&>pgz-AH=9=^K27_6?a{=$f9sjJJCm~H9vj|@Oe?G` zdgP`hrlPDkjSe}hl!#S`=VIdZkxgv~ctKK(pFwuR$O zN=#6zk_ub)7xs-oeDwkk-X2XmHmTA#OZdXe{*CiowKqC+*zw3o-6}`LQtQ-wnm=FPb?y89qe_RI`wvb( zJabpo!aFR}oF_lqqONDabfP}v+k#ESuU|en(0n@m+7ZEt59;^Ki`#F%VRLo0e(jWp zoELr1?pShAtncu-QrH?VFx%@4dST0rO8M`yV;TUGuQ^A;aU8``)IP0UknNyJ?GuK+Rz$-_WE}VQ&U-0~&QuQC=Z~i63X#0Cl zmYd4q;A9lkGVRa7WQW^bXI&0Go7KDW#>t2cT&^Bpd@uaEKP7p7QkH?k;heVQnc|Z( z^4OSqc)#B17E5}1_TJK*|Eh`&DfTJ9Ci#T4w>+-DIce|dKTnGbx*993eqBuP=)0L_ z;$Fab?MbO`+_4q>hSIB78EYBOe={SV&8j*vv*?H8hu#T3$|Vva)}{A4Z|-5RwErHU z%*mp6MUO*}_j#4lzvJ41lPhM~+;vI0_}lTv1MBHCxVG5%d%xvt-K#%OH}2-%QtOCw z8<)+KaQwt&V6@u)u?X`e>pP7}(zR(>jth=!O;Rae$zy4~qoh>lcYWv6lgHB{U!M{; z6)_c>?RxQ9jPdke>gAGYCyVF(PdLqbSL3G)e?4=;leNd6?wR+~PVV=DFrQYt)d4Lo zr!QTz`B?PBnbCjqnfwn7D;HHgm^tD8`pt_h4+%3HztrV?)i$MLp?tK{ubX@Kn1AV= zCGhyCpQLYvnu4?(pKYW{lk%QLH-pV>b1Ss6f+d}N`1kW{G5wkH<=emaD?c}OOs?~t z%`zp;ym$H5j~d%E8-HHl_Sq^m|L{7kr_u+CnwD7_cM3eJoR*gL|G0Lpb|#C{n`3FE zO5z4wi7MWYXQzGcI`$^uLFU1nq(xh&DRW!0oH}~tKg+ZuQvDTgCY$%9u-i6?w`-?d zJ;=Xz{tX$KzK&0O4jBcuJIXaQBhGctVQ&_QNO^F=*~s+Loc~(t{57Io6C}hhY%*Cb^RMB6u)^VEzdy#m^xdp_ z@crB+n>+J*4hoBX7Cc#((mZXl&xaqcW;hA-NNXki$<1D0_O*MpLH4vvu_T#q388nw za^|Hy>ToG|zESPQ#VgNFpG^09)TChJ^?BCj1vSqc&nKQy-K${zE2YngyY3;A?35%~ z?$a;1Ph5@Kb8!8}+piDDuUs#7@tKY5PF9hd3m1s1yQH)`?b=#o;RQnyE#<$0F%O1-e3-w>D)JoyLfA+(E;};)$#k^V~UrsskurG%*TTF50 z?p-exmVY$x{8qkXp~gB9@d|&{9|jx~s%A0Gli6sq-{D-fR!*10ik&*suQ@mcnA&JL zJ=(ZT_VRPdrA-q2x-XAUe|J4vXo;rpL|x9931+jrA6)(-ymPjs;*JlGj$ZIrQBaKY zuI#AfFLXKO`IzI8fd;ei<)V2!NsGQ$h$W|Jn{_%Z`S>YS;gYp-))m&Zz9+mrW<2no zDJXPM{N6D)`HUMP@g29qG{p6P9Zv1^5$Q0zc)4+YLjWwytmN!7{j`I({ z8;9EC3ufFnAHZ|E_*^h!*(JdwOaJg!?;gw){H>_C;>4!-7WJ%(lC8ftuY7mk|IW{4 zmXGV+Oy52`T{Hi~oEJNJo6@Hh7RaPL2$HqXa(a}w^lC=1<)4F$T1Wp)78hSR{o{)%@4LYF^FO)}9%DPRT)Fx_RsVnctXZJm~dv z4(t)y;g%lQ>vU`W@imqY_D;AXqPXbUwl=M_@b*Jp6Eehab(s6|)e9&%tZ&&L?|#qW zhxIkT==_x^6_)+{I6SgKAwMH{^#oRak?lH-Tdu0{7ufA zCSSQAQo5`@PHC#PN|VJQQwt&Ui&EV8INqp#K9`>&)_JxycJD90D_+tIgbrBuJ-zy{ zTS?`l!Ivq4nT`JoqlNtT87ux@_5Ak6BjQdk+&8tK5EW@zad7cXmS2JbKa{>_&Hw-6 z-_E+NyU4(3Eg|!R+br$Hb=zh-;_^T{!Ez;XcbgpZNPX=1bLP{&_P0-CToz ztXdzNo@-rA5s!7Aeb`)VxzPKHtcT0fjup1CRs|`&TkXo?o@74pqL=lz%W8)hbNjZY zC3RWb_}P@63&l_9V(&6*`<;6Lgd;Bak^h^xQ zpS3RSWH;G&Z|_-lzOS=bVh`+A`Ryy9^yBPG-QPwdm7IC4>$ zxk~*hTZzmOCwa z^{XI8_nwxLTka;yXLofqGu?c!c=`R893E3_&d1s~Cq%|6b-px>R4~idf3b{7S^h9n z=d)}3cw{`C1D`y-q<>0QXZnd_uj3Uu!Z*!m7iiyHpUb?N_pzv=XZ$iLNmKbfmMQ|< z7uW6QTR5Sw=iVfPU`c7t`s45aJbLWEXkS^Eh^swQkIKD^#bUFKybc}QVY+tj@$-3i zZ@iM?SyXxcfYXOk)zjQ^jx%>E-4nHb*Yu2WVh>ug) z_48~_zwSTCqkLzobkW4w+qXYEXIrzT-l1FF;AmTGn!~)kJ5DO?QBaB&NwYX`+OxZ>~lIX214|J7dXZZ0R^Tk)HV z;oED|>P0crepb#?l2dnEs>t`}nfZQ8(79t3kHY_-Umud;b|T=gEZ6GQj<>$-|9Aht zf9w@UcG)Gz*4KU2{<^Z6&+0?#t%VPGHeP+nXZ1os`ix1y-q6;^x57U!TXAXEg~eA6 zYY9v_C_dq+cz{>APrS_?&87MZ-TDU#-KSbl*t~4B?w9K&*AB-YziIS?Y10p;N41#? zt(WP`z1vcHU1Q2Y)ywky({F95_Ild)vb)`S=@-_NkE|B&Rur)pT`Sqv`ft{`svoZ{ zqS@jd#Nr+H=iqT8(z3{CfN_Xm*+Z$~%U&9}AXG+1H@6kKwp%=sSmV zv(9b15Pvz6zg{-|^aJh_kGMO&FKvA{V_(IN%hzHT2e3`|ske#Ay8KRaD%dSkE`i+t zV8`N9vL_-h-xT|mZT0%$`o}qvHH?upj34)HxgdL4oWK0mu56K04<^0rZ}-l zULFE=ORyKnTMduOP z^ZS%jV7GX^1bM6APT*6%Cu?5jaQ`)(`}M>1!fiaDP-v)#k9q+P(A>MGT&V>ozZ^fj z)a>oNpq*g1Xx4(f)n~oxPU9TYxw#AXFWW5l&+6PXa4ZVE_vXF}4$!r`-4^ob&HPuf zus6qx5#zuWm=UO1P{D9hN1g@J*A!PC{xWt~$(69Cz9Xzu_3 literal 0 HcmV?d00001 diff --git a/doc/diagrams/foa-metadata.png b/doc/diagrams/foa-metadata.png new file mode 100644 index 0000000000000000000000000000000000000000..0d2a530fa27194ad1358a0f298c549a885af7599 GIT binary patch literal 5896 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 literal 0 HcmV?d00001 diff --git a/doc/diagrams/foa.png b/doc/diagrams/foa.png new file mode 100644 index 0000000000000000000000000000000000000000..9b3e2362cfb195fcc0d4fc38cbfef33bae32ed0a GIT binary patch literal 3324 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 BZSepA literal 0 HcmV?d00001 diff --git a/doc/unordered/buckets.adoc b/doc/unordered/buckets.adoc index 42ec9189..8a0ea863 100644 --- a/doc/unordered/buckets.adoc +++ b/doc/unordered/buckets.adoc @@ -244,4 +244,69 @@ image::fca.png[align=center] Thus container-wide iteration is turned into traversing the non-empty bucket groups (an operation with constant time complexity) which reduces the time complexity back to `O(size())`. In total, a bucket group is only 4 words in size and it views `sizeof(std::size_t) * CHAR_BIT` buckets meaning that for all common implementations, there's only 4 bits of space overhead per bucket introduced by the bucket groups. -For more information on implementation rationale, read the <>. +A more detailed description of Boost.Unordered's open-addressing implementation is +given in an +https://bannalia.blogspot.com/2022/06/advancing-state-of-art-for.html[external article]. +For more information on implementation rationale, read the +xref:#rationale_boostunordered_multiset_and_boostunordered_multimap[corresponding section]. + +== Open Addressing Implementation + +The diagram shows the basic internal layout of `boost::unordered_flat_map` and +`boost:unordered_flat_set`. + + +[#img-foa-layout] +.Open-addressing layout used by Boost.Unordered. +image::foa.png[align=center] + +As with all open-addressing containers, elements are stored directly into the bucket array. +This array is logically divided into 2^_n_^ _groups_ of 15 elements each. +In addition to the bucket array, there is an associated _metadata array_ with 2^_n_^ +16-byte words. + +[#img-foa-metadata] +.Breakdown of a metadata word. +image::foa-metadata.png[align=center] + +A metadata word is divided into 15 _h_~_i_~ bytes (one for each associated +bucket), and an _overflow byte_ (_ofw_ in the diagram). The value of _h_~_i_~ is: + + - 0 if the corresponding bucket is empty. + - 1 to encode a special empty bucket called a _sentinel_, which is used internally to + stop iteration when the container has been fully traversed. + - If the bucket is occupied, a _reduced hash value_ obtained from the hash value of + the element. + +When looking for an element with hash value _h_, SIMD technologies such as +https://en.wikipedia.org/wiki/SSE2[SSE2] and +https://en.wikipedia.org/wiki/ARM_architecture_family#Advanced_SIMD_(Neon)[Neon] allows us +to very quickly inspect the full metadata word and look for the reduced value of _h_ among all the +15 buckets with just a handful of CPU instructions: non-matching buckets can be +readily discarded, and those whose reduced hash value matches need be inspected via full +comparison with the corresponding element. If the looked-for element is not present, +the overflow byte is inspected: + +- If the bit in the position _h_ mod 8 is zero, lookup terminates (and the +element is not present). +- If the bit is set to 1 (the group has been _overflowed_), further groups are +checked using https://en.wikipedia.org/wiki/Quadratic_probing[_quadratic probing_], and +the process is repeated. + +Insertion is algorithmically similar: empty buckets are located using SIMD, +and when going past a full group its corresponding overflow bit is set to 1. + +In architectures without SIMD support, the logical layout stays the same, but the metadata +word is codified using a technique we call _bit interleaving_: this layout allows us +to emulate SIMD with reasonably good performance using only standard arithmetic and +logical operations . + +[#img-foa-metadata-interleaving] +.Bit-interleaved metadata word. +image::foa-metadata-interleaving.png[align=center] + +A more detailed description of Boost.Unordered's closed-addressing implementation is +given in an +https://bannalia.blogspot.com/2022/11/inside-boostunorderedflatmap.html[external article]. +For more information on implementation rationale, read the +xref:#rationale_boostunordered_flat_set_and_boostunordered_flat_map[corresponding section].