authorgravatar for mlugg@mlugg.co.ukMatthew Lugg <mlugg@mlugg.co.uk> 2025-09-19 13:35:12+01:00
committergravatar for mlugg@mlugg.co.ukMatthew Lugg <mlugg@mlugg.co.uk> 2025-09-30 13:44:55+01:00
log099a95041054e456ebefbd75f6a4f9f6961002be
tree6293805ebdf2664d5b5906e614297972a7c8da6f
parent9c1821d3bfadc5eddd4dff271a4920c03ee0ffea
signaturelock-open Commit is signed but in an unrecognized format.

std.debug.SelfInfo: thread safety

This has been a TODO for ages, but in the past it didn't really matter because stack traces are typically printed to stderr for which a mutex is held so in practice there was a mutex guarding usage of `SelfInfo`. However, now that `SelfInfo` is also used for simply capturing traces, thread safety is needed. Instead of just a single mutex, though, there are a couple of different mutexes involved; this helps make critical sections smaller, particularly when unwinding the stack as `unwindFrame` doesn't typically need to hold any lock at all.

6 files changed, 136 insertions(+), 44 deletions(-)

lib/std/debug.zig+5-5
......@@ -238,7 +238,6 @@ pub fn print(comptime fmt: []const u8, args: anytype) void {
238238 nosuspend bw.print(fmt, args) catch return;
239239}
240240
241/// TODO multithreaded awareness
242241/// Marked `inline` to propagate a comptime-known error to callers.
243242pub inline fn getSelfDebugInfo() !*SelfInfo {
244243 if (!SelfInfo.target_supported) return error.UnsupportedTarget;
......@@ -1169,7 +1168,8 @@ test printLineFromFile {
11691168 }
11701169}
11711170
1172/// TODO multithreaded awareness
1171/// The returned allocator should be thread-safe if the compilation is multi-threaded, because
1172/// multiple threads could capture and/or print stack traces simultaneously.
11731173fn getDebugInfoAllocator() Allocator {
11741174 // Allow overriding the debug info allocator by exposing `root.debug.getDebugInfoAllocator`.
11751175 if (@hasDecl(root, "debug") and @hasDecl(root.debug, "getDebugInfoAllocator")) {
......@@ -1177,10 +1177,10 @@ fn getDebugInfoAllocator() Allocator {
11771177 }
11781178 // Otherwise, use a global arena backed by the page allocator
11791179 const S = struct {
1180 var arena: ?std.heap.ArenaAllocator = null;
1180 var arena: std.heap.ArenaAllocator = .init(std.heap.page_allocator);
1181 var ts_arena: std.heap.ThreadSafeAllocator = .{ .child_allocator = arena.allocator() };
11811182 };
1182 if (S.arena == null) S.arena = .init(std.heap.page_allocator);
1183 return S.arena.?.allocator();
1183 return S.ts_arena.allocator();
11841184}
11851185
11861186/// Whether or not the current target can print useful debug information when a segfault occurs.
lib/std/debug/Dwarf.zig+1-1
......@@ -346,7 +346,7 @@ pub fn deinit(di: *Dwarf, gpa: Allocator) void {
346346 di.* = undefined;
347347}
348348
349pub fn getSymbolName(di: *Dwarf, address: u64) ?[]const u8 {
349pub fn getSymbolName(di: *const Dwarf, address: u64) ?[]const u8 {
350350 // Iterate the function list backwards so that we see child DIEs before their parents. This is
351351 // important because `DW_TAG_inlined_subroutine` DIEs will have a range which is a sub-range of
352352 // their caller, and we want to return the callee's name, not the caller's.
lib/std/debug/SelfInfo.zig+47-12
......@@ -18,7 +18,21 @@ const root = @import("root");
1818
1919const SelfInfo = @This();
2020
21modules: if (target_supported) std.AutoArrayHashMapUnmanaged(usize, Module.DebugInfo) else void,
21/// Locks access to `modules`. However, does *not* lock the `Module.DebugInfo`, nor `lookup_cache`
22/// the implementation is responsible for locking as needed in its exposed methods.
23///
24/// TODO: to allow `SelfInfo` to work on freestanding, we currently just don't use this mutex there.
25/// That's a bad solution, but a better one depends on the standard library's general support for
26/// "bring your own OS" being improved.
27modules_mutex: switch (builtin.os.tag) {
28 else => std.Thread.Mutex,
29 .freestanding, .other => struct {
30 fn lock(_: @This()) void {}
31 fn unlock(_: @This()) void {}
32 },
33},
34/// Value is allocated into gpa to give it a stable pointer.
35modules: if (target_supported) std.AutoArrayHashMapUnmanaged(usize, *Module.DebugInfo) else void,
2236lookup_cache: if (target_supported) Module.LookupCache else void,
2337
2438pub const Error = error{
......@@ -43,12 +57,16 @@ pub const supports_unwinding: bool = target_supported and Module.supports_unwind
4357pub const UnwindContext = if (supports_unwinding) Module.UnwindContext;
4458
4559pub const init: SelfInfo = .{
60 .modules_mutex = .{},
4661 .modules = .empty,
4762 .lookup_cache = if (Module.LookupCache != void) .init,
4863};
4964
5065pub fn deinit(self: *SelfInfo, gpa: Allocator) void {
51 for (self.modules.values()) |*di| di.deinit(gpa);
66 for (self.modules.values()) |di| {
67 di.deinit(gpa);
68 gpa.destroy(di);
69 }
5270 self.modules.deinit(gpa);
5371 if (Module.LookupCache != void) self.lookup_cache.deinit(gpa);
5472}
......@@ -56,21 +74,35 @@ pub fn deinit(self: *SelfInfo, gpa: Allocator) void {
5674pub fn unwindFrame(self: *SelfInfo, gpa: Allocator, context: *UnwindContext) Error!usize {
5775 comptime assert(supports_unwinding);
5876 const module: Module = try .lookup(&self.lookup_cache, gpa, context.pc);
59 const gop = try self.modules.getOrPut(gpa, module.key());
60 self.modules.lockPointers();
61 defer self.modules.unlockPointers();
62 if (!gop.found_existing) gop.value_ptr.* = .init;
63 return module.unwindFrame(gpa, gop.value_ptr, context);
77 const di: *Module.DebugInfo = di: {
78 self.modules_mutex.lock();
79 defer self.modules_mutex.unlock();
80 const gop = try self.modules.getOrPut(gpa, module.key());
81 if (gop.found_existing) break :di gop.value_ptr.*;
82 errdefer _ = self.modules.pop().?;
83 const di = try gpa.create(Module.DebugInfo);
84 di.* = .init;
85 gop.value_ptr.* = di;
86 break :di di;
87 };
88 return module.unwindFrame(gpa, di, context);
6489}
6590
6691pub fn getSymbolAtAddress(self: *SelfInfo, gpa: Allocator, address: usize) Error!std.debug.Symbol {
6792 comptime assert(target_supported);
6893 const module: Module = try .lookup(&self.lookup_cache, gpa, address);
69 const gop = try self.modules.getOrPut(gpa, module.key());
70 self.modules.lockPointers();
71 defer self.modules.unlockPointers();
72 if (!gop.found_existing) gop.value_ptr.* = .init;
73 return module.getSymbolAtAddress(gpa, gop.value_ptr, address);
94 const di: *Module.DebugInfo = di: {
95 self.modules_mutex.lock();
96 defer self.modules_mutex.unlock();
97 const gop = try self.modules.getOrPut(gpa, module.key());
98 if (gop.found_existing) break :di gop.value_ptr.*;
99 errdefer _ = self.modules.pop().?;
100 const di = try gpa.create(Module.DebugInfo);
101 di.* = .init;
102 gop.value_ptr.* = di;
103 break :di di;
104 };
105 return module.getSymbolAtAddress(gpa, di, address);
74106}
75107
76108pub fn getModuleNameForAddress(self: *SelfInfo, gpa: Allocator, address: usize) Error![]const u8 {
......@@ -88,6 +120,9 @@ pub fn getModuleNameForAddress(self: *SelfInfo, gpa: Allocator, address: usize)
88120/// be valid to consider the entire application one module, or on the other hand to consider each
89121/// object file a module.
90122///
123/// Because different threads can collect stack traces concurrently, the implementation must be able
124/// to tolerate concurrent calls to any method it implements.
125///
91126/// This type must must expose the following declarations:
92127///
93128/// ```
lib/std/debug/SelfInfo/DarwinModule.zig+22-2
......@@ -252,6 +252,15 @@ fn loadMachO(module: *const DarwinModule, gpa: Allocator) !DebugInfo.LoadedMachO
252252 };
253253}
254254pub fn getSymbolAtAddress(module: *const DarwinModule, gpa: Allocator, di: *DebugInfo, address: usize) Error!std.debug.Symbol {
255 // We need the lock for a few things:
256 // * loading the Mach-O module
257 // * loading the referenced object file
258 // * scanning the DWARF of that object file
259 // * building the line number table of that object file
260 // That's enough that it doesn't really seem worth scoping the lock more tightly than the whole function..
261 di.mutex.lock();
262 defer di.mutex.unlock();
263
255264 if (di.loaded_macho == null) di.loaded_macho = module.loadMachO(gpa) catch |err| switch (err) {
256265 error.InvalidDebugInfo, error.MissingDebugInfo, error.OutOfMemory, error.Unexpected => |e| return e,
257266 else => return error.ReadFailed,
......@@ -341,8 +350,12 @@ pub fn unwindFrame(module: *const DarwinModule, gpa: Allocator, di: *DebugInfo,
341350 };
342351}
343352fn unwindFrameInner(module: *const DarwinModule, gpa: Allocator, di: *DebugInfo, context: *UnwindContext) !usize {
344 if (di.unwind == null) di.unwind = module.loadUnwindInfo();
345 const unwind = &di.unwind.?;
353 const unwind: *const DebugInfo.Unwind = u: {
354 di.mutex.lock();
355 defer di.mutex.unlock();
356 if (di.unwind == null) di.unwind = module.loadUnwindInfo();
357 break :u &di.unwind.?;
358 };
346359
347360 const unwind_info = unwind.unwind_info orelse return error.MissingDebugInfo;
348361 if (unwind_info.len < @sizeOf(macho.unwind_info_section_header)) return error.InvalidDebugInfo;
......@@ -649,10 +662,17 @@ fn unwindFrameInner(module: *const DarwinModule, gpa: Allocator, di: *DebugInfo,
649662 return ret_addr;
650663}
651664pub const DebugInfo = struct {
665 /// Held while checking and/or populating `unwind` or `loaded_macho`.
666 /// Once a field is populated and the pointer `&di.loaded_macho.?` or `&di.unwind.?` has been
667 /// gotten, the lock is released; i.e. it is not held while *using* the loaded info.
668 mutex: std.Thread.Mutex,
669
652670 unwind: ?Unwind,
653671 loaded_macho: ?LoadedMachO,
654672
655673 pub const init: DebugInfo = .{
674 .mutex = .{},
675
656676 .unwind = null,
657677 .loaded_macho = null,
658678 };
lib/std/debug/SelfInfo/ElfModule.zig+42-20
......@@ -7,16 +7,26 @@ gnu_eh_frame: ?[]const u8,
77pub const LookupCache = void;
88
99pub const DebugInfo = struct {
10 /// Held while checking and/or populating `loaded_elf`/`scanned_dwarf`/`unwind`.
11 /// Once data is populated and a pointer to the field has been gotten, the lock
12 /// is released; i.e. it is not held while *using* the loaded debug info.
13 mutex: std.Thread.Mutex,
14
1015 loaded_elf: ?ElfFile,
1116 scanned_dwarf: bool,
1217 unwind: [2]?Dwarf.Unwind,
1318 pub const init: DebugInfo = .{
19 .mutex = .{},
1420 .loaded_elf = null,
1521 .scanned_dwarf = false,
1622 .unwind = @splat(null),
1723 };
1824 pub fn deinit(di: *DebugInfo, gpa: Allocator) void {
1925 if (di.loaded_elf) |*loaded_elf| loaded_elf.deinit(gpa);
26 for (di.unwind) |*opt_unwind| {
27 const unwind = &(opt_unwind orelse continue);
28 unwind.deinit(gpa);
29 }
2030 }
2131};
2232
......@@ -145,34 +155,41 @@ fn loadElf(module: *const ElfModule, gpa: Allocator, di: *DebugInfo) Error!void
145155 }
146156}
147157pub fn getSymbolAtAddress(module: *const ElfModule, gpa: Allocator, di: *DebugInfo, address: usize) Error!std.debug.Symbol {
148 if (di.loaded_elf == null) try module.loadElf(gpa, di);
149158 const vaddr = address - module.load_offset;
150 if (di.loaded_elf.?.dwarf) |*dwarf| {
151 if (!di.scanned_dwarf) {
152 dwarf.open(gpa, native_endian) catch |err| switch (err) {
159 {
160 di.mutex.lock();
161 defer di.mutex.unlock();
162 if (di.loaded_elf == null) try module.loadElf(gpa, di);
163 const loaded_elf = &di.loaded_elf.?;
164 // We need the lock if using DWARF, as we might scan the DWARF or build a line number table.
165 if (loaded_elf.dwarf) |*dwarf| {
166 if (!di.scanned_dwarf) {
167 dwarf.open(gpa, native_endian) catch |err| switch (err) {
168 error.InvalidDebugInfo,
169 error.MissingDebugInfo,
170 error.OutOfMemory,
171 => |e| return e,
172 error.EndOfStream,
173 error.Overflow,
174 error.ReadFailed,
175 error.StreamTooLong,
176 => return error.InvalidDebugInfo,
177 };
178 di.scanned_dwarf = true;
179 }
180 return dwarf.getSymbol(gpa, native_endian, vaddr) catch |err| switch (err) {
153181 error.InvalidDebugInfo,
154182 error.MissingDebugInfo,
155183 error.OutOfMemory,
156184 => |e| return e,
185 error.ReadFailed,
157186 error.EndOfStream,
158187 error.Overflow,
159 error.ReadFailed,
160188 error.StreamTooLong,
161189 => return error.InvalidDebugInfo,
162190 };
163 di.scanned_dwarf = true;
164191 }
165 return dwarf.getSymbol(gpa, native_endian, vaddr) catch |err| switch (err) {
166 error.InvalidDebugInfo,
167 error.MissingDebugInfo,
168 error.OutOfMemory,
169 => |e| return e,
170 error.ReadFailed,
171 error.EndOfStream,
172 error.Overflow,
173 error.StreamTooLong,
174 => return error.InvalidDebugInfo,
175 };
192 // Otherwise, we're just going to scan the symtab, which we don't need the lock for; fall out of this block.
176193 }
177194 // When there's no DWARF available, fall back to searching the symtab.
178195 return di.loaded_elf.?.searchSymtab(gpa, vaddr) catch |err| switch (err) {
......@@ -231,9 +248,14 @@ fn loadUnwindInfo(module: *const ElfModule, gpa: Allocator, di: *DebugInfo) Erro
231248 }
232249}
233250pub fn unwindFrame(module: *const ElfModule, gpa: Allocator, di: *DebugInfo, context: *UnwindContext) Error!usize {
234 if (di.unwind[0] == null) try module.loadUnwindInfo(gpa, di);
235 std.debug.assert(di.unwind[0] != null);
236 for (&di.unwind) |*opt_unwind| {
251 const unwinds: *const [2]?Dwarf.Unwind = u: {
252 di.mutex.lock();
253 defer di.mutex.unlock();
254 if (di.unwind[0] == null) try module.loadUnwindInfo(gpa, di);
255 std.debug.assert(di.unwind[0] != null);
256 break :u &di.unwind;
257 };
258 for (unwinds) |*opt_unwind| {
237259 const unwind = &(opt_unwind.* orelse break);
238260 return context.unwindFrame(gpa, unwind, module.load_offset, null) catch |err| switch (err) {
239261 error.MissingDebugInfo => continue, // try the next one
lib/std/debug/SelfInfo/WindowsModule.zig+19-4
......@@ -9,14 +9,14 @@ pub fn lookup(cache: *LookupCache, gpa: Allocator, address: usize) std.debug.Sel
99 if (lookupInCache(cache, address)) |m| return m;
1010 {
1111 // Check a new module hasn't been loaded
12 cache.rwlock.lock();
13 defer cache.rwlock.unlock();
1214 cache.modules.clearRetainingCapacity();
13
1415 const handle = windows.kernel32.CreateToolhelp32Snapshot(windows.TH32CS_SNAPMODULE | windows.TH32CS_SNAPMODULE32, 0);
1516 if (handle == windows.INVALID_HANDLE_VALUE) {
1617 return windows.unexpectedError(windows.GetLastError());
1718 }
1819 defer windows.CloseHandle(handle);
19
2020 var entry: windows.MODULEENTRY32 = undefined;
2121 entry.dwSize = @sizeOf(windows.MODULEENTRY32);
2222 if (windows.kernel32.Module32First(handle, &entry) != 0) {
......@@ -30,12 +30,18 @@ pub fn lookup(cache: *LookupCache, gpa: Allocator, address: usize) std.debug.Sel
3030 return error.MissingDebugInfo;
3131}
3232pub fn getSymbolAtAddress(module: *const WindowsModule, gpa: Allocator, di: *DebugInfo, address: usize) std.debug.SelfInfo.Error!std.debug.Symbol {
33 // The `Pdb` API doesn't really allow us *any* thread-safe access, and the `Dwarf` API isn't
34 // great for it either; just lock the whole thing.
35 di.mutex.lock();
36 defer di.mutex.unlock();
37
3338 if (!di.loaded) module.loadDebugInfo(gpa, di) catch |err| switch (err) {
3439 error.OutOfMemory, error.InvalidDebugInfo, error.MissingDebugInfo, error.Unexpected => |e| return e,
3540 error.FileNotFound => return error.MissingDebugInfo,
3641 error.UnknownPDBVersion => return error.UnsupportedDebugInfo,
3742 else => return error.ReadFailed,
3843 };
44
3945 // Translate the runtime address into a virtual address into the module
4046 const vaddr = address - module.base_address;
4147
......@@ -50,7 +56,9 @@ pub fn getSymbolAtAddress(module: *const WindowsModule, gpa: Allocator, di: *Deb
5056
5157 return error.MissingDebugInfo;
5258}
53fn lookupInCache(cache: *const LookupCache, address: usize) ?WindowsModule {
59fn lookupInCache(cache: *LookupCache, address: usize) ?WindowsModule {
60 cache.rwlock.lockShared();
61 defer cache.rwlock.unlockShared();
5462 for (cache.modules.items) |*entry| {
5563 const base_address = @intFromPtr(entry.modBaseAddr);
5664 if (address >= base_address and address < base_address + entry.modBaseSize) {
......@@ -182,13 +190,19 @@ fn loadDebugInfo(module: *const WindowsModule, gpa: Allocator, di: *DebugInfo) !
182190 di.loaded = true;
183191}
184192pub const LookupCache = struct {
193 rwlock: std.Thread.RwLock,
185194 modules: std.ArrayListUnmanaged(windows.MODULEENTRY32),
186 pub const init: LookupCache = .{ .modules = .empty };
195 pub const init: LookupCache = .{
196 .rwlock = .{},
197 .modules = .empty,
198 };
187199 pub fn deinit(lc: *LookupCache, gpa: Allocator) void {
188200 lc.modules.deinit(gpa);
189201 }
190202};
191203pub const DebugInfo = struct {
204 mutex: std.Thread.Mutex,
205
192206 loaded: bool,
193207
194208 coff_image_base: u64,
......@@ -205,6 +219,7 @@ pub const DebugInfo = struct {
205219 coff_section_headers: []coff.SectionHeader,
206220
207221 pub const init: DebugInfo = .{
222 .mutex = .{},
208223 .loaded = false,
209224 .coff_image_base = undefined,
210225 .mapped_file = null,