Google Git
Sign in
chromium / external / gitster / git-htmldocs / b96f40a0cb74a86e910bb0f415c4df5182ea5ccf / . / technical / parallel-checkout.html
blob: 1ca5d14fae795047ec9dc2748fa18ea3ffbe9c52 [file] [log] [blame]
Junio C Hamanob96f40a2024-08-01 00:57:25[diff] [blame^]1<!DOCTYPE html>
2<html xmlns="http://www.w3.org/1999/xhtml" lang="en">
3<head>
4<meta charset="UTF-8"/>
5<meta http-equiv="X-UA-Compatible" content="IE=edge"/>
6<meta name="viewport" content="width=device-width, initial-scale=1.0"/>
7<meta name="generator" content="Asciidoctor 2.0.20"/>
8<title>Parallel Checkout Design Notes</title>
9<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"/>
10<style>
11/*! Asciidoctor default stylesheet | MIT License | https://asciidoctor.org */
12/* Uncomment the following line when using as a custom stylesheet */
13/* @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"; */
14html{font-family:sans-serif;-webkit-text-size-adjust:100%}
15a{background:none}
16a:focus{outline:thin dotted}
17a:active,a:hover{outline:0}
18h1{font-size:2em;margin:.67em 0}
19b,strong{font-weight:bold}
20abbr{font-size:.9em}
21abbr[title]{cursor:help;border-bottom:1px dotted #dddddf;text-decoration:none}
22dfn{font-style:italic}
23hr{height:0}
24mark{background:#ff0;color:#000}
25code,kbd,pre,samp{font-family:monospace;font-size:1em}
26pre{white-space:pre-wrap}
27q{quotes:"\201C" "\201D" "\2018" "\2019"}
28small{font-size:80%}
29sub,sup{font-size:75%;line-height:0;position:relative;vertical-align:baseline}
30sup{top:-.5em}
31sub{bottom:-.25em}
32img{border:0}
33svg:not(:root){overflow:hidden}
34figure{margin:0}
35audio,video{display:inline-block}
36audio:not([controls]){display:none;height:0}
37fieldset{border:1px solid silver;margin:0 2px;padding:.35em .625em .75em}
38legend{border:0;padding:0}
39button,input,select,textarea{font-family:inherit;font-size:100%;margin:0}
40button,input{line-height:normal}
41button,select{text-transform:none}
42button,html input[type=button],input[type=reset],input[type=submit]{-webkit-appearance:button;cursor:pointer}
43button[disabled],html input[disabled]{cursor:default}
44input[type=checkbox],input[type=radio]{padding:0}
45button::-moz-focus-inner,input::-moz-focus-inner{border:0;padding:0}
46textarea{overflow:auto;vertical-align:top}
47table{border-collapse:collapse;border-spacing:0}
48*,::before,::after{box-sizing:border-box}
49html,body{font-size:100%}
50body{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}
51a:hover{cursor:pointer}
52img,object,embed{max-width:100%;height:auto}
53object,embed{height:100%}
54img{-ms-interpolation-mode:bicubic}
55.left{float:left!important}
56.right{float:right!important}
57.text-left{text-align:left!important}
58.text-right{text-align:right!important}
59.text-center{text-align:center!important}
60.text-justify{text-align:justify!important}
61.hide{display:none}
62img,object,svg{display:inline-block;vertical-align:middle}
63textarea{height:auto;min-height:50px}
64select{width:100%}
65.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}
66div,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}
67a{color:#2156a5;text-decoration:underline;line-height:inherit}
68a:hover,a:focus{color:#1d4b8f}
69a img{border:0}
70p{line-height:1.6;margin-bottom:1.25em;text-rendering:optimizeLegibility}
71p aside{font-size:.875em;line-height:1.35;font-style:italic}
72h1,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}
73h1 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}
74h1{font-size:2.125em}
75h2{font-size:1.6875em}
76h3,#toctitle,.sidebarblock>.content>.title{font-size:1.375em}
77h4,h5{font-size:1.125em}
78h6{font-size:1em}
79hr{border:solid #dddddf;border-width:1px 0 0;clear:both;margin:1.25em 0 1.1875em}
80em,i{font-style:italic;line-height:inherit}
81strong,b{font-weight:bold;line-height:inherit}
82small{font-size:60%;line-height:inherit}
83code{font-family:"Droid Sans Mono","DejaVu Sans Mono",monospace;font-weight:400;color:rgba(0,0,0,.9)}
84ul,ol,dl{line-height:1.6;margin-bottom:1.25em;list-style-position:outside;font-family:inherit}
85ul,ol{margin-left:1.5em}
86ul li ul,ul li ol{margin-left:1.25em;margin-bottom:0}
87ul.circle{list-style-type:circle}
88ul.disc{list-style-type:disc}
89ul.square{list-style-type:square}
90ul.circle ul:not([class]),ul.disc ul:not([class]),ul.square ul:not([class]){list-style:inherit}
91ol li ul,ol li ol{margin-left:1.25em;margin-bottom:0}
92dl dt{margin-bottom:.3125em;font-weight:bold}
93dl dd{margin-bottom:1.25em}
94blockquote{margin:0 0 1.25em;padding:.5625em 1.25em 0 1.1875em;border-left:1px solid #ddd}
95blockquote,blockquote p{line-height:1.6;color:rgba(0,0,0,.85)}
96@media screen and (min-width:768px){h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6{line-height:1.2}
97h1{font-size:2.75em}
98h2{font-size:2.3125em}
99h3,#toctitle,.sidebarblock>.content>.title{font-size:1.6875em}
100h4{font-size:1.4375em}}
101table{background:#fff;margin-bottom:1.25em;border:1px solid #dedede;word-wrap:normal}
102table thead,table tfoot{background:#f7f8f7}
103table 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}
104table tr th,table tr td{padding:.5625em .625em;font-size:inherit;color:rgba(0,0,0,.8)}
105table tr.even,table tr.alt{background:#f8f8f7}
106table thead tr th,table tfoot tr th,table tbody tr td,table tr td,table tfoot tr td{line-height:1.6}
107h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6{line-height:1.2;word-spacing:-.05em}
108h1 strong,h2 strong,h3 strong,#toctitle strong,.sidebarblock>.content>.title strong,h4 strong,h5 strong,h6 strong{font-weight:400}
109.center{margin-left:auto;margin-right:auto}
110.stretch{width:100%}
111.clearfix::before,.clearfix::after,.float-group::before,.float-group::after{content:" ";display:table}
112.clearfix::after,.float-group::after{clear:both}
113:not(pre).nobreak{word-wrap:normal}
114:not(pre).nowrap{white-space:nowrap}
115:not(pre).pre-wrap{white-space:pre-wrap}
116: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}
117pre{color:rgba(0,0,0,.9);font-family:"Droid Sans Mono","DejaVu Sans Mono",monospace;line-height:1.45;text-rendering:optimizeSpeed}
118pre code,pre pre{color:inherit;font-size:inherit;line-height:inherit}
119pre>code{display:block}
120pre.nowrap,pre.nowrap pre{white-space:pre;word-wrap:normal}
121em em{font-style:normal}
122strong strong{font-weight:400}
123.keyseq{color:rgba(51,51,51,.8)}
124kbd{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}
125.keyseq kbd:first-child{margin-left:0}
126.keyseq kbd:last-child{margin-right:0}
127.menuseq,.menuref{color:#000}
128.menuseq b:not(.caret),.menuref{font-weight:inherit}
129.menuseq{word-spacing:-.02em}
130.menuseq b.caret{font-size:1.25em;line-height:.8}
131.menuseq i.caret{font-weight:bold;text-align:center;width:.45em}
132b.button::before,b.button::after{position:relative;top:-1px;font-weight:400}
133b.button::before{content:"[";padding:0 3px 0 2px}
134b.button::after{content:"]";padding:0 2px 0 3px}
135p a>code:hover{color:rgba(0,0,0,.9)}
136#header,#content,#footnotes,#footer{width:100%;margin:0 auto;max-width:62.5em;*zoom:1;position:relative;padding-left:.9375em;padding-right:.9375em}
137#header::before,#header::after,#content::before,#content::after,#footnotes::before,#footnotes::after,#footer::before,#footer::after{content:" ";display:table}
138#header::after,#content::after,#footnotes::after,#footer::after{clear:both}
139#content{margin-top:1.25em}
140#content::before{content:none}
141#header>h1:first-child{color:rgba(0,0,0,.85);margin-top:2.25rem;margin-bottom:0}
142#header>h1:first-child+#toc{margin-top:8px;border-top:1px solid #dddddf}
143#header>h1:only-child,body.toc2 #header>h1:nth-last-child(2){border-bottom:1px solid #dddddf;padding-bottom:8px}
144#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}
145#header .details span:first-child{margin-left:-.125em}
146#header .details span.email a{color:rgba(0,0,0,.85)}
147#header .details br{display:none}
148#header .details br+span::before{content:"\00a0\2013\00a0"}
149#header .details br+span.author::before{content:"\00a0\22c5\00a0";color:rgba(0,0,0,.85)}
150#header .details br+span#revremark::before{content:"\00a0|\00a0"}
151#header #revnumber{text-transform:capitalize}
152#header #revnumber::after{content:"\00a0"}
153#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}
154#toc{border-bottom:1px solid #e7e7e9;padding-bottom:.5em}
155#toc>ul{margin-left:.125em}
156#toc ul.sectlevel0>li>a{font-style:italic}
157#toc ul.sectlevel0 ul.sectlevel1{margin:.5em 0}
158#toc ul{font-family:"Open Sans","DejaVu Sans",sans-serif;list-style-type:none}
159#toc li{line-height:1.3334;margin-top:.3334em}
160#toc a{text-decoration:none}
161#toc a:active{text-decoration:underline}
162#toctitle{color:#7a2518;font-size:1.2em}
163@media screen and (min-width:768px){#toctitle{font-size:1.375em}
164body.toc2{padding-left:15em;padding-right:0}
165#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}
166#toc.toc2 #toctitle{margin-top:0;margin-bottom:.8rem;font-size:1.2em}
167#toc.toc2>ul{font-size:.9em;margin-bottom:0}
168#toc.toc2 ul ul{margin-left:0;padding-left:1em}
169#toc.toc2 ul.sectlevel0 ul.sectlevel1{padding-left:0;margin-top:.5em;margin-bottom:.5em}
170body.toc2.toc-right{padding-left:0;padding-right:15em}
171body.toc2.toc-right #toc.toc2{border-right-width:0;border-left:1px solid #e7e7e9;left:auto;right:0}}
172@media screen and (min-width:1280px){body.toc2{padding-left:20em;padding-right:0}
173#toc.toc2{width:20em}
174#toc.toc2 #toctitle{font-size:1.375em}
175#toc.toc2>ul{font-size:.95em}
176#toc.toc2 ul ul{padding-left:1.25em}
177body.toc2.toc-right{padding-left:0;padding-right:20em}}
178#content #toc{border:1px solid #e0e0dc;margin-bottom:1.25em;padding:1.25em;background:#f8f8f7;border-radius:4px}
179#content #toc>:first-child{margin-top:0}
180#content #toc>:last-child{margin-bottom:0}
181#footer{max-width:none;background:rgba(0,0,0,.8);padding:1.25em}
182#footer-text{color:hsla(0,0%,100%,.8);line-height:1.44}
183#content{margin-bottom:.625em}
184.sect1{padding-bottom:.625em}
185@media screen and (min-width:768px){#content{margin-bottom:1.25em}
186.sect1{padding-bottom:1.25em}}
187.sect1:last-child{padding-bottom:0}
188.sect1+.sect1{border-top:1px solid #e7e7e9}
189#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}
190#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}
191#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}
192#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}
193#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}
194details,.audioblock,.imageblock,.literalblock,.listingblock,.stemblock,.videoblock{margin-bottom:1.25em}
195details{margin-left:1.25rem}
196details>summary{cursor:pointer;display:block;position:relative;line-height:1.6;margin-bottom:.625rem;outline:none;-webkit-tap-highlight-color:transparent}
197details>summary::-webkit-details-marker{display:none}
198details>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%)}
199details[open]>summary::before{border:solid transparent;border-top:solid;border-width:.5em .3em 0;transform:translateY(15%)}
200details>summary::after{content:"";width:1.25rem;height:1em;position:absolute;top:.3em;left:-1.25rem}
201.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}
202table.tableblock.fit-content>caption.title{white-space:nowrap;width:0}
203.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)}
204.admonitionblock>table{border-collapse:separate;border:0;background:none;width:100%}
205.admonitionblock>table td.icon{text-align:center;width:80px}
206.admonitionblock>table td.icon img{max-width:none}
207.admonitionblock>table td.icon .title{font-weight:bold;font-family:"Open Sans","DejaVu Sans",sans-serif;text-transform:uppercase}
208.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}
209.admonitionblock>table td.content>:last-child>:last-child{margin-bottom:0}
210.exampleblock>.content{border:1px solid #e6e6e6;margin-bottom:1.25em;padding:1.25em;background:#fff;border-radius:4px}
211.sidebarblock{border:1px solid #dbdbd6;margin-bottom:1.25em;padding:1.25em;background:#f3f3f2;border-radius:4px}
212.sidebarblock>.content>.title{color:#7a2518;margin-top:0;text-align:center}
213.exampleblock>.content>:first-child,.sidebarblock>.content>:first-child{margin-top:0}
214.exampleblock>.content>:last-child,.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,.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}
215.literalblock pre,.listingblock>.content>pre{border-radius:4px;overflow-x:auto;padding:1em;font-size:.8125em}
216@media screen and (min-width:768px){.literalblock pre,.listingblock>.content>pre{font-size:.90625em}}
217@media screen and (min-width:1280px){.literalblock pre,.listingblock>.content>pre{font-size:1em}}
218.literalblock pre,.listingblock>.content>pre:not(.highlight),.listingblock>.content>pre[class=highlight],.listingblock>.content>pre[class^="highlight "]{background:#f7f7f8}
219.literalblock.output pre{color:#f7f7f8;background:rgba(0,0,0,.9)}
220.listingblock>.content{position:relative}
221.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}
222.listingblock:hover code[data-lang]::before{display:block}
223.listingblock.terminal pre .command::before{content:attr(data-prompt);padding-right:.5em;color:inherit;opacity:.5}
224.listingblock.terminal pre .command:not([data-prompt])::before{content:"$"}
225.listingblock pre.highlightjs{padding:0}
226.listingblock pre.highlightjs>code{padding:1em;border-radius:4px}
227.listingblock pre.prettyprint{border-width:0}
228.prettyprint{background:#f7f7f8}
229pre.prettyprint .linenums{line-height:1.45;margin-left:2em}
230pre.prettyprint li{background:none;list-style-type:inherit;padding-left:0}
231pre.prettyprint li code[data-lang]::before{opacity:1}
232pre.prettyprint li:not(:first-child) code[data-lang]::before{display:none}
233table.linenotable{border-collapse:separate;border:0;margin-bottom:0;background:none}
234table.linenotable td[class]{color:inherit;vertical-align:top;padding:0;line-height:inherit;white-space:normal}
235table.linenotable td.code{padding-left:.75em}
236table.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}
237pre.pygments span.linenos{display:inline-block;margin-right:.75em}
238.quoteblock{margin:0 1em 1.25em 1.5em;display:table}
239.quoteblock:not(.excerpt)>.title{margin-left:-1.5em;margin-bottom:.75em}
240.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}
241.quoteblock blockquote{margin:0;padding:0;border:0}
242.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)}
243.quoteblock blockquote>.paragraph:last-child p{margin-bottom:0}
244.quoteblock .attribution{margin-top:.75em;margin-right:.5ex;text-align:right}
245.verseblock{margin:0 1em 1.25em}
246.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}
247.verseblock pre strong{font-weight:400}
248.verseblock .attribution{margin-top:1.25rem;margin-left:.5ex}
249.quoteblock .attribution,.verseblock .attribution{font-size:.9375em;line-height:1.45;font-style:italic}
250.quoteblock .attribution br,.verseblock .attribution br{display:none}
251.quoteblock .attribution cite,.verseblock .attribution cite{display:block;letter-spacing:-.025em;color:rgba(0,0,0,.6)}
252.quoteblock.abstract blockquote::before,.quoteblock.excerpt blockquote::before,.quoteblock .quoteblock blockquote::before{display:none}
253.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}
254.quoteblock.abstract{margin:0 1em 1.25em;display:block}
255.quoteblock.abstract>.title{margin:0 0 .375em;font-size:1.15em;text-align:center}
256.quoteblock.excerpt>blockquote,.quoteblock .quoteblock{padding:0 0 .25em 1em;border-left:.25em solid #dddddf}
257.quoteblock.excerpt,.quoteblock .quoteblock{margin-left:0}
258.quoteblock.excerpt blockquote,.quoteblock.excerpt p,.quoteblock .quoteblock blockquote,.quoteblock .quoteblock p{color:inherit;font-size:1.0625rem}
259.quoteblock.excerpt .attribution,.quoteblock .quoteblock .attribution{color:inherit;font-size:.85rem;text-align:left;margin-right:0}
260p.tableblock:last-child{margin-bottom:0}
261td.tableblock>.content{margin-bottom:1.25em;word-wrap:anywhere}
262td.tableblock>.content>:last-child{margin-bottom:-1.25em}
263table.tableblock,th.tableblock,td.tableblock{border:0 solid #dedede}
264table.grid-all>*>tr>*{border-width:1px}
265table.grid-cols>*>tr>*{border-width:0 1px}
266table.grid-rows>*>tr>*{border-width:1px 0}
267table.frame-all{border-width:1px}
268table.frame-ends{border-width:1px 0}
269table.frame-sides{border-width:0 1px}
270table.frame-none>colgroup+*>:first-child>*,table.frame-sides>colgroup+*>:first-child>*{border-top-width:0}
271table.frame-none>:last-child>:last-child>*,table.frame-sides>:last-child>:last-child>*{border-bottom-width:0}
272table.frame-none>*>tr>:first-child,table.frame-ends>*>tr>:first-child{border-left-width:0}
273table.frame-none>*>tr>:last-child,table.frame-ends>*>tr>:last-child{border-right-width:0}
274table.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}
275th.halign-left,td.halign-left{text-align:left}
276th.halign-right,td.halign-right{text-align:right}
277th.halign-center,td.halign-center{text-align:center}
278th.valign-top,td.valign-top{vertical-align:top}
279th.valign-bottom,td.valign-bottom{vertical-align:bottom}
280th.valign-middle,td.valign-middle{vertical-align:middle}
281table thead th,table tfoot th{font-weight:bold}
282tbody tr th{background:#f7f8f7}
283tbody tr th,tbody tr th p,tfoot tr th,tfoot tr th p{color:rgba(0,0,0,.8);font-weight:bold}
284p.tableblock>code:only-child{background:none;padding:0}
285p.tableblock{font-size:1em}
286ol{margin-left:1.75em}
287ul li ol{margin-left:1.5em}
288dl dd{margin-left:1.125em}
289dl dd:last-child,dl dd:last-child>:last-child{margin-bottom:0}
290li p,ul dd,ol dd,.olist .olist,.ulist .ulist,.ulist .olist,.olist .ulist{margin-bottom:.625em}
291ul.checklist,ul.none,ol.none,ul.no-bullet,ol.no-bullet,ol.unnumbered,ul.unstyled,ol.unstyled{list-style-type:none}
292ul.no-bullet,ol.no-bullet,ol.unnumbered{margin-left:.625em}
293ul.unstyled,ol.unstyled{margin-left:0}
294li>p:empty:only-child::before{content:"";display:inline-block}
295ul.checklist>li>p:first-child{margin-left:-1em}
296ul.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}
297ul.checklist>li>p:first-child>input[type=checkbox]:first-child{margin-right:.25em}
298ul.inline{display:flex;flex-flow:row wrap;list-style:none;margin:0 0 .625em -1.25em}
299ul.inline>li{margin-left:1.25em}
300.unstyled dl dt{font-weight:400;font-style:normal}
301ol.arabic{list-style-type:decimal}
302ol.decimal{list-style-type:decimal-leading-zero}
303ol.loweralpha{list-style-type:lower-alpha}
304ol.upperalpha{list-style-type:upper-alpha}
305ol.lowerroman{list-style-type:lower-roman}
306ol.upperroman{list-style-type:upper-roman}
307ol.lowergreek{list-style-type:lower-greek}
308.hdlist>table,.colist>table{border:0;background:none}
309.hdlist>table>tbody>tr,.colist>table>tbody>tr{background:none}
310td.hdlist1,td.hdlist2{vertical-align:top;padding:0 .625em}
311td.hdlist1{font-weight:bold;padding-bottom:1.25em}
312td.hdlist2{word-wrap:anywhere}
313.literalblock+.colist,.listingblock+.colist{margin-top:-.5em}
314.colist td:not([class]):first-child{padding:.4em .75em 0;line-height:1;vertical-align:top}
315.colist td:not([class]):first-child img{max-width:none}
316.colist td:not([class]):last-child{padding:.25em 0}
317.thumb,.th{line-height:0;display:inline-block;border:4px solid #fff;box-shadow:0 0 0 1px #ddd}
318.imageblock.left{margin:.25em .625em 1.25em 0}
319.imageblock.right{margin:.25em 0 1.25em .625em}
320.imageblock>.title{margin-bottom:0}
321.imageblock.thumb,.imageblock.th{border-width:6px}
322.imageblock.thumb>.title,.imageblock.th>.title{padding:0 .125em}
323.image.left,.image.right{margin-top:.25em;margin-bottom:.25em;display:inline-block;line-height:0}
324.image.left{margin-right:.625em}
325.image.right{margin-left:.625em}
326a.image{text-decoration:none;display:inline-block}
327a.image object{pointer-events:none}
328sup.footnote,sup.footnoteref{font-size:.875em;position:static;vertical-align:super}
329sup.footnote a,sup.footnoteref a{text-decoration:none}
330sup.footnote a:active,sup.footnoteref a:active{text-decoration:underline}
331#footnotes{padding-top:.75em;padding-bottom:.75em;margin-bottom:.625em}
332#footnotes hr{width:20%;min-width:6.25em;margin:-.25em 0 .75em;border-width:1px 0 0}
333#footnotes .footnote{padding:0 .375em 0 .225em;line-height:1.3334;font-size:.875em;margin-left:1.2em;margin-bottom:.2em}
334#footnotes .footnote a:first-of-type{font-weight:bold;text-decoration:none;margin-left:-1.05em}
335#footnotes .footnote:last-of-type{margin-bottom:0}
336#content #footnotes{margin-top:-.625em;margin-bottom:0;padding:.75em 0}
337div.unbreakable{page-break-inside:avoid}
338.big{font-size:larger}
339.small{font-size:smaller}
340.underline{text-decoration:underline}
341.overline{text-decoration:overline}
342.line-through{text-decoration:line-through}
343.aqua{color:#00bfbf}
344.aqua-background{background:#00fafa}
345.black{color:#000}
346.black-background{background:#000}
347.blue{color:#0000bf}
348.blue-background{background:#0000fa}
349.fuchsia{color:#bf00bf}
350.fuchsia-background{background:#fa00fa}
351.gray{color:#606060}
352.gray-background{background:#7d7d7d}
353.green{color:#006000}
354.green-background{background:#007d00}
355.lime{color:#00bf00}
356.lime-background{background:#00fa00}
357.maroon{color:#600000}
358.maroon-background{background:#7d0000}
359.navy{color:#000060}
360.navy-background{background:#00007d}
361.olive{color:#606000}
362.olive-background{background:#7d7d00}
363.purple{color:#600060}
364.purple-background{background:#7d007d}
365.red{color:#bf0000}
366.red-background{background:#fa0000}
367.silver{color:#909090}
368.silver-background{background:#bcbcbc}
369.teal{color:#006060}
370.teal-background{background:#007d7d}
371.white{color:#bfbfbf}
372.white-background{background:#fafafa}
373.yellow{color:#bfbf00}
374.yellow-background{background:#fafa00}
375span.icon>.fa{cursor:default}
376a span.icon>.fa{cursor:inherit}
377.admonitionblock td.icon [class^="fa icon-"]{font-size:2.5em;text-shadow:1px 1px 2px rgba(0,0,0,.5);cursor:default}
378.admonitionblock td.icon .icon-note::before{content:"\f05a";color:#19407c}
379.admonitionblock td.icon .icon-tip::before{content:"\f0eb";text-shadow:1px 1px 2px rgba(155,155,0,.8);color:#111}
380.admonitionblock td.icon .icon-warning::before{content:"\f071";color:#bf6900}
381.admonitionblock td.icon .icon-caution::before{content:"\f06d";color:#bf3400}
382.admonitionblock td.icon .icon-important::before{content:"\f06a";color:#bf0000}
383.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}
384.conum[data-value] *{color:#fff!important}
385.conum[data-value]+b{display:none}
386.conum[data-value]::after{content:attr(data-value)}
387pre .conum[data-value]{position:relative;top:-.125em}
388b.conum *{color:inherit!important}
389.conum:not([data-value]):empty{display:none}
390dt,th.tableblock,td.content,div.footnote{text-rendering:optimizeLegibility}
391h1,h2,p,td.content,span.alt,summary{letter-spacing:-.01em}
392p strong,td.content strong,div.footnote strong{letter-spacing:-.005em}
393p,blockquote,dt,td.content,td.hdlist1,span.alt,summary{font-size:1.0625rem}
394p{margin-bottom:1.25rem}
395.sidebarblock p,.sidebarblock dt,.sidebarblock td.content,p.tableblock{font-size:1em}
396.exampleblock>.content{background:#fffef7;border-color:#e0e0dc;box-shadow:0 1px 4px #e0e0dc}
397.print-only{display:none!important}
398@page{margin:1.25cm .75cm}
399@media print{*{box-shadow:none!important;text-shadow:none!important}
400html{font-size:80%}
401a{color:inherit!important;text-decoration:underline!important}
402a.bare,a[href^="#"],a[href^="mailto:"]{text-decoration:none!important}
403a[href^="http:"]:not(.bare)::after,a[href^="https:"]:not(.bare)::after{content:"(" attr(href) ")";display:inline-block;font-size:.875em;padding-left:.25em}
404abbr[title]{border-bottom:1px dotted}
405abbr[title]::after{content:" (" attr(title) ")"}
406pre,blockquote,tr,img,object,svg{page-break-inside:avoid}
407thead{display:table-header-group}
408svg{max-width:100%}
409p,blockquote,dt,td.content{font-size:1em;orphans:3;widows:3}
410h2,h3,#toctitle,.sidebarblock>.content>.title{page-break-after:avoid}
411#header,#content,#footnotes,#footer{max-width:none}
412#toc,.sidebarblock,.exampleblock>.content{background:none!important}
413#toc{border-bottom:1px solid #dddddf!important;padding-bottom:0!important}
414body.book #header{text-align:center}
415body.book #header>h1:first-child{border:0!important;margin:2.5em 0 1em}
416body.book #header .details{border:0!important;display:block;padding:0!important}
417body.book #header .details span:first-child{margin-left:0!important}
418body.book #header .details br{display:block}
419body.book #header .details br+span::before{content:none!important}
420body.book #toc{border:0!important;text-align:left!important;padding:0!important;margin:0!important}
421body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-break-before:always}
422.listingblock code[data-lang]::before{display:block}
423#footer{padding:0 .9375em}
424.hide-on-print{display:none!important}
425.print-only{display:block!important}
426.hide-for-print{display:none!important}
427.show-for-print{display:inherit!important}}
428@media amzn-kf8,print{#header>h1:first-child{margin-top:1.25rem}
429.sect1{padding:0!important}
430.sect1+.sect1{border:0}
431#footer{background:none}
432#footer-text{color:rgba(0,0,0,.6);font-size:.9em}}
433@media amzn-kf8{#header,#content,#footnotes,#footer{padding:0}}
434</style>
435</head>
436<body class="article">
437<div id="header">
438<h1>Parallel Checkout Design Notes</h1>
439<div class="details">
440<span id="revdate">2024-07-31</span>
441</div>
442</div>
443<div id="content">
444<div id="preamble">
445<div class="sectionbody">
446<div class="paragraph">
447<p>The "Parallel Checkout" feature attempts to use multiple processes to
448parallelize the work of uncompressing the blobs, applying in-core
449filters, and writing the resulting contents to the working tree during a
450checkout operation. It can be used by all checkout-related commands,
451such as <code>clone</code>, <code>checkout</code>, <code>reset</code>, <code>sparse-checkout</code>, and others.</p>
452</div>
453<div class="paragraph">
454<p>These commands share the following basic structure:</p>
455</div>
456<div class="ulist">
457<ul>
458<li>
459<p>Step 1: Read the current index file into memory.</p>
460</li>
461<li>
462<p>Step 2: Modify the in-memory index based upon the command, and
463temporarily mark all cache entries that need to be updated.</p>
464</li>
465<li>
466<p>Step 3: Populate the working tree to match the new candidate index.
467This includes iterating over all of the to-be-updated cache entries
468and delete, create, or overwrite the associated files in the working
469tree.</p>
470</li>
471<li>
472<p>Step 4: Write the new index to disk.</p>
473</li>
474</ul>
475</div>
476<div class="paragraph">
477<p>Step 3 is the focus of the "parallel checkout" effort described here.</p>
478</div>
479</div>
480</div>
481<div class="sect1">
482<h2 id="_sequential_implementation">Sequential Implementation</h2>
483<div class="sectionbody">
484<div class="paragraph">
485<p>For the purposes of discussion here, the current sequential
486implementation of Step 3 is divided in 3 parts, each one implemented in
487its own function:</p>
488</div>
489<div class="ulist">
490<ul>
491<li>
492<p>Step 3a: <code>unpack-trees.c:check_updates()</code> contains a series of
493sequential loops iterating over the <code>cache_entry</code>'s array. The main
494loop in this function calls the Step 3b function for each of the
495to-be-updated entries.</p>
496</li>
497<li>
498<p>Step 3b: <code>entry.c:checkout_entry()</code> examines the existing working tree
499for file conflicts, collisions, and unsaved changes. It removes files
500and creates leading directories as necessary. It calls the Step 3c
501function for each entry to be written.</p>
502</li>
503<li>
504<p>Step 3c: <code>entry.c:write_entry()</code> loads the blob into memory, smudges
505it if necessary, creates the file in the working tree, writes the
506smudged contents, calls <code>fstat()</code> or <code>lstat()</code>, and updates the
507associated <code>cache_entry</code> struct with the stat information gathered.</p>
508</li>
509</ul>
510</div>
511<div class="paragraph">
512<p>It wouldn&#8217;t be safe to perform Step 3b in parallel, as there could be
513race conditions between file creations and removals. Instead, the
514parallel checkout framework lets the sequential code handle Step 3b,
515and uses parallel workers to replace the sequential
516<code>entry.c:write_entry()</code> calls from Step 3c.</p>
517</div>
518</div>
519</div>
520<div class="sect1">
521<h2 id="_rejected_multi_threaded_solution">Rejected Multi-Threaded Solution</h2>
522<div class="sectionbody">
523<div class="paragraph">
524<p>The most "straightforward" implementation would be to spread the set of
525to-be-updated cache entries across multiple threads. But due to the
526thread-unsafe functions in the object database code, we would have to use locks to
527coordinate the parallel operation. An early prototype of this solution
528showed that the multi-threaded checkout would bring performance
529improvements over the sequential code, but there was still too much lock
530contention. A <code>perf</code> profiling indicated that around 20% of the runtime
531during a local Linux clone (on an SSD) was spent in locking functions.
532For this reason this approach was rejected in favor of using multiple
533child processes, which led to better performance.</p>
534</div>
535</div>
536</div>
537<div class="sect1">
538<h2 id="_multi_process_solution">Multi-Process Solution</h2>
539<div class="sectionbody">
540<div class="paragraph">
541<p>Parallel checkout alters the aforementioned Step 3 to use multiple
542<code>checkout--worker</code> background processes to distribute the work. The
543long-running worker processes are controlled by the foreground Git
544command using the existing run-command API.</p>
545</div>
546<div class="sect2">
547<h3 id="_overview">Overview</h3>
548<div class="paragraph">
549<p>Step 3b is only slightly altered; for each entry to be checked out, the
550main process performs the following steps:</p>
551</div>
552<div class="ulist">
553<ul>
554<li>
555<p>M1: Check whether there is any untracked or unclean file in the
556working tree which would be overwritten by this entry, and decide
557whether to proceed (removing the file(s)) or not.</p>
558</li>
559<li>
560<p>M2: Create the leading directories.</p>
561</li>
562<li>
563<p>M3: Load the conversion attributes for the entry&#8217;s path.</p>
564</li>
565<li>
566<p>M4: Check, based on the entry&#8217;s type and conversion attributes,
567whether the entry is eligible for parallel checkout (more on this
568later). If it is eligible, enqueue the entry and the loaded
569attributes to later write the entry in parallel. If not, write the
570entry right away, using the default sequential code.</p>
571</li>
572</ul>
573</div>
574<div class="paragraph">
575<p>Note: we save the conversion attributes associated with each entry
576because the workers don&#8217;t have access to the main process' index state,
577so they can&#8217;t load the attributes by themselves (and the attributes are
578needed to properly smudge the entry). Additionally, this has a positive
579impact on performance as (1) we don&#8217;t need to load the attributes twice
580and (2) the attributes machinery is optimized to handle paths in
581sequential order.</p>
582</div>
583<div class="paragraph">
584<p>After all entries have passed through the above steps, the main process
585checks if the number of enqueued entries is sufficient to spread among
586the workers. If not, it just writes them sequentially. Otherwise, it
587spawns the workers and distributes the queued entries uniformly in
588continuous chunks. This aims to minimize the chances of two workers
589writing to the same directory simultaneously, which could increase lock
590contention in the kernel.</p>
591</div>
592<div class="paragraph">
593<p>Then, for each assigned item, each worker:</p>
594</div>
595<div class="ulist">
596<ul>
597<li>
598<p>W1: Checks if there is any non-directory file in the leading part of
599the entry&#8217;s path or if there already exists a file at the entry' path.
600If so, mark the entry with <code>PC_ITEM_COLLIDED</code> and skip it (more on
601this later).</p>
602</li>
603<li>
604<p>W2: Creates the file (with O_CREAT and O_EXCL).</p>
605</li>
606<li>
607<p>W3: Loads the blob into memory (inflating and delta reconstructing
608it).</p>
609</li>
610<li>
611<p>W4: Applies any required in-process filter, like end-of-line
612conversion and re-encoding.</p>
613</li>
614<li>
615<p>W5: Writes the result to the file descriptor opened at W2.</p>
616</li>
617<li>
618<p>W6: Calls <code>fstat()</code> or <code>lstat()</code> on the just-written path, and sends
619the result back to the main process, together with the end status of
620the operation and the item&#8217;s identification number.</p>
621</li>
622</ul>
623</div>
624<div class="paragraph">
625<p>Note that, when possible, steps W3 to W5 are delegated to the streaming
626machinery, removing the need to keep the entire blob in memory.</p>
627</div>
628<div class="paragraph">
629<p>If the worker fails to read the blob or to write it to the working tree,
630it removes the created file to avoid leaving empty files behind. This is
631the <strong>only</strong> time a worker is allowed to remove a file.</p>
632</div>
633<div class="paragraph">
634<p>As mentioned earlier, it is the responsibility of the main process to
635remove any file that blocks the checkout operation (or abort if the
636removal(s) would cause data loss and the user didn&#8217;t ask to <code>--force</code>).
637This is crucial to avoid race conditions and also to properly detect
638path collisions at Step W1.</p>
639</div>
640<div class="paragraph">
641<p>After the workers finish writing the items and sending back the required
642information, the main process handles the results in two steps:</p>
643</div>
644<div class="ulist">
645<ul>
646<li>
647<p>First, it updates the in-memory index with the <code>lstat()</code> information
648sent by the workers. (This must be done first as this information
649might be required in the following step.)</p>
650</li>
651<li>
652<p>Then it writes the items which collided on disk (i.e. items marked
653with <code>PC_ITEM_COLLIDED</code>). More on this below.</p>
654</li>
655</ul>
656</div>
657</div>
658</div>
659</div>
660<div class="sect1">
661<h2 id="_path_collisions">Path Collisions</h2>
662<div class="sectionbody">
663<div class="paragraph">
664<p>Path collisions happen when two different paths correspond to the same
665entry in the file system. E.g. the paths <em>a</em> and <em>A</em> would collide in a
666case-insensitive file system.</p>
667</div>
668<div class="paragraph">
669<p>The sequential checkout deals with collisions in the same way that it
670deals with files that were already present in the working tree before
671checkout. Basically, it checks if the path that it wants to write
672already exists on disk, makes sure the existing file doesn&#8217;t have
673unsaved data, and then overwrites it. (To be more pedantic: it deletes
674the existing file and creates the new one.) So, if there are multiple
675colliding files to be checked out, the sequential code will write each
676one of them but only the last will actually survive on disk.</p>
677</div>
678<div class="paragraph">
679<p>Parallel checkout aims to reproduce the same behavior. However, we
680cannot let the workers racily write to the same file on disk. Instead,
681the workers detect when the entry that they want to check out would
682collide with an existing file, and mark it with <code>PC_ITEM_COLLIDED</code>.
683Later, the main process can sequentially feed these entries back to
684<code>checkout_entry()</code> without the risk of race conditions. On clone, this
685also has the effect of marking the colliding entries to later emit a
686warning for the user, like the classic sequential checkout does.</p>
687</div>
688<div class="paragraph">
689<p>The workers are able to detect both collisions among the entries being
690concurrently written and collisions between a parallel-eligible entry
691and an ineligible entry. The general idea for collision detection is
692quite straightforward: for each parallel-eligible entry, the main
693process must remove all files that prevent this entry from being written
694(before enqueueing it). This includes any non-directory file in the
695leading path of the entry. Later, when a worker gets assigned the entry,
696it looks again for the non-directory files and for an already existing
697file at the entry&#8217;s path. If any of these checks finds something, the
698worker knows that there was a path collision.</p>
699</div>
700<div class="paragraph">
701<p>Because parallel checkout can distinguish path collisions from the case
702where the file was already present in the working tree before checkout,
703we could alternatively choose to skip the checkout of colliding entries.
704However, each entry that doesn&#8217;t get written would have NULL <code>lstat()</code>
705fields on the index. This could cause performance penalties for
706subsequent commands that need to refresh the index, as they would have
707to go to the file system to see if the entry is dirty. Thus, if we have
708N entries in a colliding group and we decide to write and <code>lstat()</code> only
709one of them, every subsequent <code>git-status</code> will have to read, convert,
710and hash the written file N - 1 times. By checking out all colliding
711entries (like the sequential code does), we only pay the overhead once,
712during checkout.</p>
713</div>
714</div>
715</div>
716<div class="sect1">
717<h2 id="_eligible_entries_for_parallel_checkout">Eligible Entries for Parallel Checkout</h2>
718<div class="sectionbody">
719<div class="paragraph">
720<p>As previously mentioned, not all entries passed to <code>checkout_entry()</code>
721will be considered eligible for parallel checkout. More specifically, we
722exclude:</p>
723</div>
724<div class="ulist">
725<ul>
726<li>
727<p>Symbolic links; to avoid race conditions that, in combination with
728path collisions, could cause workers to write files at the wrong
729place. For example, if we were to concurrently check out a symlink
730<em>a</em> &#8594; <em>b</em> and a regular file <em>A/f</em> in a case-insensitive file system,
731we could potentially end up writing the file <em>A/f</em> at <em>a/f</em>, due to a
732race condition.</p>
733</li>
734<li>
735<p>Regular files that require external filters (either "one shot" filters
736or long-running process filters). These filters are black-boxes to Git
737and may have their own internal locking or non-concurrent assumptions.
738So it might not be safe to run multiple instances in parallel.</p>
739<div class="paragraph">
740<p>Besides, long-running filters may use the delayed checkout feature to
741postpone the return of some filtered blobs. The delayed checkout queue
742and the parallel checkout queue are not compatible and should remain
743separate.</p>
744</div>
745<div class="paragraph">
746<p>Note: regular files that only require internal filters, like end-of-line
747conversion and re-encoding, are eligible for parallel checkout.</p>
748</div>
749</li>
750</ul>
751</div>
752<div class="paragraph">
753<p>Ineligible entries are checked out by the classic sequential codepath
754<strong>before</strong> spawning workers.</p>
755</div>
756<div class="paragraph">
757<p>Note: submodules' files are also eligible for parallel checkout (as
758long as they don&#8217;t fall into any of the excluding categories mentioned
759above). But since each submodule is checked out in its own child
760process, we don&#8217;t mix the superproject&#8217;s and the submodules' files in
761the same parallel checkout process or queue.</p>
762</div>
763</div>
764</div>
765<div class="sect1">
766<h2 id="_the_api">The API</h2>
767<div class="sectionbody">
768<div class="paragraph">
769<p>The parallel checkout API was designed with the goal of minimizing
770changes to the current users of the checkout machinery. This means that
771they don&#8217;t have to call a different function for sequential or parallel
772checkout. As already mentioned, <code>checkout_entry()</code> will automatically
773insert the given entry in the parallel checkout queue when this feature
774is enabled and the entry is eligible; otherwise, it will just write the
775entry right away, using the sequential code. In general, callers of the
776parallel checkout API should look similar to this:</p>
777</div>
778<div class="listingblock">
779<div class="content">
780<pre>int pc_workers, pc_threshold, err = 0;
781struct checkout state;
782
783get_parallel_checkout_configs(&amp;pc_workers, &amp;pc_threshold);
784
785/*
786 * This check is not strictly required, but it
787 * should save some time in sequential mode.
788 */
789if (pc_workers &gt; 1)
790 init_parallel_checkout();
791
792for (each cache_entry ce to-be-updated)
793 err |= checkout_entry(ce, &amp;state, NULL, NULL);
794
795err |= run_parallel_checkout(&amp;state, pc_workers, pc_threshold, NULL, NULL);</pre>
796</div>
797</div>
798</div>
799</div>
800</div>
801<div id="footer">
802<div id="footer-text">
803Last updated 2023-10-23 14:43:46 -0700
804</div>
805</div>
806</body>
807</html>