include/sa/sa_map.h

filter: Statementstmt 83.5% 76 / 91 Branchbran 56.0% 37 / 66 Conditioncond n/a MC/DCmcdc n/a Subroutinesub n/a Podpod n/a totaltotal 71.9% 113 / 157 CC 0 SCAR 0
CC
0
Cov
0%
CRAP 0
« include/sa/sa_frozen.h ↑ Summary include/sa/sa_wake.h »
1 #ifndef SA_MAP_H
2 #define SA_MAP_H
3  
4 /* sa_map.h - where the memory comes from, and how a second process reaches it.
5 * Perl-free.
6 *
7 * ---- two ways in, one structure ---------------------------------------------
8 *
9 * ANONYMOUS mmap(MAP_SHARED|MAP_ANONYMOUS) before a fork, inherited. The
10 * simple case. No name, no cleanup, gone when the last process
11 * exits.
12 * NAMED shm_open + ftruncate + mmap on POSIX, CreateFileMapping backed
13 * by the pagefile on Windows. A process that is not a fork
14 * descendant can attach, which is the whole reason the offsets
15 * rule in sa_format.h exists.
16 *
17 * ---- the create race, which is not hypothetical ----------------------------
18 *
19 * A freshly ftruncate'd segment reads as zeros. Two processes racing to create
20 * the same name both end up with a valid mapping, and the loser of O_EXCL maps
21 * a segment whose header the winner has not finished writing.
22 *
23 * So the winner writes the whole header and stores `magic` LAST with a release
24 * store, and the loser spins bounded on `magic` and then validates. It is the
25 * same commit discipline a record uses one layer up: everything, then one word,
26 * released. A loser that times out fails open rather than guessing.
27 *
28 * ---- lifetime, and why destroy is explicit ---------------------------------
29 *
30 * shm_unlink removes the NAME, not the mapping - existing mappings stay valid
31 * until their last user unmaps. A creator that crashes therefore leaves the
32 * segment behind, which is a feature (a restarting server reattaches to a live
33 * region and its readers never noticed) and a leak (nothing removes a name
34 * nobody will open again). There is no way to have one without the other, so
35 * destroy is a deliberate call and the POD says who is expected to make it.
36 */
37  
38 #include "sa/sa_format.h"
39  
40 #include <stdlib.h>
41 #include <string.h>
42  
43 #ifdef _WIN32
44 # include <windows.h>
45 #else
46 # include <sys/types.h>
47 # include <sys/mman.h>
48 # include <sys/stat.h>
49 # include <fcntl.h>
50 # include <unistd.h>
51 # include <errno.h>
52 #endif
53  
54  
55 /* ---- WAITING FOR A HEADER SOMEBODY ELSE IS STILL PUBLISHING ----------------
56 *
57 * Every structure in this dist commits the same way: write the body, then store
58 * one magic word with a release. A process that finds the magic unset has to
59 * wait for it, and this is the one place that wait is implemented.
60 *
61 * BOUNDED BY TIME, not by turns. A spin count is the wrong quantity in both
62 * directions: two hundred thousand iterations is under a millisecond on a fast
63 * machine, so a creator that was merely descheduled gets abandoned, and it is
64 * also a core burned solid while waiting. This sleeps between looks and gives
65 * up when the time is gone. The iteration backstop is only there so a clock
66 * stepped backwards cannot turn a bounded wait into an unbounded one. */
67 756 static int sa_wait_magic32(volatile uint32_t *p, uint32_t want) {
68 756 uint64_t deadline = sa_now_us() + SA_CREATE_WAIT_US;
69 756 long backstop = 0;
70 756 ▶ while (sa_at_load32_acq(p) != want) {
Branch: 1 branch
BranchTrueFalseTotal
while (sa_at_load32_acq(p) != want) { 0 756 756
71 0 ▶ if (++backstop > 1000000L) return 0;
Branch: 1 branch
BranchTrueFalseTotal
if (++backstop > 1000000L) return 0; 0 0 0
72 0 ▶ if (sa_now_us() >= deadline) return 0;
Branch: 1 branch
BranchTrueFalseTotal
if (sa_now_us() >= deadline) return 0; 0 0 0
73 0 sa_stall(SA_CREATE_POLL_US);
74 }
75 756 return 1;
76 }
77  
78 #define SA_SRC_ANON 0
79 #define SA_SRC_NAMED 1
80  
81 /* The process-local half of a region. NONE of this is in the mapping: `base`
82 * in particular is this process's address for it, which is exactly the thing
83 * that must never be written into shared memory. */
84 typedef struct sa_map {
85 void *base;
86 uint64_t len;
87 int src;
88 #ifdef _WIN32
89 HANDLE mh;
90 #else
91 char *name; /* strdup'd, for destroy; NULL when anonymous */
92 #endif
93 } sa_map;
94  
95 /* ---- the platform half ----------------------------------------------------
96 *
97 * Three primitives, one shape: reserve `len` bytes of shared memory, tell the
98 * caller whether it was freshly created (so it knows whether to write the
99 * header or wait for one), and hand back the base.
100 */
101  
102 #ifdef _WIN32
103  
104 static int sa_os_map(sa_map *m, const char *name, uint64_t len, int *created,
105 int may_create) {
106 HANDLE mh;
107 void *addr;
108 DWORD hi = (DWORD)(len >> 32), lo = (DWORD)(len & 0xFFFFFFFFu);
109  
110 m->base = NULL; m->len = 0; m->mh = INVALID_HANDLE_VALUE;
111 m->src = name ? SA_SRC_NAMED : SA_SRC_ANON;
112  
113 if (!may_create) {
114 /* Attach only. OpenFileMapping fails rather than creating, which is
115 * the whole difference between the two entries. */
116 if (!name) return SA_E_NOENT;
117 mh = OpenFileMappingA(FILE_MAP_ALL_ACCESS, FALSE, name);
118 if (!mh) return SA_E_NOENT;
119 if (created) *created = 0;
120 /* THE SECTION'S SIZE WINS, exactly as it does on POSIX below.
121 *
122 * An attacher does not know how big the region is; the creator decided
123 * that, and asking the attacher to guess is the out-of-band agreement
124 * the registry exists to abolish. Mapping the caller's guess maps a
125 * PREFIX, the header's own `total` then runs past the end of the view,
126 * and sa_check_header correctly refuses the whole thing - so `attach`
127 * failed on every region bigger than the guess, which on Windows is
128 * every region, since named is the only mode there is.
129 *
130 * Zero means "to the end of the section", and VirtualQuery is how the
131 * size comes back: there is no fstat here and the section carries no
132 * length of its own that a caller can ask for. */
133 len = 0;
134 }
135 else {
136 /* INVALID_HANDLE_VALUE means pagefile-backed: no file on disk, which
137 * is what a shared region wants. A NULL name gives an unnamed mapping,
138 * which on Windows is inherited only by explicit handle duplication -
139 * there is no fork, so the anonymous mode exists here only for a
140 * single process. */
141 mh = CreateFileMappingA(INVALID_HANDLE_VALUE, NULL, PAGE_READWRITE,
142 hi, lo, name);
143 if (!mh) return SA_E_MAP;
144 if (created) *created = (GetLastError() != ERROR_ALREADY_EXISTS);
145 }
146  
147 addr = MapViewOfFile(mh, FILE_MAP_ALL_ACCESS, 0, 0, (SIZE_T)len);
148 if (!addr) { CloseHandle(mh); return SA_E_MAP; }
149  
150 if (!len) {
151 MEMORY_BASIC_INFORMATION mbi;
152 if (!VirtualQuery(addr, &mbi, sizeof mbi)) {
153 UnmapViewOfFile(addr);
154 CloseHandle(mh);
155 return SA_E_MAP;
156 }
157 len = (uint64_t)mbi.RegionSize;
158 }
159  
160 m->base = addr; m->len = len; m->mh = mh;
161 return SA_E_OK;
162 }
163  
164 static void sa_os_unmap(sa_map *m) {
165 if (m->base) UnmapViewOfFile(m->base);
166 if (m->mh != INVALID_HANDLE_VALUE) CloseHandle(m->mh);
167 m->base = NULL; m->len = 0; m->mh = INVALID_HANDLE_VALUE;
168 }
169  
170 /* A Windows section disappears with its last handle, so there is no name to
171 * unlink and nothing to leak. */
172 static int sa_os_destroy(const char *name) { (void)name; return SA_E_OK; }
173  
174 #else
175  
176 161 static int sa_os_map(sa_map *m, const char *name, uint64_t len, int *created,
177 int may_create) {
178 void *addr;
179  
180 161 m->base = NULL; m->len = 0; m->name = NULL;
181 161 m->src = name ? SA_SRC_NAMED : SA_SRC_ANON;
182  
183 161 ▶ if (!name) {
Branch: 1 branch
BranchTrueFalseTotal
if (!name) { 149 12 161
184 149 ▶ if (!may_create) return SA_E_NOENT; /* nothing to attach to */
Branch: 1 branch
BranchTrueFalseTotal
if (!may_create) return SA_E_NOENT; /* nothing to attach to */ 0 149 149
185 149 addr = mmap(NULL, (size_t)len, PROT_READ | PROT_WRITE,
186 MAP_SHARED | MAP_ANON, -1, 0);
187 149 ▶ if (addr == MAP_FAILED) return SA_E_MAP;
Branch: 1 branch
BranchTrueFalseTotal
if (addr == MAP_FAILED) return SA_E_MAP; 0 149 149
188 149 ▶ if (created) *created = 1;
Branch: 1 branch
BranchTrueFalseTotal
if (created) *created = 1; 149 0 149
189 149 m->base = addr; m->len = len;
190 149 return SA_E_OK;
191 }
192  
193 {
194 12 int fd, mine = 0;
195 /* ATTACH MUST NOT CREATE. Passing O_CREAT here unconditionally is how
196 * `attach` on a name nobody has ever used hands back an empty region
197 * instead of saying no - and the caller then reads zeros and believes
198 * them. The two entries are different questions and get different
199 * flags. */
200 12 ▶ if (may_create) {
Branch: 1 branch
BranchTrueFalseTotal
if (may_create) { 5 7 12
201 5 mine = 1;
202 5 fd = shm_open(name, O_RDWR | O_CREAT | O_EXCL, 0600);
203 5 ▶ if (fd < 0 && errno == EEXIST) {
Branch: 2 branches
BranchTrueFalseTotal
if (fd < 0 && errno == EEXIST) { 0 5 5
if (fd < 0 && errno == EEXIST) { 0 0 0
204 0 mine = 0;
205 0 fd = shm_open(name, O_RDWR, 0600);
206 }
207 }
208 else {
209 7 fd = shm_open(name, O_RDWR, 0600);
210 }
211 12 ▶ if (fd < 0) return (errno == ENOENT) ? SA_E_NOENT : SA_E_MAP;
Branch: 2 branches
BranchTrueFalseTotal
if (fd < 0) return (errno == ENOENT) ? SA_E_NOENT : SA_E_MAP; 2 10 12
if (fd < 0) return (errno == ENOENT) ? SA_E_NOENT : SA_E_MAP; 2 0 2
212  
213 /* Only the creator sizes it. A second process calling ftruncate on a
214 * live segment would truncate it under everybody else. */
215 10 ▶ if (mine && ftruncate(fd, (off_t)len) != 0) {
Branch: 2 branches
BranchTrueFalseTotal
if (mine && ftruncate(fd, (off_t)len) != 0) { 5 5 10
if (mine && ftruncate(fd, (off_t)len) != 0) { 0 5 5
216 0 close(fd);
217 0 shm_unlink(name);
218 0 return SA_E_MAP;
219 }
220 10 ▶ if (!mine) {
Branch: 1 branch
BranchTrueFalseTotal
if (!mine) { 5 5 10
221 /* The winner may not have got to ftruncate yet, so a zero-length
222 * segment here is a race to wait out, not a refusal. */
223 struct stat st;
224 5 uint64_t deadline = sa_now_us() + SA_CREATE_WAIT_US;
225 5 long backstop = 0;
226 for (;;) {
227 5 ▶ if (fstat(fd, &st) != 0) { close(fd); return SA_E_MAP; }
Branch: 1 branch
BranchTrueFalseTotal
if (fstat(fd, &st) != 0) { close(fd); return SA_E_MAP; } 0 5 5
228 5 ▶ if ((uint64_t)st.st_size >= len) break;
Branch: 1 branch
BranchTrueFalseTotal
if ((uint64_t)st.st_size >= len) break; 5 0 5
229 /* A SLEEP, not a spin. This loop contains a SYSCALL, so a spin
230 * bound of two hundred thousand was two hundred thousand
231 * fstats - a core burned to discover the creator had not got to
232 * ftruncate yet. */
233 0 ▶ if (++backstop > 1000000L) { close(fd); return SA_E_MAP; }
Branch: 1 branch
BranchTrueFalseTotal
if (++backstop > 1000000L) { close(fd); return SA_E_MAP; } 0 0 0
234 0 ▶ if (sa_now_us() >= deadline) { close(fd); return SA_E_MAP; }
Branch: 1 branch
BranchTrueFalseTotal
if (sa_now_us() >= deadline) { close(fd); return SA_E_MAP; } 0 0 0
235 0 sa_stall(SA_CREATE_POLL_US);
236 }
237 /* THE SEGMENT'S SIZE WINS, not the caller's.
238 *
239 * An attacher does not know how big the region is - that is the
240 * creator's decision, and asking the attacher to guess it right is
241 * exactly the out-of-band agreement the name registry exists to
242 * abolish. So `len` is a MINIMUM here, and what gets mapped is
243 * whatever is actually there. Mapping the caller's guess instead
244 * maps a prefix, and the header's own `total` then runs past the
245 * end of the mapping, which the validator correctly refuses. */
246 5 len = (uint64_t)st.st_size;
247 }
248  
249 10 addr = mmap(NULL, (size_t)len, PROT_READ | PROT_WRITE, MAP_SHARED,
250 fd, 0);
251 /* The mapping keeps the segment alive, so the descriptor goes now -
252 * the same reason a mapped file's fd is closed immediately. */
253 10 close(fd);
254 10 ▶ if (addr == MAP_FAILED) return SA_E_MAP;
Branch: 1 branch
BranchTrueFalseTotal
if (addr == MAP_FAILED) return SA_E_MAP; 0 10 10
255  
256 /* The name is kept only so `destroy` has something to unlink. Losing
257 * it to a failed malloc would make destroy silently do nothing, which
258 * is a leaked segment nobody can account for later - so the mapping is
259 * refused instead. A caller that cannot allocate 32 bytes has worse
260 * problems than a region it did not get. */
261 10 m->name = (char *)malloc(strlen(name) + 1);
262 10 ▶ if (!m->name) {
Branch: 1 branch
BranchTrueFalseTotal
if (!m->name) { 0 10 10
263 0 munmap(addr, (size_t)len);
264 0 return SA_E_NOMEM;
265 }
266 10 strcpy(m->name, name);
267 10 ▶ if (created) *created = mine;
Branch: 1 branch
BranchTrueFalseTotal
if (created) *created = mine; 10 0 10
268 10 m->base = addr; m->len = len;
269 10 return SA_E_OK;
270 }
271 }
272  
273 159 static void sa_os_unmap(sa_map *m) {
274 159 ▶ if (m->base) munmap(m->base, (size_t)m->len);
Branch: 1 branch
BranchTrueFalseTotal
if (m->base) munmap(m->base, (size_t)m->len); 159 0 159
275 159 ▶ if (m->name) { free(m->name); m->name = NULL; }
Branch: 1 branch
BranchTrueFalseTotal
if (m->name) { free(m->name); m->name = NULL; } 10 149 159
276 159 m->base = NULL; m->len = 0;
277 159 }
278  
279 8 static int sa_os_destroy(const char *name) {
280 8 ▶ if (shm_unlink(name) != 0) return (errno == ENOENT) ? SA_E_NOENT : SA_E_MAP;
Branch: 2 branches
BranchTrueFalseTotal
if (shm_unlink(name) != 0) return (errno == ENOENT) ? SA_E_NOENT : SA_E_MAP; 4 4 8
if (shm_unlink(name) != 0) return (errno == ENOENT) ? SA_E_NOENT : SA_E_MAP; 4 0 4
281 4 return SA_E_OK;
282 }
283  
284 #endif /* _WIN32 */
285  
286 /* ---- the portable half ----------------------------------------------------- */
287  
288 /* Create or attach, and hand back a mapping whose header is valid.
289 *
290 * `name` NULL means anonymous. `len` is the whole region including the header;
291 * it is ignored when attaching an existing named segment, whose own header
292 * says how big it is.
293 */
294 161 static int sa_map_open(sa_map *m, const char *name, uint64_t len,
295 uint32_t reg_max, int *created, int may_create)
296 {
297 161 int rc, mine = 0;
298 sa_header *h;
299  
300 #if !SA_HAVE_ATOMICS
301 (void)m; (void)name; (void)len; (void)reg_max; (void)created;
302 (void)may_create;
303 return SA_E_NOATOMICS;
304 #else
305 161 rc = sa_os_map(m, name, len, &mine, may_create);
306 161 ▶ if (rc != SA_E_OK) return rc;
Branch: 1 branch
BranchTrueFalseTotal
if (rc != SA_E_OK) return rc; 2 159 161
307 159 ▶ if (created) *created = mine;
Branch: 1 branch
BranchTrueFalseTotal
if (created) *created = mine; 159 0 159
308  
309 159 h = (sa_header *)m->base;
310  
311 159 ▶ if (mine) {
Branch: 1 branch
BranchTrueFalseTotal
if (mine) { 154 5 159
312 /* Write everything, then publish `magic` last. Until that store lands,
313 * a racing attacher sees zeros and waits. */
314 154 memset(h, 0, (size_t)sa_header_bytes(reg_max));
315 154 h->layout = SA_LAYOUT_VERSION;
316 154 h->hdr_size = (uint16_t)sizeof(sa_header);
317 154 h->endian = SA_ENDIAN_PROBE;
318 154 h->word = (uint32_t)sizeof(void *);
319 154 h->total = len;
320 154 h->reg_off = sa_align_up((uint64_t)sizeof(sa_header));
321 154 h->reg_max = reg_max;
322 154 h->reg_used = 0;
323 154 h->peers_off = sa_peers_offset(reg_max);
324 154 h->peers_max = SA_PEERS_MAX;
325 154 h->peers_used = 0;
326 154 h->stall_us = 0;
327 /* 250ms before a reader starts asking whether a hole's publisher is
328 * dead. Long enough that an ordinary preemption is just a wait, short
329 * enough that a real crash does not stall a tail visibly. */
330 154 h->reap_grace_us = 250000;
331 154 sa_at_store64_rel(&h->brk, sa_header_bytes(reg_max));
332 154 sa_at_store32_rel(&h->magic, SA_MAGIC);
333 }
334 5 ▶ else if (!sa_wait_magic32(&h->magic, SA_MAGIC)) {
Branch: 1 branch
BranchTrueFalseTotal
else if (!sa_wait_magic32(&h->magic, SA_MAGIC)) { 0 5 5
335 0 sa_os_unmap(m);
336 0 return SA_E_MAGIC;
337 }
338  
339 159 rc = sa_check_header(m->base, m->len);
340 159 ▶ if (rc != SA_E_OK) { sa_os_unmap(m); return rc; }
Branch: 1 branch
BranchTrueFalseTotal
if (rc != SA_E_OK) { sa_os_unmap(m); return rc; } 0 159 159
341 159 return SA_E_OK;
342 #endif
343 }
344  
345 159 static void sa_map_release(sa_map *m) {
346 159 ▶ if (m && m->base) sa_os_unmap(m);
Branch: 2 branches
BranchTrueFalseTotal
if (m && m->base) sa_os_unmap(m); 159 0 159
if (m && m->base) sa_os_unmap(m); 159 0 159
347 159 }
348  
349 #endif /* SA_MAP_H */
« include/sa/sa_frozen.h ↑ Summary include/sa/sa_wake.h »