Docs cleanup

Author: g41797

docs/generate.sh

@@ -15,7 +15,7 @@ rm -rf build
 mkdir build
 
 # Generate intermediate binary format for our project
-odin doc ../examples/ -all-packages -doc-format -out:odin-mbox.odin-doc
+odin doc ../mbox ../mpsc ../pool ../wakeup ../nbio_mbox ../examples -all-packages -doc-format -out:odin-mbox.odin-doc
 
 # Create a temporary config with absolute paths
 sed "s|PROJECT_ROOT|$ROOT_DIR|g" odin-doc.json > build/odin-doc.json

examples/negotiation.odin

@@ -35,7 +35,7 @@ _Worker :: struct {
 // - Loop receives the request. Reuses it as the reply (increments data, sends back).
 // - Worker receives the reply and frees it.
 // - One allocation per round-trip. Worker owns the memory start to finish.
-negotiation_example :: proc() -> bool {
+negotiation_example :: proc(kind: nbio_mbox.Nbio_Wakeuper_Kind = .UDP) -> bool {
 	err := nbio.acquire_thread_event_loop()
 	if err != nil {
 		return false
@@ -45,7 +45,7 @@ negotiation_example :: proc() -> bool {
 	loop := nbio.current_thread_event_loop()
 
 	// loop_mb receives requests from the worker.
-	loop_mb, init_err := nbio_mbox.init_nbio_mbox(Msg, loop)
+	loop_mb, init_err := nbio_mbox.init_nbio_mbox(Msg, loop, kind)
 	if init_err != .None {
 		return false
 	}

mpsc/MPSC-Queue-Implementation-Comparison.md

@@ -9,8 +9,8 @@ when a message is sent from another thread.
 
 | Kind | How it works | Notes |
 |------|-------------|-------|
-| `.UDP` (default) | Sender writes 1 byte to a loopback UDP socket; nbio wakes on receipt | Stable on Linux, macOS, Windows |
-| `.Timeout` | Zero-duration nbio timeout; CAS flag prevents queue overflow | 128-slot cross-thread queue limit |
+| `.UDP` (default) | Sender writes 1 byte to a loopback UDP socket; nbio wakes on receipt | No queue limit |
+| `.Timeout` | Zero-duration nbio timeout; CAS flag prevents queue overflow | Works on all platforms |
 
 ## Requirements
 

nbio_mbox/README.md

@@ -6,11 +6,11 @@ when a message is sent from another thread.
 
 Two wake mechanisms are available via Nbio_Wakeuper_Kind:
 
-  .UDP (default) — A loopback UDP socket. The sender writes 1 byte; nbio wakes on
-      receipt. Stable on Linux, macOS, and Windows. No queue capacity limit.
+  .UDP (default) — A loopback UDP socket. The sender writes 1 byte; nbio wakes on receipt.
+      No queue capacity limit.
 
-  .Timeout — A zero-duration nbio timeout. Limited by the 128-slot cross-thread
-      queue; throttled with a CAS flag to prevent overflow under high-frequency sends.
+  .Timeout — A zero-duration nbio timeout. Works on all platforms.
+      Throttled with a CAS flag to prevent 128-slot cross-thread queue overflow.
 
 Thread model:
 

nbio_mbox/doc.odin

@@ -163,6 +163,10 @@ _udp_recv_cb :: proc(op: ^nbio.Operation, state: ^_UDP_State) {
 
 // _udp_close cancels the pending recv, closes both sockets, and frees state.
 // Must be called from the event-loop thread — nbio.remove panics cross-thread.
+//
+// nbio.tick(0) after remove drains any pending IOCP cancellation completion on
+// Windows before the sockets and state are freed. On Linux/macOS remove is truly
+// silent (callback never fires), so tick(0) is a no-op there.
 @(private)
 _udp_close :: proc(ctx: rawptr) {
 	if ctx == nil {
@@ -174,6 +178,7 @@ _udp_close :: proc(ctx: rawptr) {
 		nbio.remove(state.recv_op)
 		state.recv_op = nil
 	}
+	nbio.tick(0) // drain IOCP cancellation completion before freeing buffers
 	net.close(state.recv_sock)
 	net.close(state.send_sock)
 	free(state, state.allocator)
@@ -242,6 +247,8 @@ _init_udp_wakeup :: proc(
 // init_nbio_mbox allocates a try_mbox.Mbox wired to the nbio event loop.
 //
 // kind selects the wake mechanism (default: .UDP).
+// Use .Timeout if UDP sockets are unavailable or on Windows where IOCP
+// completion packets may interact unexpectedly with UDP at high speed.
 //
 // Returns (nil, .Invalid_Loop) if loop is nil.
 // Returns (nil, .Keepalive_Failed) if the Timeout wakeuper allocation fails.

nbio_mbox/nbio_mbox.odin

@@ -1,5 +1,5 @@
-// SPDX-FileCopyrightText: Copyright (c) 2026 g41797
-// SPDX-License-Identifier: MIT
+//+test
+
 
 package pool_tests
 
@@ -94,15 +94,21 @@ test_pool_get_timeout_put_wakes :: proc(t: ^testing.T) {
 		return
 	}
 
-	ctx := _Put_Wakes_Ctx{pool = &p, msg = msg}
+	ctx := _Put_Wakes_Ctx {
+		pool = &p,
+		msg  = msg,
+	}
 
-	th := thread.create_and_start_with_data(&ctx, proc(data: rawptr) {
+	th := thread.create_and_start_with_data(
+	&ctx,
+	proc(data: rawptr) {
 		c := (^_Put_Wakes_Ctx)(data)
 		// Signal the waiter that we're ready, then put the message back.
 		sync.sema_post(&c.ready)
 		time.sleep(5 * time.Millisecond)
 		pool_pkg.put(c.pool, c.msg)
-	})
+	},
+	)
 
 	// Wait until the thread is running, then block on get with a long timeout.
 	sync.sema_wait(&ctx.ready)
@@ -122,15 +128,20 @@ test_pool_get_timeout_destroy_wakes :: proc(t: ^testing.T) {
 	p: pool_pkg.Pool(Test_Msg)
 	pool_pkg.init(&p, reset = nil)
 
-	ctx := _Destroy_Wakes_Ctx{pool = &p}
+	ctx := _Destroy_Wakes_Ctx {
+		pool = &p,
+	}
 
-	th := thread.create_and_start_with_data(&ctx, proc(data: rawptr) {
+	th := thread.create_and_start_with_data(
+	&ctx,
+	proc(data: rawptr) {
 		c := (^_Destroy_Wakes_Ctx)(data)
 		// Signal the waiter that we're running, then destroy the pool.
 		sync.sema_post(&c.ready)
 		time.sleep(5 * time.Millisecond)
 		pool_pkg.destroy(c.pool)
-	})
+	},
+	)
 
 	// Wait until the thread is running, then block on get with infinite timeout.
 	sync.sema_wait(&ctx.ready)
@@ -158,7 +169,12 @@ test_pool_many_waiters_partial_fill :: proc(t: ^testing.T) {
 	threads: [N]^thread.Thread
 
 	for i in 0 ..< N {
-		ctxs[i] = _N_Pool_Ctx{pool = &p, idx = i, started = &started, done = &done}
+		ctxs[i] = _N_Pool_Ctx {
+			pool    = &p,
+			idx     = i,
+			started = &started,
+			done    = &done,
+		}
 		threads[i] = thread.create_and_start_with_data(&ctxs[i], proc(data: rawptr) {
 			c := (^_N_Pool_Ctx)(data)
 			sync.sema_post(c.started)
@@ -222,7 +238,12 @@ test_pool_destroy_wakes_all :: proc(t: ^testing.T) {
 	threads: [N]^thread.Thread
 
 	for i in 0 ..< N {
-		ctxs[i] = _N_Pool_Ctx{pool = &p, idx = i, started = &started, done = &done}
+		ctxs[i] = _N_Pool_Ctx {
+			pool    = &p,
+			idx     = i,
+			started = &started,
+			done    = &done,
+		}
 		threads[i] = thread.create_and_start_with_data(&ctxs[i], proc(data: rawptr) {
 			c := (^_N_Pool_Ctx)(data)
 			sync.sema_post(c.started)
@@ -274,7 +295,11 @@ test_pool_stress_high_volume :: proc(t: ^testing.T) {
 	threads: [N]^thread.Thread
 
 	for i in 0 ..< N {
-		ctxs[i] = _Stress_Ctx{pool = &p, start = &start, done = &done}
+		ctxs[i] = _Stress_Ctx {
+			pool  = &p,
+			start = &start,
+			done  = &done,
+		}
 		threads[i] = thread.create_and_start_with_data(&ctxs[i], proc(data: rawptr) {
 			c := (^_Stress_Ctx)(data)
 			sync.sema_wait(c.start)
@@ -316,7 +341,11 @@ test_pool_max_limit_racing :: proc(t: ^testing.T) {
 	threads: [N]^thread.Thread
 
 	for i in 0 ..< N {
-		ctxs[i] = _Max_Race_Ctx{pool = &p, start = &start, done = &done}
+		ctxs[i] = _Max_Race_Ctx {
+			pool  = &p,
+			start = &start,
+			done  = &done,
+		}
 		threads[i] = thread.create_and_start_with_data(&ctxs[i], proc(data: rawptr) {
 			c := (^_Max_Race_Ctx)(data)
 			sync.sema_wait(c.start)
@@ -339,7 +368,11 @@ test_pool_max_limit_racing :: proc(t: ^testing.T) {
 		thread.destroy(threads[i])
 	}
 
-	testing.expect(t, p.curr_msgs <= 3, "curr_msgs should not exceed max_msgs after concurrent puts")
+	testing.expect(
+		t,
+		p.curr_msgs <= 3,
+		"curr_msgs should not exceed max_msgs after concurrent puts",
+	)
 	pool_pkg.destroy(&p)
 }
 
@@ -357,7 +390,11 @@ test_pool_shutdown_race :: proc(t: ^testing.T) {
 	threads: [N]^thread.Thread
 
 	for i in 0 ..< N {
-		ctxs[i] = _Shutdown_Ctx{pool = &p, start = &start, done = &done}
+		ctxs[i] = _Shutdown_Ctx {
+			pool  = &p,
+			start = &start,
+			done  = &done,
+		}
 		threads[i] = thread.create_and_start_with_data(&ctxs[i], proc(data: rawptr) {
 			c := (^_Shutdown_Ctx)(data)
 			sync.sema_wait(c.start)
@@ -402,7 +439,10 @@ test_pool_idempotent_destroy :: proc(t: ^testing.T) {
 	threads: [N]^thread.Thread
 
 	for i in 0 ..< N {
-		ctxs[i] = _Idempotent_Ctx{pool = &p, start = &start}
+		ctxs[i] = _Idempotent_Ctx {
+			pool  = &p,
+			start = &start,
+		}
 		threads[i] = thread.create_and_start_with_data(&ctxs[i], proc(data: rawptr) {
 			c := (^_Idempotent_Ctx)(data)
 			sync.sema_wait(c.start)
@@ -426,8 +466,14 @@ test_pool_idempotent_destroy :: proc(t: ^testing.T) {
 // new/free calls, never falling back to context.allocator.
 @(test)
 test_pool_allocator_integrity :: proc(t: ^testing.T) {
-	data := Counting_Alloc_Data{max = 10, backing = context.allocator}
-	counting := mem.Allocator{procedure = _counting_alloc, data = &data}
+	data := Counting_Alloc_Data {
+		max     = 10,
+		backing = context.allocator,
+	}
+	counting := mem.Allocator {
+		procedure = _counting_alloc,
+		data      = &data,
+	}
 
 	p: pool_pkg.Pool(Test_Msg)
 	pool_pkg.init(&p, initial_msgs = 3, reset = nil, allocator = counting)