Repository navigation
Expand file tree
/
Copy patharchitecture.html
More file actions
429 lines (416 loc) · 30.3 KB
/
Copy patharchitecture.html
File metadata and controls
429 lines (416 loc) · 30.3 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>fib architecture</title>
<link rel="preconnect" href="https://fonts.googleapis.com">
<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=IBM+Plex+Sans:wght@400;500;600;700&family=IBM+Plex+Mono:wght@400;500;600&display=swap">
<style>
:root{
--bg:#f3f5f8; --surface:#ffffff; --ink:#16202c; --muted:#5a6676; --line:#d8dee7;
--paper:#ffffff; --paper-line:#e2e6ed;
--loop:#2458c6; --work:#0c7d72; --hs:#a86a12; --str:#6b45c8; --tmr:#5f6b7a; --usr:#b23a62;
--loop-bg:#e8effc; --work-bg:#e3f4f1; --hs-bg:#fbf0de; --str-bg:#efe9fb; --tmr-bg:#eceff3; --usr-bg:#fae6ed;
--code-bg:#eef1f5;
--sans:"IBM Plex Sans","PingFang SC","Hiragino Sans GB","Microsoft YaHei",system-ui,sans-serif;
--mono:"IBM Plex Mono",ui-monospace,"SF Mono",Menlo,monospace;
}
@media (prefers-color-scheme: dark){
:root:not([data-theme="light"]){
color-scheme:dark;
--bg:#0f141b; --surface:#161d27; --ink:#e4e9f0; --muted:#94a0b0; --line:#2a3443;
--paper:#eef1f5; --paper-line:#c9d0da;
--loop:#7aa4ff; --work:#4fd1bf; --hs:#f0b35a; --str:#b39cff; --tmr:#a3adba; --usr:#f27fa3;
--loop-bg:#1b2842; --work-bg:#12302c; --hs-bg:#35280f; --str-bg:#271f40; --tmr-bg:#222a35; --usr-bg:#3a1a27;
--code-bg:#1f2833;
}
}
:root[data-theme="dark"]{
color-scheme:dark;
--bg:#0f141b; --surface:#161d27; --ink:#e4e9f0; --muted:#94a0b0; --line:#2a3443;
--paper:#eef1f5; --paper-line:#c9d0da;
--loop:#7aa4ff; --work:#4fd1bf; --hs:#f0b35a; --str:#b39cff; --tmr:#a3adba; --usr:#f27fa3;
--loop-bg:#1b2842; --work-bg:#12302c; --hs-bg:#35280f; --str-bg:#271f40; --tmr-bg:#222a35; --usr-bg:#3a1a27;
--code-bg:#1f2833;
}
*{box-sizing:border-box}
body{background:var(--bg);color:var(--ink);font:15px/1.7 var(--sans);padding-inline:16px;padding-block:0 64px}
.wrap{max-width:1180px;margin:0 auto;display:grid;grid-template-columns:220px minmax(0,1fr);gap:40px}
nav.toc{position:sticky;top:env(safe-area-inset-top,0px);align-self:start;padding-top:40px;font-size:13px}
nav.toc b{display:block;font:600 11px/1 var(--mono);letter-spacing:.12em;color:var(--muted);text-transform:uppercase;margin-bottom:12px}
nav.toc ol{list-style:none;margin:0;padding:0;display:grid;gap:2px}
nav.toc a{display:block;padding:5px 10px;border-radius:6px;color:var(--ink);text-decoration:none}
nav.toc a:hover,nav.toc a:focus-visible{background:var(--surface);outline:none}
nav.toc a span{font-family:var(--mono);color:var(--muted);margin-right:6px}
main{min-width:0;padding-top:40px}
header h1{font-size:34px;line-height:1.2;margin:0 0 12px;letter-spacing:-.01em;text-wrap:balance}
header p{color:var(--muted);max-width:72ch;margin:0 0 8px}
h2{font-size:23px;line-height:1.3;margin:0 0 6px;text-wrap:balance}
h3{font-size:16px;margin:22px 0 8px}
section{padding-top:48px;scroll-margin-top:12px}
section>.lede{color:var(--muted);margin:0 0 14px;max-width:78ch}
code,.mono{font-family:var(--mono);font-size:.88em}
p code,li code,td code{background:var(--code-bg);padding:1px 5px;border-radius:4px}
.legend{display:flex;flex-wrap:wrap;gap:8px;margin:18px 0 0}
.chip{display:inline-flex;align-items:center;gap:6px;padding:3px 10px;border-radius:999px;font:500 12px/1.6 var(--mono);border:1px solid currentColor}
.chip i{width:8px;height:8px;border-radius:2px;background:currentColor}
.c-loop{color:var(--loop);background:var(--loop-bg)} .c-work{color:var(--work);background:var(--work-bg)}
.c-hs{color:var(--hs);background:var(--hs-bg)} .c-str{color:var(--str);background:var(--str-bg)}
.c-tmr{color:var(--tmr);background:var(--tmr-bg)} .c-usr{color:var(--usr);background:var(--usr-bg)}
.runs{display:flex;flex-wrap:wrap;gap:6px;margin:0 0 14px}
.diagram{background:var(--paper);border:1px solid var(--paper-line);border-radius:10px;padding:18px 12px;overflow-x:auto}
.diagram pre.mermaid{margin:0;background:transparent;text-align:center;color:#16202c}
.notes{margin:14px 0 0;padding-left:20px;display:grid;gap:6px;max-width:82ch}
.notes li::marker{color:var(--muted)}
.ref{font:12px/1.5 var(--mono);color:var(--muted);margin-top:10px}
.tbl{overflow-x:auto;margin-top:14px;border:1px solid var(--line);border-radius:10px;background:var(--surface)}
table{border-collapse:collapse;width:100%;min-width:760px;font-size:13.5px}
th,td{text-align:left;vertical-align:top;padding:9px 12px;border-bottom:1px solid var(--line)}
th{font:600 11px/1.4 var(--mono);letter-spacing:.06em;text-transform:uppercase;color:var(--muted);background:var(--bg)}
tr:last-child td{border-bottom:0}
td:first-child{font-weight:600;white-space:nowrap}
.dash{color:var(--muted)}
.callout{border-left:3px solid var(--hs);background:var(--surface);padding:10px 14px;border-radius:0 8px 8px 0;margin-top:14px;max-width:82ch}
@media (max-width:860px){
.wrap{grid-template-columns:1fr;gap:0}
nav.toc{position:static;padding-top:24px}
nav.toc ol{grid-template-columns:repeat(auto-fill,minmax(150px,1fr))}
header h1{font-size:27px}
}
.toplinks{display:flex;flex-wrap:wrap;gap:6px;margin:0 0 22px}
.toplinks a{display:inline-block;padding:3px 10px;border:1px solid var(--line);border-radius:999px;font:500 12px/1.6 var(--mono);color:var(--ink);text-decoration:none;background:var(--surface)}
.toplinks a[aria-current]{border-color:var(--loop);color:var(--loop);background:var(--loop-bg)}
.toplinks a:hover,.toplinks a:focus-visible{border-color:var(--loop);outline:none}
header p a,.lede a{color:var(--loop)}
.rules{display:grid;grid-template-columns:repeat(auto-fit,minmax(240px,1fr));gap:14px;margin-top:14px}
.rule{background:var(--surface);border:1px solid var(--line);border-radius:10px;padding:16px 18px}
.rule b{display:block;font-size:16px;margin-bottom:6px}
.rule p{margin:0;color:var(--muted);font-size:14px}
body{margin:0}
</style>
</head>
<body>
<div class="wrap">
<nav class="toc" aria-label="Contents">
<div class="toplinks"><a href="architecture.html" aria-current="page">Architecture</a><a href="flows.html">Flows</a><a href="architecture.html" aria-current="page">English</a><a href="architecture.zh-CN.html">中文</a></div>
<b>Contents</b>
<ol>
<li><a href="#rules"><span>00</span>Three invariants</a></li>
<li><a href="#parts"><span>01</span>The parts</a></li>
<li><a href="#layers"><span>02</span>Handler layers</a></li>
<li><a href="#read"><span>03</span>Reading and scheduling</a></li>
<li><a href="#write"><span>04</span>Writes and backpressure</a></li>
<li><a href="#close"><span>05</span>Close and reclaim</a></li>
<li><a href="#balance"><span>06</span>Load balance</a></li>
<li><a href="#memory"><span>07</span>Buffers and memory</a></li>
<li><a href="#platform"><span>08</span>Platform backends</a></li>
<li><a href="#packages"><span>09</span>Packages</a></li>
</ol>
</nav>
<main>
<header>
<h1>fib architecture</h1>
<p>fib (Fast In Balance) is edge-triggered event loops with a pool of goroutines: the loops only wait for events and schedule the connections those make runnable onto logical workers, and every round of a connection, its reads, callbacks and writes, runs on a worker. This page describes the Go implementation as a whole, from the source at <code>main</code> (8a388d4). The step-by-step flow of each protocol is in <a href="flows.html">Protocol flows</a>.</p>
<div class="legend">
<span class="chip c-loop"><i></i>event loop (root / poller)</span>
<span class="chip c-work"><i></i>‹Name›-workers, the engine pool</span>
<span class="chip c-hs"><i></i>fib-tls-handshake pool</span>
<span class="chip c-str"><i></i>‹Name›-streams pool</span>
<span class="chip c-tmr"><i></i>timer goroutine</span>
<span class="chip c-usr"><i></i>the application's own goroutine</span>
</div>
</header>
<section id="rules">
<h2>Three invariants</h2>
<p class="lede">The whole concurrency model is reasoned about from these three rules. The rest of the design follows from them.</p>
<div class="rules">
<div class="rule"><b>Descriptors belong to the event loop</b><p>Only a loop calls <code>epoll_ctl</code>, accepts, and finally closes a descriptor. A worker that wants reads paused, a connection closed or a descriptor released says so through the command queue and an eventfd, and a loop that is already awake needs no wake-up.</p></div>
<div class="rule"><b>Order belongs to the connection</b><p>The unit of scheduling is the connection, not the event. The loop folds readiness into the connection's <code>pendingEvents</code> and does not submit it again while <code>scheduled</code> is set. A connection has at most one worker at a time, so OnData never runs twice at once or out of order, and OnClose always follows the OnData before it.</p></div>
<div class="rule"><b>Connections are bound to no thread</b><p>Each round is taken by whichever worker is idle, and the next round may be another goroutine's. What is balanced is the work waiting to run, not the number of connections.</p></div>
</div>
</section>
<section id="parts">
<h2>The parts</h2>
<p class="lede">An Engine owns the listeners, the event loop, its command queue and the worker pool. With <code>IOPollers</code>, the default on more than four CPUs, it also owns pollers: each is an Engine without listeners, with a loop, command queue and descriptor table of its own, sharing its parent's settings, handler, worker pool and server-wide budget.</p>
<div class="diagram"><pre class="mermaid">
flowchart LR
subgraph ENG["Engine (fib.New)"]
ROOT["root loop<br/>accept · UDP reads · commands"]
P0["poller 0<br/>waits · registers · closes fds"]
P1["poller N-1"]
CMD["command queue + eventfd<br/>refresh · close · detach · accept · dial"]
BUD["server-wide budget pendingTotal<br/>MaxPendingBytes"]
end
subgraph POOLS["goroutine pools"]
WK["‹Name›-workers<br/>every round of a connection"]
STR["‹Name›-streams<br/>HTTP/2 and HTTP/3 handlers"]
HS["fib-tls-handshake<br/>crypto/tls handshakes"]
end
BP["bufferpool<br/>power-of-two classes, one per process"]
TM["time.AfterFunc<br/>deadlines · UDP sweep · QUIC"]
ROOT -- "fd % N" --> P0
ROOT --> P1
P0 -- "GoTasks, one batch" --> WK
P1 --> WK
ROOT -- "UDP peer runnable" --> WK
WK -- "commands" --> CMD --> P0
WK -- "requests of multiplexed protocols" --> STR
P0 -- "OnOpen submits the handshake" --> HS
TM --> CMD
WK -.-> BP
STR -.-> BP
classDef loop fill:#e8effc,stroke:#2458c6,color:#16202c
classDef work fill:#e3f4f1,stroke:#0c7d72,color:#16202c
classDef hs fill:#fbf0de,stroke:#a86a12,color:#16202c
classDef str fill:#efe9fb,stroke:#6b45c8,color:#16202c
classDef tmr fill:#eceff3,stroke:#5f6b7a,color:#16202c
classDef usr fill:#fae6ed,stroke:#b23a62,color:#16202c
class ROOT,P0,P1,CMD,BUD loop
class WK work
class STR str
class HS hs
class TM,BP tmr
</pre></div>
<div class="tbl"><table>
<thead><tr><th>Part</th><th>How many, how large</th><th>What it does</th></tr></thead>
<tbody>
<tr><td>Root loop</td><td>One per Engine, the goroutine in <code>Run</code></td><td>Accepts; reads the shared UDP socket and sorts datagrams by peer; runs its own command queue</td></tr>
<tr><td>Poller</td><td>NumCPU÷4 rounded down, at least 1; <code>IOPollerCount</code> overrides; ignored on Windows</td><td>For the connections handed to it: waiting for events, pausing and resuming reads, registering and closing descriptors, OnOpen</td></tr>
<tr><td>‹Name›-workers</td><td>Adaptive; ceiling max(GOMAXPROCS×1000, NumCPU×20); shared by engines of one Name by default</td><td>Every round of every connection: reads, the OnData chain, coalesced writes, OnClose</td></tr>
<tr><td>‹Name›-streams</td><td>Adaptive; ceiling twice the widest engine pool of that Name, floor 0</td><td>HTTP/2 and HTTP/3 request handlers; HTTP/1's asynchronous handovers</td></tr>
<tr><td>fib-tls-handshake</td><td>Adaptive; ceiling 65536, one per process</td><td>Blocking TLS handshakes</td></tr>
</tbody>
</table></div>
<ul class="notes">
<li>A worker count is a ceiling, not a population. An adaptive pool grows when a task finds every worker busy, and at intervals retires half of the workers that sat idle throughout. A high ceiling costs nothing; a low one throttles bursts.</li>
<li>A worker makes its connection's read and write system calls itself and spends much of a round in the kernel rather than on a P, so the pool is oversubscribed relative to the cores. GOMAXPROCS is best left at the runtime's default, the cores.</li>
<li>The three pools are separate. An engine worker may wait on the stream pool's or the handshake pool's queue, never the reverse, so workers cannot all end up stuck in a submission.</li>
</ul>
<p class="ref">engine.go Engine · :284 openPollers · config.go DefaultPoolSizing · pollerCount · config.go · streampool · sidepool · taskpool/adaptive.go</p>
</section>
<section id="layers">
<h2>Handler layers</h2>
<p class="lede">Protocols stack by wrapping a <code>fib.Handler</code>. Input climbs the OnData chain; output goes through <code>Connection.Send</code>, and through the connection's <code>Layer</code> first when it has one. The handler on top always sees an ordinary connection.</p>
<div class="diagram"><pre class="mermaid">
flowchart TD
SOCK[("socket")]
CONN["fib.Connection<br/>readLoop · send queue · cork · watermarks"]
TLS["tls.Handler + layer<br/>decrypt → plaintext OnData; Send → encrypt → SendRaw"]
HTTP["http.ServerHandler<br/>HTTP/1 parsing · HTTP/2 framing · h2c upgrade"]
WS["websocket.ServerHandler<br/>opening handshake · frames"]
APP1["http.Handler<br/>ServeHTTP(Context, Request)"]
APP2["websocket.Handler<br/>OnOpen / OnMessage / OnClose"]
TUN["http.Tunnel<br/>ws.Upgrade: 101 or extended CONNECT"]
H3["http3.ServerHandler<br/>QUIC · QPACK, on a UDP engine"]
SOCK --> CONN
CONN --> TLS
CONN -- "cleartext" --> HTTP
CONN -- "cleartext" --> WS
TLS --> HTTP
TLS --> WS
HTTP --> APP1
WS --> APP2
APP1 -- "Upgrade" --> TUN --> APP2
CONN -- "UDP datagrams" --> H3 --> APP1
classDef loop fill:#e8effc,stroke:#2458c6,color:#16202c
classDef work fill:#e3f4f1,stroke:#0c7d72,color:#16202c
classDef hs fill:#fbf0de,stroke:#a86a12,color:#16202c
classDef str fill:#efe9fb,stroke:#6b45c8,color:#16202c
classDef tmr fill:#eceff3,stroke:#5f6b7a,color:#16202c
classDef usr fill:#fae6ed,stroke:#b23a62,color:#16202c
class CONN,SOCK loop
class TLS hs
class HTTP,WS,H3,TUN work
class APP1,APP2 usr
</pre></div>
<ul class="notes">
<li>A <code>fib.Handler</code> has four callbacks: <code>OnOpen</code>, <code>OnData</code>, <code>OnPriorityData</code> and <code>OnClose</code>. OnOpen runs on the event loop, the others on workers.</li>
<li>One <code>http.Handler</code> can serve HTTP/1 and HTTP/2 (a TCP engine) and HTTP/3 (a UDP engine), answering through the same <code>Context</code>.</li>
<li>WebSocket attaches in two ways: <code>websocket.ServerHandler</code> as a <code>fib.Handler</code> itself, or <code>Upgrade</code> called from an HTTP handler, which switches the whole connection on HTTP/1.1 and one stream on HTTP/2 and HTTP/3.</li>
<li>The HTTP middleware (compress, cors, csrf, etag, limiter, logger, pprof, recover, requestid, responsetime) wraps an <code>http.Handler</code> and knows nothing of the transport.</li>
</ul>
<p class="ref">handler.go · tls/tls.go · http/handler.go · http/tunnel.go · websocket/handler.go · websocket/upgrade.go · http3/server.go</p>
</section>
<section id="read">
<h2>Reading and scheduling</h2>
<p class="lede">From a kernel event to the application's callback and back to a connection that can be scheduled again. A loop submits one batch of connections per round, rather than one lock-and-wake cycle per connection.</p>
<div class="diagram"><pre class="mermaid">
flowchart LR
A["epoll_wait returns<br/>ET, 1024 events at most"] --> B["token → connection<br/>paged fd table + generation check"]
B --> C["noteEvent<br/>fold into pendingEvents<br/>ready only if not scheduled"]
C --> D["runReady<br/>GoTasks, the whole batch<br/>runtime.Gosched gives up the P"]
D --> E["worker: process<br/>flush, then read until empty<br/>OnData; one write at the end"]
E --> F["under the lock, no new events:<br/>scheduled = false"]
F -. "later events submit it again, perhaps to another worker" .-> C
classDef loop fill:#e8effc,stroke:#2458c6,color:#16202c
classDef work fill:#e3f4f1,stroke:#0c7d72,color:#16202c
classDef hs fill:#fbf0de,stroke:#a86a12,color:#16202c
classDef str fill:#efe9fb,stroke:#6b45c8,color:#16202c
classDef tmr fill:#eceff3,stroke:#5f6b7a,color:#16202c
classDef usr fill:#fae6ed,stroke:#b23a62,color:#16202c
class A,B,C,D loop
class E,F work
</pre></div>
<ul class="notes">
<li><b>Coalescing.</b> Readiness is level information to a connection, so repeated notifications are or-ed together and a hot connection cannot grow an unbounded event queue. A notification that is only EPOLLOUT with nothing queued is dropped, which keeps every new connection from being scheduled a second time.</li>
<li><b>Giving up the P.</b> After submitting, the loop calls <code>Gosched</code> so that the workers it just woke run on its P straight away. With 4 Ps serving HTTP/2 echoes over 10k connections that was worth 10% to 25%.</li>
<li><b>A loop holds no P while it waits.</b> With IOPollers a loop parks in the Go runtime's network poller instead of blocking in the <code>epoll_wait</code> system call.</li>
<li><b>Read buffers are borrowed per round.</b> The 16KB read buffer comes from bufferpool for the round and goes back at its end, so an idle connection holds none. A short read says the socket is empty, and no further read is made only to get EAGAIN.</li>
<li><b>UDP is the exception.</b> The loop reads a shared UDP socket itself, in batches, and queues each datagram on its peer's connection; the worker's round only hands the queue to the handler.</li>
</ul>
<p class="ref">poller_epoll.go:79 runLoop · engine.go:602 noteEvent · :377 runReady · :456 submitReady · connection.go:524 process · :777 readLoop · engine.go:138 deliverDatagram</p>
</section>
<section id="write">
<h2>Writes and backpressure</h2>
<p class="lede">What can be written at once is written at once; only the rest is queued. Queued bytes have two bounds, a watermark per connection and a budget for the whole engine, and crossing either pauses reads, leaving TCP flow control to slow the peer.</p>
<div class="diagram"><pre class="mermaid">
flowchart TD
S["Send / SendParts / SendOwned<br/>any goroutine"] --> L{"has a Layer"}
L -- "yes, TLS" --> ENC["layer.Send encrypts → SendRaw"] --> Q
L -- no --> Q{"queue empty, no flush running, not corked"}
Q -- yes --> W["non-blocking write"]
W --> F{"all written"}
F -- yes --> DONE["return: nothing queued, no registration change"]
F -- no --> QU
Q -- "no; corked in a round" --> QU["queue the rest<br/>pendingBytes and pendingTotal grow together"]
QU --> CK["end of round, uncork: flushOutput<br/>writev of up to 64 items / sendfile"]
QU --> WM{"high watermark, 64KB<br/>or the budget exhausted, if set"}
WM -- yes --> RF["commandRefresh → loop<br/>pauseDecision → EPOLL_CTL_MOD drops EPOLLIN"]
QU --> EDGE["EPOLLOUT edge → a round → flushOutput"]
EDGE --> LOW{"down to the low watermark, 16KB<br/>budget back to a quarter"}
LOW -- yes --> RS["commandRefresh → reads resume<br/>re-arming reports bytes already in the socket"]
classDef loop fill:#e8effc,stroke:#2458c6,color:#16202c
classDef work fill:#e3f4f1,stroke:#0c7d72,color:#16202c
classDef hs fill:#fbf0de,stroke:#a86a12,color:#16202c
classDef str fill:#efe9fb,stroke:#6b45c8,color:#16202c
classDef tmr fill:#eceff3,stroke:#5f6b7a,color:#16202c
classDef usr fill:#fae6ed,stroke:#b23a62,color:#16202c
class S,ENC,Q,W,F,DONE,QU,CK,WM,EDGE,LOW,L work
class RF,RS loop
</pre></div>
<ul class="notes">
<li><b>Write interest is permanent.</b> EPOLLOUT is armed from registration on, so queueing needs no registration change; only a watermark crossing costs an <code>epoll_ctl</code>.</li>
<li><b>Cork.</b> A round's replies accumulate in one contiguous buffer and reach the socket in one write when it ends. A handler streaming a response calls <code>Flush</code> to send its first part early, and an application may <code>Cork</code> for itself.</li>
<li><b>Hysteresis.</b> Reads pause at the high watermark (64KB by default) and resume at a quarter of it, so that replies do not cross the line back and forth; the budget, off by default and set with <code>MaxPendingBytes</code>, likewise resumes at a quarter. At high connection counts it is the bound on the sum, which the watermark alone admits times the connection count.</li>
<li><b>A connection paused by the budget</b> may have nothing of its own left to flush, and so no event of its own to re-evaluate it. The loop keeps such connections in <code>budgetPaused</code> and resumes them when the budget recovers, and a connection on another poller that drains the budget wakes the loops holding some.</li>
<li><b>Read-side backpressure.</b> <code>HoldReads</code> lets an application stop reading while it works through what it has, as a streamed request body does; releasing it redelivers what the socket already held.</li>
<li><code>Stats()</code> reports how often each kind of pause happened, how many have been lifted and the total queued now. <code>SendFile</code> uses sendfile and is not charged to the budget.</li>
</ul>
<p class="ref">connection.go:393 send · :308 pauseDecision · :709 uncork · flushOutput · engine.go:677 refreshConnection · resumeBudgetPaused · releaseBudget · Stats</p>
</section>
<section id="close">
<h2>Close and reclaim</h2>
<p class="lede">Every close takes the same path through the loop. The connection stops at once, but OnClose and the descriptor's release are queued with its rounds, as an event is.</p>
<div class="diagram"><pre class="mermaid">
flowchart LR
subgraph SRC["where a close comes from"]
S1["Close / CloseWithError"]
S2["in a round: EOF, I/O error, RDHUP"]
S3["deadline timer"]
S4["CloseAfterSend: queue drained"]
S5["UDP idle sweep"]
end
C["commandClose"]
subgraph LOOP["event loop: closeConnection"]
L1["closed = true, reason kept<br/>send queue dropped, budget returned<br/>deadlines stopped"]
L2["closePending = true<br/>schedule a last round unless one is"]
L3["detach<br/>EPOLL_CTL_DEL · close(fd)<br/>clear the table entry"]
L1 --> L2
end
subgraph WK["worker: the last round"]
W1["the OnData before it returns first"]
W2["finishClose → OnClose(c, err)"]
W1 --> W2
end
S1 --> C
S2 --> C
S3 --> C
S4 --> C
S5 -- "commandUDPSweep" --> L1
C --> L1
L2 --> W1
W2 -- "commandDetach" --> L3
classDef loop fill:#e8effc,stroke:#2458c6,color:#16202c
classDef work fill:#e3f4f1,stroke:#0c7d72,color:#16202c
classDef hs fill:#fbf0de,stroke:#a86a12,color:#16202c
classDef str fill:#efe9fb,stroke:#6b45c8,color:#16202c
classDef tmr fill:#eceff3,stroke:#5f6b7a,color:#16202c
classDef usr fill:#fae6ed,stroke:#b23a62,color:#16202c
class L1,L2,L3,C loop
class W1,W2,S2,S4 work
class S3,S5 tmr
class S1 usr
</pre></div>
<ul class="notes">
<li>While a round is still running on a worker, the descriptor it reads and writes is not closed, and so cannot be handed to another connection under it.</li>
<li>Descriptor reuse is guarded by a generation: a token's low half is the descriptor and its high half a generation, so an event left over from a descriptor's previous owner resolves to nothing.</li>
<li>Closing your own connection in OnData and then waiting for what OnClose reports deadlocks: that report waits for this round to return.</li>
<li>When an engine closes it stops its loops and pollers, waits for the rounds in flight, and then runs the last rounds still owed, so no closed connection loses its OnClose.</li>
</ul>
<p class="ref">engine.go:742 closeConnection · connection.go:650 finishClose · engine_unix.go detach · Close · deadline.go</p>
</section>
<section id="balance">
<h2>Load balance</h2>
<p class="lede">Connections spread evenly are not work spread evenly: a few hot connections or heavy tasks can land on one thread. fib deals with that at four levels.</p>
<div class="tbl"><table>
<thead><tr><th>Level</th><th>What it does</th><th>Cost and trade-off</th></tr></thead>
<tbody>
<tr><td>Workers</td><td>Each round of a connection goes to an idle worker, with no affinity; the adaptive pool queues by P and takes batches</td><td>A handler that blocks holds up its own connection only, and the pool grows to absorb it</td></tr>
<tr><td>Pollers</td><td>Accepted connections go to <code>fd % pollerCount</code>; a poller only waits, about 0.2µs a request against 4.5µs on the workers</td><td>More pollers compete with the workers for Ps; one per 4 CPUs is the default</td></tr>
<tr><td>Accept</td><td>The root loop accepts and hands on by default; on Linux <code>ReusePort</code> has every poller listen and accept for itself</td><td>ReusePort lifts the one loop's accept ceiling, but a connection stays on the poller the kernel's hash chose, however busy</td></tr>
<tr><td>Multiplexing</td><td>HTTP/2 and HTTP/3 handlers run on the stream pool, so one connection's requests are served concurrently</td><td><code>MaxConcurrentHandlers</code> bounds one connection; the request over the limit runs on the reader</td></tr>
</tbody>
</table></div>
</section>
<section id="memory">
<h2>Buffers and memory</h2>
<ul class="notes">
<li><b>bufferpool</b> is one package-level pool for the process. Every capacity is a power of two, which is exactly one of Go's allocator size classes, so nothing is paid for rounding, and each class keeps a reserve behind its <code>sync.Pool</code> that a collection does not empty.</li>
<li><b>Read buffers</b> are 16KB and borrowed per round. The bytes are lent to the handler for the length of OnData; protocol parsers parse in place and copy only what is left over.</li>
<li><b>Send buffers</b> are taken at twice the read buffer, aligned to a pool class, which holds a round's replies. A buffer a single large message grew goes back to the class its capacity belongs to and cannot inflate the ordinary ones.</li>
<li><b>The connection table</b> is paged and indexed by descriptor, 4096 entries a page: a lookup is two bounds checks rather than a hash, and only the page directory ever grows.</li>
<li><b>TLS</b> keeps no crypto/tls buffers after the handshake and opens records straight from the round's read buffer. Each UDP datagram takes a buffer from the pool, which QUIC gives back when it is done.</li>
</ul>
<p class="ref">bufferpool/bufferpool.go · engine.go acquireSendBuffer · engine_unix.go trackConnection</p>
</section>
<section id="platform">
<h2>Platform backends</h2>
<p class="lede">The rest of the engine is written against readiness. Each backend translates what it observes into the same event bits, so the workers, the queueing and the backpressure are the same code everywhere.</p>
<div class="tbl"><table>
<thead><tr><th>Platform</th><th>Backend</th><th>Notes</th></tr></thead>
<tbody>
<tr><td>Linux</td><td>epoll, edge-triggered, eventfd wake-ups</td><td>IOPollers; ReusePort spreads accepts and UDP; reads and writes are raw system calls, recvfrom / sendto / sendmsg under <code>SocketSyscalls</code>; UDP uses recvmmsg / sendmmsg</td></tr>
<tr><td>macOS</td><td>kqueue</td><td>IOPollers supported; <code>SO_REUSEPORT</code> does not spread TCP connections between sockets, so the root loop still accepts</td></tr>
<tr><td>Windows</td><td>I/O completion port</td><td>A zero-byte overlapped WSARecv plays the read edge and an overlapped WSASend's completion the write edge; one loop, IOPollers ignored</td></tr>
<tr><td>Others</td><td><code>*_other.go</code></td><td>A fallback on the standard library, a goroutine per connection, with the same API</td></tr>
</tbody>
</table></div>
<p class="ref">poller_epoll.go · poller_kqueue.go · engine_windows.go · internal/sys/sockio_linux.go · internal/udpbatch/batch_linux.go · engine_other.go</p>
</section>
<section id="packages">
<h2>Packages</h2>
<div class="tbl"><table>
<thead><tr><th>Package</th><th>Contents</th></tr></thead>
<tbody>
<tr><td><code>fib</code></td><td>Engine, Connection, Handler, Config; TCP, Unix sockets and UDP; Dial and DialWith (a chosen local address and port range), OpenUDPPeer, the net.Conn adapter, deadlines, SendFile, HoldReads</td></tr>
<tr><td><code>taskpool</code></td><td>Interchangeable bounded schedulers: Elastic, Adaptive, AdaptiveChan, Inline</td></tr>
<tr><td><code>streampool</code> · <code>sidepool</code></td><td>The stream pools, one per engine name; the handshake and client pools, one per process</td></tr>
<tr><td><code>bufferpool</code></td><td>The shared buffer pool in power-of-two classes</td></tr>
<tr><td><code>tls</code></td><td>TLS over a connection: crypto/tls handshakes, with AES-GCM and AES-CBC records protected by the package itself; sans-IO DTLS 1.2 with DTLS-SRTP for WebRTC</td></tr>
<tr><td><code>http</code> · <code>hpack</code></td><td>HTTP/1.x and HTTP/2 servers and asynchronous clients; Context, streamed bodies, Tunnel, StreamPool</td></tr>
<tr><td><code>http3</code> · <code>http3/quic</code> · <code>http3/qpack</code></td><td>HTTP/3 server and client, with their own QUIC and QPACK</td></tr>
<tr><td><code>websocket</code></td><td>Server, client, frame-at-a-time delivery, permessage-deflate, upgrades over HTTP/1, 2 and 3</td></tr>
<tr><td><code>webrtc/*</code></td><td>PeerConnection and a UDP Mux shared by many; ICE, STUN, TURN (client and server), SDP, SCTP data channels, SRTP and RTP</td></tr>
<tr><td><code>media/*</code></td><td>Live streaming on a hub: RTMP, RTSP, SRT, HTTP-FLV, HLS and WHIP/WHEP, remuxed without transcoding</td></tr>
<tr><td><code>middleware/*</code></td><td>HTTP middleware</td></tr>
<tr><td><code>c/</code></td><td>The earlier C implementation (one epoll loop and a pthread pool), not covered here</td></tr>
</tbody>
</table></div>
</section>
</main>
</div>
<script src="https://cdn.jsdelivr.net/npm/mermaid@10.9.1/dist/mermaid.min.js"></script>
<script>mermaid.initialize({startOnLoad:true,theme:"neutral",flowchart:{htmlLabels:true}});</script>
</body>
</html>