tea-test-dao

<!DOCTYPE html> <html xmlns="http://www.w3.org/1999/xhtml" lang="en"> <head> <meta charset="UTF-8"/> <meta http-equiv="X-UA-Compatible" content="IE=edge"/> <meta name="viewport" content="width=device-width, initial-scale=1.0"/> <meta name="generator" content="Asciidoctor 2.0.17"/> <title>reftable</title> <link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Open+Sans:300,300italic,400,400italic,600,600italic%7CNoto+Serif:400,400italic,700,700italic%7CDroid+Sans+Mono:400,700"/> <style> /*! Asciidoctor default stylesheet | MIT License | https://asciidoctor.org */ /* Uncomment the following line when using as a custom stylesheet */ /* @import "https://fonts.googleapis.com/css?family=Open+Sans:300,300italic,400,400italic,600,600italic%7CNoto+Serif:400,400italic,700,700italic%7CDroid+Sans+Mono:400,700"; */ html{font-family:sans-serif;-webkit-text-size-adjust:100%} a{background:none} a:focus{outline:thin dotted} a:active,a:hover{outline:0} h1{font-size:2em;margin:.67em 0} b,strong{font-weight:bold} abbr{font-size:.9em} abbr[title]{cursor:help;border-bottom:1px dotted #dddddf;text-decoration:none} dfn{font-style:italic} hr{height:0} mark{background:#ff0;color:#000} code,kbd,pre,samp{font-family:monospace;font-size:1em} pre{white-space:pre-wrap} q{quotes:"\201C" "\201D" "\2018" "\2019"} small{font-size:80%} sub,sup{font-size:75%;line-height:0;position:relative;vertical-align:baseline} sup{top:-.5em} sub{bottom:-.25em} img{border:0} svg:not(:root){overflow:hidden} figure{margin:0} audio,video{display:inline-block} audio:not([controls]){display:none;height:0} fieldset{border:1px solid silver;margin:0 2px;padding:.35em .625em .75em} legend{border:0;padding:0} button,input,select,textarea{font-family:inherit;font-size:100%;margin:0} button,input{line-height:normal} button,select{text-transform:none} button,html input[type=button],input[type=reset],input[type=submit]{-webkit-appearance:button;cursor:pointer} button[disabled],html input[disabled]{cursor:default} input[type=checkbox],input[type=radio]{padding:0} button::-moz-focus-inner,input::-moz-focus-inner{border:0;padding:0} textarea{overflow:auto;vertical-align:top} table{border-collapse:collapse;border-spacing:0} *,::before,::after{box-sizing:border-box} html,body{font-size:100%} body{background:#fff;color:rgba(0,0,0,.8);padding:0;margin:0;font-family:"Noto Serif","DejaVu Serif",serif;line-height:1;position:relative;cursor:auto;-moz-tab-size:4;-o-tab-size:4;tab-size:4;word-wrap:anywhere;-moz-osx-font-smoothing:grayscale;-webkit-font-smoothing:antialiased} a:hover{cursor:pointer} img,object,embed{max-width:100%;height:auto} object,embed{height:100%} img{-ms-interpolation-mode:bicubic} .left{float:left!important} .right{float:right!important} .text-left{text-align:left!important} .text-right{text-align:right!important} .text-center{text-align:center!important} .text-justify{text-align:justify!important} .hide{display:none} img,object,svg{display:inline-block;vertical-align:middle} textarea{height:auto;min-height:50px} select{width:100%} .subheader,.admonitionblock td.content>.title,.audioblock>.title,.exampleblock>.title,.imageblock>.title,.listingblock>.title,.literalblock>.title,.stemblock>.title,.openblock>.title,.paragraph>.title,.quoteblock>.title,table.tableblock>.title,.verseblock>.title,.videoblock>.title,.dlist>.title,.olist>.title,.ulist>.title,.qlist>.title,.hdlist>.title{line-height:1.45;color:#7a2518;font-weight:400;margin-top:0;margin-bottom:.25em} div,dl,dt,dd,ul,ol,li,h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6,pre,form,p,blockquote,th,td{margin:0;padding:0} a{color:#2156a5;text-decoration:underline;line-height:inherit} a:hover,a:focus{color:#1d4b8f} a img{border:0} p{line-height:1.6;margin-bottom:1.25em;text-rendering:optimizeLegibility} p aside{font-size:.875em;line-height:1.35;font-style:italic} h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6{font-family:"Open Sans","DejaVu Sans",sans-serif;font-weight:300;font-style:normal;color:#ba3925;text-rendering:optimizeLegibility;margin-top:1em;margin-bottom:.5em;line-height:1.0125em} h1 small,h2 small,h3 small,#toctitle small,.sidebarblock>.content>.title small,h4 small,h5 small,h6 small{font-size:60%;color:#e99b8f;line-height:0} h1{font-size:2.125em} h2{font-size:1.6875em} h3,#toctitle,.sidebarblock>.content>.title{font-size:1.375em} h4,h5{font-size:1.125em} h6{font-size:1em} hr{border:solid #dddddf;border-width:1px 0 0;clear:both;margin:1.25em 0 1.1875em} em,i{font-style:italic;line-height:inherit} strong,b{font-weight:bold;line-height:inherit} small{font-size:60%;line-height:inherit} code{font-family:"Droid Sans Mono","DejaVu Sans Mono",monospace;font-weight:400;color:rgba(0,0,0,.9)} ul,ol,dl{line-height:1.6;margin-bottom:1.25em;list-style-position:outside;font-family:inherit} ul,ol{margin-left:1.5em} ul li ul,ul li ol{margin-left:1.25em;margin-bottom:0} ul.square li ul,ul.circle li ul,ul.disc li ul{list-style:inherit} ul.square{list-style-type:square} ul.circle{list-style-type:circle} ul.disc{list-style-type:disc} ol li ul,ol li ol{margin-left:1.25em;margin-bottom:0} dl dt{margin-bottom:.3125em;font-weight:bold} dl dd{margin-bottom:1.25em} blockquote{margin:0 0 1.25em;padding:.5625em 1.25em 0 1.1875em;border-left:1px solid #ddd} blockquote,blockquote p{line-height:1.6;color:rgba(0,0,0,.85)} @media screen and (min-width:768px){h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6{line-height:1.2} h1{font-size:2.75em} h2{font-size:2.3125em} h3,#toctitle,.sidebarblock>.content>.title{font-size:1.6875em} h4{font-size:1.4375em}} table{background:#fff;margin-bottom:1.25em;border:1px solid #dedede;word-wrap:normal} table thead,table tfoot{background:#f7f8f7} table thead tr th,table thead tr td,table tfoot tr th,table tfoot tr td{padding:.5em .625em .625em;font-size:inherit;color:rgba(0,0,0,.8);text-align:left} table tr th,table tr td{padding:.5625em .625em;font-size:inherit;color:rgba(0,0,0,.8)} table tr.even,table tr.alt{background:#f8f8f7} table thead tr th,table tfoot tr th,table tbody tr td,table tr td,table tfoot tr td{line-height:1.6} h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6{line-height:1.2;word-spacing:-.05em} h1 strong,h2 strong,h3 strong,#toctitle strong,.sidebarblock>.content>.title strong,h4 strong,h5 strong,h6 strong{font-weight:400} .center{margin-left:auto;margin-right:auto} .stretch{width:100%} .clearfix::before,.clearfix::after,.float-group::before,.float-group::after{content:" ";display:table} .clearfix::after,.float-group::after{clear:both} :not(pre).nobreak{word-wrap:normal} :not(pre).nowrap{white-space:nowrap} :not(pre).pre-wrap{white-space:pre-wrap} :not(pre):not([class^=L])>code{font-size:.9375em;font-style:normal!important;letter-spacing:0;padding:.1em .5ex;word-spacing:-.15em;background:#f7f7f8;border-radius:4px;line-height:1.45;text-rendering:optimizeSpeed} pre{color:rgba(0,0,0,.9);font-family:"Droid Sans Mono","DejaVu Sans Mono",monospace;line-height:1.45;text-rendering:optimizeSpeed} pre code,pre pre{color:inherit;font-size:inherit;line-height:inherit} pre>code{display:block} pre.nowrap,pre.nowrap pre{white-space:pre;word-wrap:normal} em em{font-style:normal} strong strong{font-weight:400} .keyseq{color:rgba(51,51,51,.8)} kbd{font-family:"Droid Sans Mono","DejaVu Sans Mono",monospace;display:inline-block;color:rgba(0,0,0,.8);font-size:.65em;line-height:1.45;background:#f7f7f7;border:1px solid #ccc;border-radius:3px;box-shadow:0 1px 0 rgba(0,0,0,.2),inset 0 0 0 .1em #fff;margin:0 .15em;padding:.2em .5em;vertical-align:middle;position:relative;top:-.1em;white-space:nowrap} .keyseq kbd:first-child{margin-left:0} .keyseq kbd:last-child{margin-right:0} .menuseq,.menuref{color:#000} .menuseq b:not(.caret),.menuref{font-weight:inherit} .menuseq{word-spacing:-.02em} .menuseq b.caret{font-size:1.25em;line-height:.8} .menuseq i.caret{font-weight:bold;text-align:center;width:.45em} b.button::before,b.button::after{position:relative;top:-1px;font-weight:400} b.button::before{content:"[";padding:0 3px 0 2px} b.button::after{content:"]";padding:0 2px 0 3px} p a>code:hover{color:rgba(0,0,0,.9)} #header,#content,#footnotes,#footer{width:100%;margin:0 auto;max-width:62.5em;*zoom:1;position:relative;padding-left:.9375em;padding-right:.9375em} #header::before,#header::after,#content::before,#content::after,#footnotes::before,#footnotes::after,#footer::before,#footer::after{content:" ";display:table} #header::after,#content::after,#footnotes::after,#footer::after{clear:both} #content{margin-top:1.25em} #content::before{content:none} #header>h1:first-child{color:rgba(0,0,0,.85);margin-top:2.25rem;margin-bottom:0} #header>h1:first-child+#toc{margin-top:8px;border-top:1px solid #dddddf} #header>h1:only-child,body.toc2 #header>h1:nth-last-child(2){border-bottom:1px solid #dddddf;padding-bottom:8px} #header .details{border-bottom:1px solid #dddddf;line-height:1.45;padding-top:.25em;padding-bottom:.25em;padding-left:.25em;color:rgba(0,0,0,.6);display:flex;flex-flow:row wrap} #header .details span:first-child{margin-left:-.125em} #header .details span.email a{color:rgba(0,0,0,.85)} #header .details br{display:none} #header .details br+span::before{content:"\00a0\2013\00a0"} #header .details br+span.author::before{content:"\00a0\22c5\00a0";color:rgba(0,0,0,.85)} #header .details br+span#revremark::before{content:"\00a0|\00a0"} #header #revnumber{text-transform:capitalize} #header #revnumber::after{content:"\00a0"} #content>h1:first-child:not([class]){color:rgba(0,0,0,.85);border-bottom:1px solid #dddddf;padding-bottom:8px;margin-top:0;padding-top:1rem;margin-bottom:1.25rem} #toc{border-bottom:1px solid #e7e7e9;padding-bottom:.5em} #toc>ul{margin-left:.125em} #toc ul.sectlevel0>li>a{font-style:italic} #toc ul.sectlevel0 ul.sectlevel1{margin:.5em 0} #toc ul{font-family:"Open Sans","DejaVu Sans",sans-serif;list-style-type:none} #toc li{line-height:1.3334;margin-top:.3334em} #toc a{text-decoration:none} #toc a:active{text-decoration:underline} #toctitle{color:#7a2518;font-size:1.2em} @media screen and (min-width:768px){#toctitle{font-size:1.375em} body.toc2{padding-left:15em;padding-right:0} #toc.toc2{margin-top:0!important;background:#f8f8f7;position:fixed;width:15em;left:0;top:0;border-right:1px solid #e7e7e9;border-top-width:0!important;border-bottom-width:0!important;z-index:1000;padding:1.25em 1em;height:100%;overflow:auto} #toc.toc2 #toctitle{margin-top:0;margin-bottom:.8rem;font-size:1.2em} #toc.toc2>ul{font-size:.9em;margin-bottom:0} #toc.toc2 ul ul{margin-left:0;padding-left:1em} #toc.toc2 ul.sectlevel0 ul.sectlevel1{padding-left:0;margin-top:.5em;margin-bottom:.5em} body.toc2.toc-right{padding-left:0;padding-right:15em} body.toc2.toc-right #toc.toc2{border-right-width:0;border-left:1px solid #e7e7e9;left:auto;right:0}} @media screen and (min-width:1280px){body.toc2{padding-left:20em;padding-right:0} #toc.toc2{width:20em} #toc.toc2 #toctitle{font-size:1.375em} #toc.toc2>ul{font-size:.95em} #toc.toc2 ul ul{padding-left:1.25em} body.toc2.toc-right{padding-left:0;padding-right:20em}} #content #toc{border:1px solid #e0e0dc;margin-bottom:1.25em;padding:1.25em;background:#f8f8f7;border-radius:4px} #content #toc>:first-child{margin-top:0} #content #toc>:last-child{margin-bottom:0} #footer{max-width:none;background:rgba(0,0,0,.8);padding:1.25em} #footer-text{color:hsla(0,0%,100%,.8);line-height:1.44} #content{margin-bottom:.625em} .sect1{padding-bottom:.625em} @media screen and (min-width:768px){#content{margin-bottom:1.25em} .sect1{padding-bottom:1.25em}} .sect1:last-child{padding-bottom:0} .sect1+.sect1{border-top:1px solid #e7e7e9} #content h1>a.anchor,h2>a.anchor,h3>a.anchor,#toctitle>a.anchor,.sidebarblock>.content>.title>a.anchor,h4>a.anchor,h5>a.anchor,h6>a.anchor{position:absolute;z-index:1001;width:1.5ex;margin-left:-1.5ex;display:block;text-decoration:none!important;visibility:hidden;text-align:center;font-weight:400} #content h1>a.anchor::before,h2>a.anchor::before,h3>a.anchor::before,#toctitle>a.anchor::before,.sidebarblock>.content>.title>a.anchor::before,h4>a.anchor::before,h5>a.anchor::before,h6>a.anchor::before{content:"\00A7";font-size:.85em;display:block;padding-top:.1em} #content h1:hover>a.anchor,#content h1>a.anchor:hover,h2:hover>a.anchor,h2>a.anchor:hover,h3:hover>a.anchor,#toctitle:hover>a.anchor,.sidebarblock>.content>.title:hover>a.anchor,h3>a.anchor:hover,#toctitle>a.anchor:hover,.sidebarblock>.content>.title>a.anchor:hover,h4:hover>a.anchor,h4>a.anchor:hover,h5:hover>a.anchor,h5>a.anchor:hover,h6:hover>a.anchor,h6>a.anchor:hover{visibility:visible} #content h1>a.link,h2>a.link,h3>a.link,#toctitle>a.link,.sidebarblock>.content>.title>a.link,h4>a.link,h5>a.link,h6>a.link{color:#ba3925;text-decoration:none} #content h1>a.link:hover,h2>a.link:hover,h3>a.link:hover,#toctitle>a.link:hover,.sidebarblock>.content>.title>a.link:hover,h4>a.link:hover,h5>a.link:hover,h6>a.link:hover{color:#a53221} details,.audioblock,.imageblock,.literalblock,.listingblock,.stemblock,.videoblock{margin-bottom:1.25em} details{margin-left:1.25rem} details>summary{cursor:pointer;display:block;position:relative;line-height:1.6;margin-bottom:.625rem;outline:none;-webkit-tap-highlight-color:transparent} details>summary::-webkit-details-marker{display:none} details>summary::before{content:"";border:solid transparent;border-left:solid;border-width:.3em 0 .3em .5em;position:absolute;top:.5em;left:-1.25rem;transform:translateX(15%)} details[open]>summary::before{border:solid transparent;border-top:solid;border-width:.5em .3em 0;transform:translateY(15%)} details>summary::after{content:"";width:1.25rem;height:1em;position:absolute;top:.3em;left:-1.25rem} .admonitionblock td.content>.title,.audioblock>.title,.exampleblock>.title,.imageblock>.title,.listingblock>.title,.literalblock>.title,.stemblock>.title,.openblock>.title,.paragraph>.title,.quoteblock>.title,table.tableblock>.title,.verseblock>.title,.videoblock>.title,.dlist>.title,.olist>.title,.ulist>.title,.qlist>.title,.hdlist>.title{text-rendering:optimizeLegibility;text-align:left;font-family:"Noto Serif","DejaVu Serif",serif;font-size:1rem;font-style:italic} table.tableblock.fit-content>caption.title{white-space:nowrap;width:0} .paragraph.lead>p,#preamble>.sectionbody>[class=paragraph]:first-of-type p{font-size:1.21875em;line-height:1.6;color:rgba(0,0,0,.85)} .admonitionblock>table{border-collapse:separate;border:0;background:none;width:100%} .admonitionblock>table td.icon{text-align:center;width:80px} .admonitionblock>table td.icon img{max-width:none} .admonitionblock>table td.icon .title{font-weight:bold;font-family:"Open Sans","DejaVu Sans",sans-serif;text-transform:uppercase} .admonitionblock>table td.content{padding-left:1.125em;padding-right:1.25em;border-left:1px solid #dddddf;color:rgba(0,0,0,.6);word-wrap:anywhere} .admonitionblock>table td.content>:last-child>:last-child{margin-bottom:0} .exampleblock>.content{border:1px solid #e6e6e6;margin-bottom:1.25em;padding:1.25em;background:#fff;border-radius:4px} .exampleblock>.content>:first-child{margin-top:0} .exampleblock>.content>:last-child{margin-bottom:0} .sidebarblock{border:1px solid #dbdbd6;margin-bottom:1.25em;padding:1.25em;background:#f3f3f2;border-radius:4px} .sidebarblock>:first-child{margin-top:0} .sidebarblock>:last-child{margin-bottom:0} .sidebarblock>.content>.title{color:#7a2518;margin-top:0;text-align:center} .exampleblock>.content>:last-child>:last-child,.exampleblock>.content .olist>ol>li:last-child>:last-child,.exampleblock>.content .ulist>ul>li:last-child>:last-child,.exampleblock>.content .qlist>ol>li:last-child>:last-child,.sidebarblock>.content>:last-child>:last-child,.sidebarblock>.content .olist>ol>li:last-child>:last-child,.sidebarblock>.content .ulist>ul>li:last-child>:last-child,.sidebarblock>.content .qlist>ol>li:last-child>:last-child{margin-bottom:0} .literalblock pre,.listingblock>.content>pre{border-radius:4px;overflow-x:auto;padding:1em;font-size:.8125em} @media screen and (min-width:768px){.literalblock pre,.listingblock>.content>pre{font-size:.90625em}} @media screen and (min-width:1280px){.literalblock pre,.listingblock>.content>pre{font-size:1em}} .literalblock pre,.listingblock>.content>pre:not(.highlight),.listingblock>.content>pre[class=highlight],.listingblock>.content>pre[class^="highlight "]{background:#f7f7f8} .literalblock.output pre{color:#f7f7f8;background:rgba(0,0,0,.9)} .listingblock>.content{position:relative} .listingblock code[data-lang]::before{display:none;content:attr(data-lang);position:absolute;font-size:.75em;top:.425rem;right:.5rem;line-height:1;text-transform:uppercase;color:inherit;opacity:.5} .listingblock:hover code[data-lang]::before{display:block} .listingblock.terminal pre .command::before{content:attr(data-prompt);padding-right:.5em;color:inherit;opacity:.5} .listingblock.terminal pre .command:not([data-prompt])::before{content:"$"} .listingblock pre.highlightjs{padding:0} .listingblock pre.highlightjs>code{padding:1em;border-radius:4px} .listingblock pre.prettyprint{border-width:0} .prettyprint{background:#f7f7f8} pre.prettyprint .linenums{line-height:1.45;margin-left:2em} pre.prettyprint li{background:none;list-style-type:inherit;padding-left:0} pre.prettyprint li code[data-lang]::before{opacity:1} pre.prettyprint li:not(:first-child) code[data-lang]::before{display:none} table.linenotable{border-collapse:separate;border:0;margin-bottom:0;background:none} table.linenotable td[class]{color:inherit;vertical-align:top;padding:0;line-height:inherit;white-space:normal} table.linenotable td.code{padding-left:.75em} table.linenotable td.linenos,pre.pygments .linenos{border-right:1px solid;opacity:.35;padding-right:.5em;-webkit-user-select:none;-moz-user-select:none;-ms-user-select:none;user-select:none} pre.pygments span.linenos{display:inline-block;margin-right:.75em} .quoteblock{margin:0 1em 1.25em 1.5em;display:table} .quoteblock:not(.excerpt)>.title{margin-left:-1.5em;margin-bottom:.75em} .quoteblock blockquote,.quoteblock p{color:rgba(0,0,0,.85);font-size:1.15rem;line-height:1.75;word-spacing:.1em;letter-spacing:0;font-style:italic;text-align:justify} .quoteblock blockquote{margin:0;padding:0;border:0} .quoteblock blockquote::before{content:"\201c";float:left;font-size:2.75em;font-weight:bold;line-height:.6em;margin-left:-.6em;color:#7a2518;text-shadow:0 1px 2px rgba(0,0,0,.1)} .quoteblock blockquote>.paragraph:last-child p{margin-bottom:0} .quoteblock .attribution{margin-top:.75em;margin-right:.5ex;text-align:right} .verseblock{margin:0 1em 1.25em} .verseblock pre{font-family:"Open Sans","DejaVu Sans",sans-serif;font-size:1.15rem;color:rgba(0,0,0,.85);font-weight:300;text-rendering:optimizeLegibility} .verseblock pre strong{font-weight:400} .verseblock .attribution{margin-top:1.25rem;margin-left:.5ex} .quoteblock .attribution,.verseblock .attribution{font-size:.9375em;line-height:1.45;font-style:italic} .quoteblock .attribution br,.verseblock .attribution br{display:none} .quoteblock .attribution cite,.verseblock .attribution cite{display:block;letter-spacing:-.025em;color:rgba(0,0,0,.6)} .quoteblock.abstract blockquote::before,.quoteblock.excerpt blockquote::before,.quoteblock .quoteblock blockquote::before{display:none} .quoteblock.abstract blockquote,.quoteblock.abstract p,.quoteblock.excerpt blockquote,.quoteblock.excerpt p,.quoteblock .quoteblock blockquote,.quoteblock .quoteblock p{line-height:1.6;word-spacing:0} .quoteblock.abstract{margin:0 1em 1.25em;display:block} .quoteblock.abstract>.title{margin:0 0 .375em;font-size:1.15em;text-align:center} .quoteblock.excerpt>blockquote,.quoteblock .quoteblock{padding:0 0 .25em 1em;border-left:.25em solid #dddddf} .quoteblock.excerpt,.quoteblock .quoteblock{margin-left:0} .quoteblock.excerpt blockquote,.quoteblock.excerpt p,.quoteblock .quoteblock blockquote,.quoteblock .quoteblock p{color:inherit;font-size:1.0625rem} .quoteblock.excerpt .attribution,.quoteblock .quoteblock .attribution{color:inherit;font-size:.85rem;text-align:left;margin-right:0} p.tableblock:last-child{margin-bottom:0} td.tableblock>.content{margin-bottom:1.25em;word-wrap:anywhere} td.tableblock>.content>:last-child{margin-bottom:-1.25em} table.tableblock,th.tableblock,td.tableblock{border:0 solid #dedede} table.grid-all>*>tr>*{border-width:1px} table.grid-cols>*>tr>*{border-width:0 1px} table.grid-rows>*>tr>*{border-width:1px 0} table.frame-all{border-width:1px} table.frame-ends{border-width:1px 0} table.frame-sides{border-width:0 1px} table.frame-none>colgroup+*>:first-child>*,table.frame-sides>colgroup+*>:first-child>*{border-top-width:0} table.frame-none>:last-child>:last-child>*,table.frame-sides>:last-child>:last-child>*{border-bottom-width:0} table.frame-none>*>tr>:first-child,table.frame-ends>*>tr>:first-child{border-left-width:0} table.frame-none>*>tr>:last-child,table.frame-ends>*>tr>:last-child{border-right-width:0} table.stripes-all>*>tr,table.stripes-odd>*>tr:nth-of-type(odd),table.stripes-even>*>tr:nth-of-type(even),table.stripes-hover>*>tr:hover{background:#f8f8f7} th.halign-left,td.halign-left{text-align:left} th.halign-right,td.halign-right{text-align:right} th.halign-center,td.halign-center{text-align:center} th.valign-top,td.valign-top{vertical-align:top} th.valign-bottom,td.valign-bottom{vertical-align:bottom} th.valign-middle,td.valign-middle{vertical-align:middle} table thead th,table tfoot th{font-weight:bold} tbody tr th{background:#f7f8f7} tbody tr th,tbody tr th p,tfoot tr th,tfoot tr th p{color:rgba(0,0,0,.8);font-weight:bold} p.tableblock>code:only-child{background:none;padding:0} p.tableblock{font-size:1em} ol{margin-left:1.75em} ul li ol{margin-left:1.5em} dl dd{margin-left:1.125em} dl dd:last-child,dl dd:last-child>:last-child{margin-bottom:0} li p,ul dd,ol dd,.olist .olist,.ulist .ulist,.ulist .olist,.olist .ulist{margin-bottom:.625em} ul.checklist,ul.none,ol.none,ul.no-bullet,ol.no-bullet,ol.unnumbered,ul.unstyled,ol.unstyled{list-style-type:none} ul.no-bullet,ol.no-bullet,ol.unnumbered{margin-left:.625em} ul.unstyled,ol.unstyled{margin-left:0} li>p:empty:only-child::before{content:"";display:inline-block} ul.checklist>li>p:first-child{margin-left:-1em} ul.checklist>li>p:first-child>.fa-square-o:first-child,ul.checklist>li>p:first-child>.fa-check-square-o:first-child{width:1.25em;font-size:.8em;position:relative;bottom:.125em} ul.checklist>li>p:first-child>input[type=checkbox]:first-child{margin-right:.25em} ul.inline{display:flex;flex-flow:row wrap;list-style:none;margin:0 0 .625em -1.25em} ul.inline>li{margin-left:1.25em} .unstyled dl dt{font-weight:400;font-style:normal} ol.arabic{list-style-type:decimal} ol.decimal{list-style-type:decimal-leading-zero} ol.loweralpha{list-style-type:lower-alpha} ol.upperalpha{list-style-type:upper-alpha} ol.lowerroman{list-style-type:lower-roman} ol.upperroman{list-style-type:upper-roman} ol.lowergreek{list-style-type:lower-greek} .hdlist>table,.colist>table{border:0;background:none} .hdlist>table>tbody>tr,.colist>table>tbody>tr{background:none} td.hdlist1,td.hdlist2{vertical-align:top;padding:0 .625em} td.hdlist1{font-weight:bold;padding-bottom:1.25em} td.hdlist2{word-wrap:anywhere} .literalblock+.colist,.listingblock+.colist{margin-top:-.5em} .colist td:not([class]):first-child{padding:.4em .75em 0;line-height:1;vertical-align:top} .colist td:not([class]):first-child img{max-width:none} .colist td:not([class]):last-child{padding:.25em 0} .thumb,.th{line-height:0;display:inline-block;border:4px solid #fff;box-shadow:0 0 0 1px #ddd} .imageblock.left{margin:.25em .625em 1.25em 0} .imageblock.right{margin:.25em 0 1.25em .625em} .imageblock>.title{margin-bottom:0} .imageblock.thumb,.imageblock.th{border-width:6px} .imageblock.thumb>.title,.imageblock.th>.title{padding:0 .125em} .image.left,.image.right{margin-top:.25em;margin-bottom:.25em;display:inline-block;line-height:0} .image.left{margin-right:.625em} .image.right{margin-left:.625em} a.image{text-decoration:none;display:inline-block} a.image object{pointer-events:none} sup.footnote,sup.footnoteref{font-size:.875em;position:static;vertical-align:super} sup.footnote a,sup.footnoteref a{text-decoration:none} sup.footnote a:active,sup.footnoteref a:active{text-decoration:underline} #footnotes{padding-top:.75em;padding-bottom:.75em;margin-bottom:.625em} #footnotes hr{width:20%;min-width:6.25em;margin:-.25em 0 .75em;border-width:1px 0 0} #footnotes .footnote{padding:0 .375em 0 .225em;line-height:1.3334;font-size:.875em;margin-left:1.2em;margin-bottom:.2em} #footnotes .footnote a:first-of-type{font-weight:bold;text-decoration:none;margin-left:-1.05em} #footnotes .footnote:last-of-type{margin-bottom:0} #content #footnotes{margin-top:-.625em;margin-bottom:0;padding:.75em 0} div.unbreakable{page-break-inside:avoid} .big{font-size:larger} .small{font-size:smaller} .underline{text-decoration:underline} .overline{text-decoration:overline} .line-through{text-decoration:line-through} .aqua{color:#00bfbf} .aqua-background{background:#00fafa} .black{color:#000} .black-background{background:#000} .blue{color:#0000bf} .blue-background{background:#0000fa} .fuchsia{color:#bf00bf} .fuchsia-background{background:#fa00fa} .gray{color:#606060} .gray-background{background:#7d7d7d} .green{color:#006000} .green-background{background:#007d00} .lime{color:#00bf00} .lime-background{background:#00fa00} .maroon{color:#600000} .maroon-background{background:#7d0000} .navy{color:#000060} .navy-background{background:#00007d} .olive{color:#606000} .olive-background{background:#7d7d00} .purple{color:#600060} .purple-background{background:#7d007d} .red{color:#bf0000} .red-background{background:#fa0000} .silver{color:#909090} .silver-background{background:#bcbcbc} .teal{color:#006060} .teal-background{background:#007d7d} .white{color:#bfbfbf} .white-background{background:#fafafa} .yellow{color:#bfbf00} .yellow-background{background:#fafa00} span.icon>.fa{cursor:default} a span.icon>.fa{cursor:inherit} .admonitionblock td.icon [class^="fa icon-"]{font-size:2.5em;text-shadow:1px 1px 2px rgba(0,0,0,.5);cursor:default} .admonitionblock td.icon .icon-note::before{content:"\f05a";color:#19407c} .admonitionblock td.icon .icon-tip::before{content:"\f0eb";text-shadow:1px 1px 2px rgba(155,155,0,.8);color:#111} .admonitionblock td.icon .icon-warning::before{content:"\f071";color:#bf6900} .admonitionblock td.icon .icon-caution::before{content:"\f06d";color:#bf3400} .admonitionblock td.icon .icon-important::before{content:"\f06a";color:#bf0000} .conum[data-value]{display:inline-block;color:#fff!important;background:rgba(0,0,0,.8);border-radius:50%;text-align:center;font-size:.75em;width:1.67em;height:1.67em;line-height:1.67em;font-family:"Open Sans","DejaVu Sans",sans-serif;font-style:normal;font-weight:bold} .conum[data-value] *{color:#fff!important} .conum[data-value]+b{display:none} .conum[data-value]::after{content:attr(data-value)} pre .conum[data-value]{position:relative;top:-.125em} b.conum *{color:inherit!important} .conum:not([data-value]):empty{display:none} dt,th.tableblock,td.content,div.footnote{text-rendering:optimizeLegibility} h1,h2,p,td.content,span.alt,summary{letter-spacing:-.01em} p strong,td.content strong,div.footnote strong{letter-spacing:-.005em} p,blockquote,dt,td.content,span.alt,summary{font-size:1.0625rem} p{margin-bottom:1.25rem} .sidebarblock p,.sidebarblock dt,.sidebarblock td.content,p.tableblock{font-size:1em} .exampleblock>.content{background:#fffef7;border-color:#e0e0dc;box-shadow:0 1px 4px #e0e0dc} .print-only{display:none!important} @page{margin:1.25cm .75cm} @media print{*{box-shadow:none!important;text-shadow:none!important} html{font-size:80%} a{color:inherit!important;text-decoration:underline!important} a.bare,a[href^="#"],a[href^="mailto:"]{text-decoration:none!important} a[href^="http:"]:not(.bare)::after,a[href^="https:"]:not(.bare)::after{content:"(" attr(href) ")";display:inline-block;font-size:.875em;padding-left:.25em} abbr[title]{border-bottom:1px dotted} abbr[title]::after{content:" (" attr(title) ")"} pre,blockquote,tr,img,object,svg{page-break-inside:avoid} thead{display:table-header-group} svg{max-width:100%} p,blockquote,dt,td.content{font-size:1em;orphans:3;widows:3} h2,h3,#toctitle,.sidebarblock>.content>.title{page-break-after:avoid} #header,#content,#footnotes,#footer{max-width:none} #toc,.sidebarblock,.exampleblock>.content{background:none!important} #toc{border-bottom:1px solid #dddddf!important;padding-bottom:0!important} body.book #header{text-align:center} body.book #header>h1:first-child{border:0!important;margin:2.5em 0 1em} body.book #header .details{border:0!important;display:block;padding:0!important} body.book #header .details span:first-child{margin-left:0!important} body.book #header .details br{display:block} body.book #header .details br+span::before{content:none!important} body.book #toc{border:0!important;text-align:left!important;padding:0!important;margin:0!important} body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-break-before:always} .listingblock code[data-lang]::before{display:block} #footer{padding:0 .9375em} .hide-on-print{display:none!important} .print-only{display:block!important} .hide-for-print{display:none!important} .show-for-print{display:inherit!important}} @media amzn-kf8,print{#header>h1:first-child{margin-top:1.25rem} .sect1{padding:0!important} .sect1+.sect1{border:0} #footer{background:none} #footer-text{color:rgba(0,0,0,.6);font-size:.9em}} @media amzn-kf8{#header,#content,#footnotes,#footer{padding:0}} </style> </head> <body class="article"> <div id="header"> </div> <div id="content"> <div class="sect1"> <h2 id="_reftable">reftable</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_overview">Overview</h3> <div class="sect3"> <h4 id="_problem_statement">Problem statement</h4> <div class="paragraph"> <p>Some repositories contain a lot of references (e.g. android at 866k, rails at 31k). The existing packed-refs format takes up a lot of space (e.g. 62M), and does not scale with additional references. Lookup of a single reference requires linearly scanning the file.</p> </div> <div class="paragraph"> <p>Atomic pushes modifying multiple references require copying the entire packed-refs file, which can be a considerable amount of data moved (e.g. 62M in, 62M out) for even small transactions (2 refs modified).</p> </div> <div class="paragraph"> <p>Repositories with many loose references occupy a large number of disk blocks from the local file system, as each reference is its own file storing 41 bytes (and another file for the corresponding reflog). This negatively affects the number of inodes available when a large number of repositories are stored on the same filesystem. Readers can be penalized due to the larger number of syscalls required to traverse and read the <code>$GIT_DIR/refs</code> directory.</p> </div> </div> <div class="sect3"> <h4 id="_objectives">Objectives</h4> <div class="ulist"> <ul> <li> <p>Near constant time lookup for any single reference, even when the repository is cold and not in process or kernel cache.</p> </li> <li> <p>Near constant time verification if an object name is referred to by at least one reference (for allow-tip-sha1-in-want).</p> </li> <li> <p>Efficient enumeration of an entire namespace, such as <code>refs/tags/</code>.</p> </li> <li> <p>Support atomic push with <code>O(size_of_update)</code> operations.</p> </li> <li> <p>Combine reflog storage with ref storage for small transactions.</p> </li> <li> <p>Separate reflog storage for base refs and historical logs.</p> </li> </ul> </div> </div> <div class="sect3"> <h4 id="_description">Description</h4> <div class="paragraph"> <p>A reftable file is a portable binary file format customized for reference storage. References are sorted, enabling linear scans, binary search lookup, and range scans.</p> </div> <div class="paragraph"> <p>Storage in the file is organized into variable sized blocks. Prefix compression is used within a single block to reduce disk space. Block size and alignment are tunable by the writer.</p> </div> </div> <div class="sect3"> <h4 id="_performance">Performance</h4> <div class="paragraph"> <p>Space used, packed-refs vs. reftable:</p> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 16.6666%;"/> <col style="width: 16.6666%;"/> <col style="width: 16.6666%;"/> <col style="width: 16.6666%;"/> <col style="width: 16.6666%;"/> <col style="width: 16.667%;"/> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">repository</th> <th class="tableblock halign-right valign-top">packed-refs</th> <th class="tableblock halign-right valign-top">reftable</th> <th class="tableblock halign-right valign-top">% original</th> <th class="tableblock halign-right valign-top">avg ref</th> <th class="tableblock halign-right valign-top">avg obj</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">android</p></td> <td class="tableblock halign-right valign-top"><p class="tableblock">62.2 M</p></td> <td class="tableblock halign-right valign-top"><p class="tableblock">36.1 M</p></td> <td class="tableblock halign-right valign-top"><p class="tableblock">58.0%</p></td> <td class="tableblock halign-right valign-top"><p class="tableblock">33 bytes</p></td> <td class="tableblock halign-right valign-top"><p class="tableblock">5 bytes</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">rails</p></td> <td class="tableblock halign-right valign-top"><p class="tableblock">1.8 M</p></td> <td class="tableblock halign-right valign-top"><p class="tableblock">1.1 M</p></td> <td class="tableblock halign-right valign-top"><p class="tableblock">57.7%</p></td> <td class="tableblock halign-right valign-top"><p class="tableblock">29 bytes</p></td> <td class="tableblock halign-right valign-top"><p class="tableblock">4 bytes</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">git</p></td> <td class="tableblock halign-right valign-top"><p class="tableblock">78.7 K</p></td> <td class="tableblock halign-right valign-top"><p class="tableblock">48.1 K</p></td> <td class="tableblock halign-right valign-top"><p class="tableblock">61.0%</p></td> <td class="tableblock halign-right valign-top"><p class="tableblock">50 bytes</p></td> <td class="tableblock halign-right valign-top"><p class="tableblock">4 bytes</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">git (heads)</p></td> <td class="tableblock halign-right valign-top"><p class="tableblock">332 b</p></td> <td class="tableblock halign-right valign-top"><p class="tableblock">269 b</p></td> <td class="tableblock halign-right valign-top"><p class="tableblock">81.0%</p></td> <td class="tableblock halign-right valign-top"><p class="tableblock">33 bytes</p></td> <td class="tableblock halign-right valign-top"><p class="tableblock">0 bytes</p></td> </tr> </tbody> </table> <div class="paragraph"> <p>Scan (read 866k refs), by reference name lookup (single ref from 866k refs), and by SHA-1 lookup (refs with that SHA-1, from 866k refs):</p> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 20%;"/> <col style="width: 20%;"/> <col style="width: 20%;"/> <col style="width: 20%;"/> <col style="width: 20%;"/> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">format</th> <th class="tableblock halign-right valign-top">cache</th> <th class="tableblock halign-right valign-top">scan</th> <th class="tableblock halign-right valign-top">by name</th> <th class="tableblock halign-right valign-top">by SHA-1</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">packed-refs</p></td> <td class="tableblock halign-right valign-top"><p class="tableblock">cold</p></td> <td class="tableblock halign-right valign-top"><p class="tableblock">402 ms</p></td> <td class="tableblock halign-right valign-top"><p class="tableblock">409,660.1 usec</p></td> <td class="tableblock halign-right valign-top"><p class="tableblock">412,535.8 usec</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">packed-refs</p></td> <td class="tableblock halign-right valign-top"><p class="tableblock">hot</p></td> <td class="tableblock halign-right valign-top"></td> <td class="tableblock halign-right valign-top"><p class="tableblock">6,844.6 usec</p></td> <td class="tableblock halign-right valign-top"><p class="tableblock">20,110.1 usec</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">reftable</p></td> <td class="tableblock halign-right valign-top"><p class="tableblock">cold</p></td> <td class="tableblock halign-right valign-top"><p class="tableblock">112 ms</p></td> <td class="tableblock halign-right valign-top"><p class="tableblock">33.9 usec</p></td> <td class="tableblock halign-right valign-top"><p class="tableblock">323.2 usec</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">reftable</p></td> <td class="tableblock halign-right valign-top"><p class="tableblock">hot</p></td> <td class="tableblock halign-right valign-top"></td> <td class="tableblock halign-right valign-top"><p class="tableblock">20.2 usec</p></td> <td class="tableblock halign-right valign-top"><p class="tableblock">320.8 usec</p></td> </tr> </tbody> </table> <div class="paragraph"> <p>Space used for 149,932 log entries for 43,061 refs, reflog vs. reftable:</p> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 33.3333%;"/> <col style="width: 33.3333%;"/> <col style="width: 33.3334%;"/> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">format</th> <th class="tableblock halign-right valign-top">size</th> <th class="tableblock halign-right valign-top">avg entry</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">$GIT_DIR/logs</p></td> <td class="tableblock halign-right valign-top"><p class="tableblock">173 M</p></td> <td class="tableblock halign-right valign-top"><p class="tableblock">1209 bytes</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">reftable</p></td> <td class="tableblock halign-right valign-top"><p class="tableblock">5 M</p></td> <td class="tableblock halign-right valign-top"><p class="tableblock">37 bytes</p></td> </tr> </tbody> </table> </div> </div> <div class="sect2"> <h3 id="_details">Details</h3> <div class="sect3"> <h4 id="_peeling">Peeling</h4> <div class="paragraph"> <p>References stored in a reftable are peeled, a record for an annotated (or signed) tag records both the tag object, and the object it refers to. This is analogous to storage in the packed-refs format.</p> </div> </div> <div class="sect3"> <h4 id="_reference_name_encoding">Reference name encoding</h4> <div class="paragraph"> <p>Reference names are an uninterpreted sequence of bytes that must pass <a href="../git-check-ref-format.html">git-check-ref-format(1)</a> as a valid reference name.</p> </div> </div> <div class="sect3"> <h4 id="_key_unicity">Key unicity</h4> <div class="paragraph"> <p>Each entry must have a unique key; repeated keys are disallowed.</p> </div> </div> <div class="sect3"> <h4 id="_network_byte_order">Network byte order</h4> <div class="paragraph"> <p>All multi-byte, fixed width fields are in network byte order.</p> </div> </div> <div class="sect3"> <h4 id="_varint_encoding">Varint encoding</h4> <div class="paragraph"> <p>Varint encoding is identical to the ofs-delta encoding method used within pack files.</p> </div> <div class="paragraph"> <p>Decoder works as follows:</p> </div> <div class="literalblock"> <div class="content"> <pre>val = buf[ptr] & 0x7f while (buf[ptr] & 0x80) { ptr++ val = ((val + 1) << 7) | (buf[ptr] & 0x7f) }</pre> </div> </div> </div> <div class="sect3"> <h4 id="_ordering">Ordering</h4> <div class="paragraph"> <p>Blocks are lexicographically ordered by their first reference.</p> </div> </div> <div class="sect3"> <h4 id="_directoryfile_conflicts">Directory/file conflicts</h4> <div class="paragraph"> <p>The reftable format accepts both <code>refs/heads/foo</code> and <code>refs/heads/foo/bar</code> as distinct references.</p> </div> <div class="paragraph"> <p>This property is useful for retaining log records in reftable, but may confuse versions of Git using <code>$GIT_DIR/refs</code> directory tree to maintain references. Users of reftable may choose to continue to reject <code>foo</code> and <code>foo/bar</code> type conflicts to prevent problems for peers.</p> </div> </div> </div> <div class="sect2"> <h3 id="_file_format">File format</h3> <div class="sect3"> <h4 id="_structure">Structure</h4> <div class="paragraph"> <p>A reftable file has the following high-level structure:</p> </div> <div class="literalblock"> <div class="content"> <pre>first_block { header first_ref_block } ref_block* ref_index* obj_block* obj_index* log_block* log_index* footer</pre> </div> </div> <div class="paragraph"> <p>A log-only file omits the <code>ref_block</code>, <code>ref_index</code>, <code>obj_block</code> and <code>obj_index</code> sections, containing only the file header and log block:</p> </div> <div class="literalblock"> <div class="content"> <pre>first_block { header } log_block* log_index* footer</pre> </div> </div> <div class="paragraph"> <p>In a log-only file, the first log block immediately follows the file header, without padding to block alignment.</p> </div> </div> <div class="sect3"> <h4 id="_block_size">Block size</h4> <div class="paragraph"> <p>The file’s block size is arbitrarily determined by the writer, and does not have to be a power of 2. The block size must be larger than the longest reference name or log entry used in the repository, as references cannot span blocks.</p> </div> <div class="paragraph"> <p>Powers of two that are friendly to the virtual memory system or filesystem (such as 4k or 8k) are recommended. Larger sizes (64k) can yield better compression, with a possible increased cost incurred by readers during access.</p> </div> <div class="paragraph"> <p>The largest block size is <code>16777215</code> bytes (15.99 MiB).</p> </div> </div> <div class="sect3"> <h4 id="_block_alignment">Block alignment</h4> <div class="paragraph"> <p>Writers may choose to align blocks at multiples of the block size by including <code>padding</code> filled with NUL bytes at the end of a block to round out to the chosen alignment. When alignment is used, writers must specify the alignment with the file header’s <code>block_size</code> field.</p> </div> <div class="paragraph"> <p>Block alignment is not required by the file format. Unaligned files must set <code>block_size = 0</code> in the file header, and omit <code>padding</code>. Unaligned files with more than one ref block must include the <a href="#Ref-index">ref index</a> to support fast lookup. Readers must be able to read both aligned and non-aligned files.</p> </div> <div class="paragraph"> <p>Very small files (e.g. a single ref block) may omit <code>padding</code> and the ref index to reduce total file size.</p> </div> </div> <div class="sect3"> <h4 id="_header_version_1">Header (version 1)</h4> <div class="paragraph"> <p>A 24-byte header appears at the beginning of the file:</p> </div> <div class="literalblock"> <div class="content"> <pre>'REFT' uint8( version_number = 1 ) uint24( block_size ) uint64( min_update_index ) uint64( max_update_index )</pre> </div> </div> <div class="paragraph"> <p>Aligned files must specify <code>block_size</code> to configure readers with the expected block alignment. Unaligned files must set <code>block_size = 0</code>.</p> </div> <div class="paragraph"> <p>The <code>min_update_index</code> and <code>max_update_index</code> describe bounds for the <code>update_index</code> field of all log records in this file. When reftables are used in a stack for <a href="#Update-transactions">transactions</a>, these fields can order the files such that the prior file’s <code>max_update_index + 1</code> is the next file’s <code>min_update_index</code>.</p> </div> </div> <div class="sect3"> <h4 id="_header_version_2">Header (version 2)</h4> <div class="paragraph"> <p>A 28-byte header appears at the beginning of the file:</p> </div> <div class="literalblock"> <div class="content"> <pre>'REFT' uint8( version_number = 2 ) uint24( block_size ) uint64( min_update_index ) uint64( max_update_index ) uint32( hash_id )</pre> </div> </div> <div class="paragraph"> <p>The header is identical to <code>version_number=1</code>, with the 4-byte hash ID ("sha1" for SHA1 and "s256" for SHA-256) appended to the header.</p> </div> <div class="paragraph"> <p>For maximum backward compatibility, it is recommended to use version 1 when writing SHA1 reftables.</p> </div> </div> <div class="sect3"> <h4 id="_first_ref_block">First ref block</h4> <div class="paragraph"> <p>The first ref block shares the same block as the file header, and is 24 bytes smaller than all other blocks in the file. The first block immediately begins after the file header, at position 24.</p> </div> <div class="paragraph"> <p>If the first block is a log block (a log-only file), its block header begins immediately at position 24.</p> </div> </div> <div class="sect3"> <h4 id="_ref_block_format">Ref block format</h4> <div class="paragraph"> <p>A ref block is written as:</p> </div> <div class="literalblock"> <div class="content"> <pre>'r' uint24( block_len ) ref_record+ uint24( restart_offset )+ uint16( restart_count ) padding?</pre> </div> </div> <div class="paragraph"> <p>Blocks begin with <code>block_type = 'r'</code> and a 3-byte <code>block_len</code> which encodes the number of bytes in the block up to, but not including the optional <code>padding</code>. This is always less than or equal to the file’s block size. In the first ref block, <code>block_len</code> includes 24 bytes for the file header.</p> </div> <div class="paragraph"> <p>The 2-byte <code>restart_count</code> stores the number of entries in the <code>restart_offset</code> list, which must not be empty. Readers can use <code>restart_count</code> to binary search between restarts before starting a linear scan.</p> </div> <div class="paragraph"> <p>Exactly <code>restart_count</code> 3-byte <code>restart_offset</code> values precede the <code>restart_count</code>. Offsets are relative to the start of the block and refer to the first byte of any <code>ref_record</code> whose name has not been prefix compressed. Entries in the <code>restart_offset</code> list must be sorted, ascending. Readers can start linear scans from any of these records.</p> </div> <div class="paragraph"> <p>A variable number of <code>ref_record</code> fill the middle of the block, describing reference names and values. The format is described below.</p> </div> <div class="paragraph"> <p>As the first ref block shares the first file block with the file header, all <code>restart_offset</code> in the first block are relative to the start of the file (position 0), and include the file header. This forces the first <code>restart_offset</code> to be <code>28</code>.</p> </div> <div class="sect4"> <h5 id="_ref_record">ref record</h5> <div class="paragraph"> <p>A <code>ref_record</code> describes a single reference, storing both the name and its value(s). Records are formatted as:</p> </div> <div class="literalblock"> <div class="content"> <pre>varint( prefix_length ) varint( (suffix_length << 3) | value_type ) suffix varint( update_index_delta ) value?</pre> </div> </div> <div class="paragraph"> <p>The <code>prefix_length</code> field specifies how many leading bytes of the prior reference record’s name should be copied to obtain this reference’s name. This must be 0 for the first reference in any block, and also must be 0 for any <code>ref_record</code> whose offset is listed in the <code>restart_offset</code> table at the end of the block.</p> </div> <div class="paragraph"> <p>Recovering a reference name from any <code>ref_record</code> is a simple concat:</p> </div> <div class="literalblock"> <div class="content"> <pre>this_name = prior_name[0..prefix_length] + suffix</pre> </div> </div> <div class="paragraph"> <p>The <code>suffix_length</code> value provides the number of bytes available in <code>suffix</code> to copy from <code>suffix</code> to complete the reference name.</p> </div> <div class="paragraph"> <p>The <code>update_index</code> that last modified the reference can be obtained by adding <code>update_index_delta</code> to the <code>min_update_index</code> from the file header: <code>min_update_index + update_index_delta</code>.</p> </div> <div class="paragraph"> <p>The <code>value</code> follows. Its format is determined by <code>value_type</code>, one of the following:</p> </div> <div class="ulist"> <ul> <li> <p><code>0x0</code>: d