Commit 9e6318a4ea042e3fab7a1b2347600cde3d804e1a | zig

author	Matthew Lugg <mlugg@mlugg.co.uk> 2024-08-17 12:05:12+01:00
committer	Jacob Young <jacobly@ziglang.org> 2024-08-17 18:50:10-04:00
log	9e6318a4ea042e3fab7a1b2347600cde3d804e1a
tree	cfcc1d1a770ae4b8de4e381710ac6ec4e4fcd502
parent	7f2466e65fe0b7411792ce3d3f186893ed22379d

compiler: add some doc comments

2 files changed, 24 insertions(+), 2 deletions(-)

src
- InternPool.zig
- Zcu
  - PerThread.zig

src/InternPool.zig+21-2

 @@ -62,10 +62,18 @@ const want_multi_threaded = true;
 /// Whether a single-threaded intern pool impl is in use.
 pub const single_threaded = builtin.single_threaded or !want_multi_threaded;
+/// A `TrackedInst.Index` provides a single, unchanging reference to a ZIR instruction across a whole
+/// compilation. From this index, you can acquire a `TrackedInst`, which containss a reference to both
+/// the file which the instruction lives in, and the instruction index itself, which is updated on
+/// incremental updates by `Zcu.updateZirRefs`.
 pub const TrackedInst = extern struct {
     file: FileIndex,
     inst: Zir.Inst.Index,
+    /// It is possible on an incremental update that we "lose" a ZIR instruction: some tracked `%x` in
+    /// the old ZIR failed to map to any `%y` in the new ZIR. For this reason, we actually store values
+    /// of type `MaybeLost`, which uses `ZirIndex.lost` to represent this case. `Index.resolve` etc
+    /// return `null` when the `TrackedInst` being resolved has been lost.
     pub const MaybeLost = extern struct {
         file: FileIndex,
         inst: ZirIndex,
 @@ -244,14 +252,17 @@ pub fn trackZir(
     return index;
 }
+/// At the start of an incremental update, we update every entry in `tracked_insts` to include
+/// the new ZIR index. Once this is done, we must update the hashmap metadata so that lookups
+/// return correct entries where they already exist.
 pub fn rehashTrackedInsts(
     ip: *InternPool,
     gpa: Allocator,
-    /// TODO: maybe don't take this? it doesn't actually matter, only one thread is running at this point
     tid: Zcu.PerThread.Id,
 ) Allocator.Error!void {
+    assert(tid == .main); // we shouldn't have any other threads active right now
     // TODO: this function doesn't handle OOM well. What should it do?
-    //       Indeed, what should anyone do when they run out of memory?
     // We don't lock anything, as this function assumes that no other thread is
     // accessing `tracked_insts`. This is necessary because we're going to be
 @@ -795,6 +806,14 @@ const Local = struct {
     /// This state is fully local to the owning thread and does not require any
     /// atomic access.
     mutate: struct {
+        /// When we need to allocate any long-lived buffer for mutating the `InternPool`, it is
+        /// allocated into this `arena` (for the `Id` of the thread performing the mutation). An
+        /// arena is used to avoid contention on the GPA, and to ensure that any code which retains
+        /// references to old state remains valid. For instance, when reallocing hashmap metadata,
+        /// a racing lookup on another thread may still retain a handle to the old metadata pointer,
+        /// so it must remain valid.
+        /// This arena's lifetime is tied to that of `Compilation`, although it can be cleared on
+        /// garbage collection (currently vaporware).
         arena: std.heap.ArenaAllocator.State,
         items: ListMutate,

src/Zcu/PerThread.zig+3

...	@@ -1,3 +1,6 @@	...	@@ -1,3 +1,6 @@
		1	//! This type provides a wrapper around a `*Zcu` for uses which require a thread `Id`.
		2	//! Any operation which mutates `InternPool` state lives here rather than on `Zcu`.
		3
1	zcu: *Zcu,	4	zcu: *Zcu,
2		5
3	/// Dense, per-thread unique index.	6	/// Dense, per-thread unique index.