Initial pool implementation, updated examples and docs

Author: g41797

.gitignore

@@ -23,6 +23,7 @@ ols.json
 # Local Session Data
 mailbox_init.md
 design/STATUS.md
+design/heap-pool-plan.md
 
 # Documentation tools
 /tools/tmp_pkg_repo

README.md

@@ -43,8 +43,8 @@ Odin has [channels](https://pkg.odin-lang.org/core/sync/chan/). Use them if they
 
 **mbox** helps when you need:
 
-- **Zero allocations**: No copying. It links your struct directly.
-- **Recycling**: Use the same message over and over
+- **Zero copies**: No data copying. It links your struct directly.
+- **Recycling**: Use a pool to reuse messages with zero allocations per send.
 - **nbio**: Wakes the `nbio` loop when a message arrives.
 - **Timeouts**: Stop waiting after a certain time.
 - **Interrupts**: Wake a thread without sending a message. One-time signal.
@@ -94,12 +94,13 @@ Both are thread-safe. Both have zero allocations for sending or receiving.
 
 | Example | Description |
 | :--- | :--- |
-| [Endless Game](examples/endless_game.odin) | 4 threads pass a single message in a circle. Millions of turns with zero overhead. |
+| [Endless Game](examples/endless_game.odin) | 4 threads pass a single heap-allocated message in a circle. |
 | [Negotiation](examples/negotiation.odin) | Request and reply between a worker thread and an `nbio` loop. |
 | [Life and Death](examples/lifecycle.odin) | Full flow: from allocation to cleanup. |
-| [Stress Test](examples/stress.odin) | Many threads sending thousands of messages to one receiver. |
+| [Stress Test](examples/stress.odin) | Many producers, one consumer, pool-based message recycling. |
 | [Interrupt](examples/interrupt.odin) | How to wake a waiting thread without sending a message. |
 | [Close](examples/close.odin) | Stop the game and get back all unprocessed messages. |
+| [Master](examples/master.odin) | Pool + mailbox owned by one struct. Coordinated shutdown. |
 
 ---
 
@@ -110,15 +111,21 @@ They are just small tips to show you the game...
 
 ## Quick start
 
+> **Warning**: Never send stack-allocated messages across threads.
+> The stack frame can be freed before the receiving thread reads the message.
+> Always allocate messages on the heap (`new`) or use a pool.
+
 ### Basic Send and Receive
 
 ```odin
 // sender thread:
-msg := My_Msg{data = 42}
-mbox.send(&mb, &msg)
+msg := new(My_Msg)
+msg.data = 42
+mbox.send(&mb, msg)
 
 // receiver thread:
 got, err := mbox.wait_receive(&mb, 100 * time.Millisecond)
+if got != nil { free(got) }
 ```
 
 ### Interrupt a Waiter
@@ -195,11 +202,40 @@ for node := list.pop_front(&remaining); node != nil; node = list.pop_front(&rema
 }
 ```
 
+## Pool
+
+For high-throughput use, recycle messages with the companion `pool` package.
+
+```odin
+import pool_pkg "path/to/odin-mbox/pool"
+
+// Setup:
+p: pool_pkg.Pool(My_Msg)
+pool_pkg.init(&p, initial_msgs = 64, max_msgs = 256)
+
+// Sender: get from pool, fill, send.
+msg := pool_pkg.get(&p)
+msg.data = 42
+mbox.send(&mb, msg)
+
+// Receiver: receive, use, return to pool.
+got, err := mbox.wait_receive(&mb)
+if err == .None { pool_pkg.put(&p, got) }
+
+// Cleanup:
+pool_pkg.destroy(&p)
+```
+
+See [design/mbox_examples.md](design/mbox_examples.md) for the MASTER pattern (pool + mailbox, coordinated shutdown).
+
+---
+
 ## Best Practices
 
 1. **Ownership.** Once you send a message, don't touch it. It belongs to the mailbox until someone receives it.
-2. **Cleanup.** Use `close()` to stop. Undelivered messages are returned to you—it is now safe to free or reuse them.
-3. **Threads.** Always wait for threads to finish (`thread.join`) before you free the mailbox itself.
+2. **Heap.** Always use heap-allocated messages across threads. Never use stack allocation.
+3. **Cleanup.** Use `close()` to stop. Undelivered messages are returned to you—free or return to pool.
+4. **Threads.** Always wait for threads to finish (`thread.join`) before you free the mailbox itself.
 
 
 ---

_notes.txt

@@ -24,3 +24,7 @@ context—Odin’s Most Misunderstood Feature
 
 Odin build doc pages magic
     https://github.com/laytan/odin-tree-sitter
+
+
+Add core:nbio#6124
+    https://github.com/odin-lang/Odin/pull/6124

design/mailbox_design.md

@@ -193,7 +193,20 @@ You only get ownership back when you `receive()` it or get it from `close()`.
 Always wait for all threads to finish (`thread.join`) before you free the mailbox itself.
 The mailbox must stay alive as long as any thread can still access it.
 
-### 4. nbio loop initialization
+### 4. Message lifetime
+Never use stack-allocated messages for inter-thread communication.
+The stack frame can be freed before the receiving thread reads the message.
+
+Three ownership patterns:
+
+1. **Heap**: `new` to allocate, `free` after receive. Simple. Good for low-frequency use.
+2. **Pool**: `pool.get` / `pool.put`. High-throughput recycling. Zero allocations during the run.
+3. **MASTER**: one struct owns both pool and mailbox. One shutdown call handles everything.
+
+"Zero copies" means mbox does not copy message data. It does not mean zero allocations.
+You still allocate message objects. mbox just links them.
+
+### 5. nbio loop initialization
 On some platforms (like macOS/kqueue), `nbio.wake_up` requires that the event loop has been ticked at least once to register the internal wake-up event in the kernel. 
 
 Before starting any threads that might call `send_to_loop` or `close_loop`, call `nbio.tick(0)` on the loop thread. This ensures the loop is fully initialized and ready to receive wake-up signals from other threads.

design/mbox_examples.md

@@ -6,6 +6,8 @@ mbox is intrusive. The message struct is the node. No extra allocation per messa
 
 ## 1. Basic send and receive
 
+Allocate messages on the heap. Never pass stack-allocated messages across threads.
+
 ```odin
 import mbox "path/to/odin-mbox"
 import list "core:container/intrusive/list"
@@ -15,18 +17,22 @@ Msg :: struct {
     data: int,
 }
 
-// Sender:
-msg := Msg{data = 42}
-ok := mbox.send(&mb, &msg)
+// Sender thread:
+msg := new(Msg)
+msg.data = 42
+ok := mbox.send(&mb, msg)
 
 // Receiver (non-blocking poll):
 got, err := mbox.wait_receive(&mb, 0)  // err == .Timeout means no message
+if got != nil { free(got) }
 
 // Receiver (blocking, infinite wait):
 got, err := mbox.wait_receive(&mb)
+if got != nil { free(got) }
 
 // Receiver (blocking, with timeout):
 got, err := mbox.wait_receive(&mb, 100 * time.Millisecond)
+if got != nil { free(got) }
 ```
 
 ---
@@ -162,23 +168,32 @@ See `examples/negotiation.odin` for a working version of this pattern.
 
 ## 6. High-throughput stress pattern
 
-Many producers, one consumer.
+Many producers, one consumer. Use a pool for zero-allocation recycling.
 
 ```odin
+import pool_pkg "path/to/odin-mbox/pool"
+
+// Setup:
+shared_pool: pool_pkg.Pool(Msg)
+pool_pkg.init(&shared_pool, initial_msgs = N, max_msgs = N)
+
 // Consumer thread:
 for {
     msg, err := mbox.wait_receive(&mb)
     if err == .Closed { break }
-    // process msg
+    pool_pkg.put(&shared_pool, msg)  // return to pool
 }
 
 // Each producer thread:
-for i in 0 ..< N {
-    mbox.send(&mb, &msgs[i])
+for _ in 0 ..< N / P {
+    msg := pool_pkg.get(&shared_pool)
+    if msg != nil {
+        mbox.send(&mb, msg)
+    }
 }
 
-// After all producers finish (capture remaining if drain is needed — see Pattern 8):
-_, _ = mbox.close(&mb)
+// After done:
+pool_pkg.destroy(&shared_pool)
 ```
 
 See `examples/stress.odin` for a working version of this pattern.
@@ -254,3 +269,77 @@ This pattern is perfect for:
 - Games where one "entity" is manipulated by many systems.
 
 See `examples/endless_game.odin` for the full implementation.
+
+---
+
+## 10. Pool usage (init / get / put / destroy)
+
+Use a pool when you send many messages and want to avoid repeated heap allocations.
+
+```odin
+import pool_pkg "path/to/odin-mbox/pool"
+
+// Setup (once, before any threads start):
+p: pool_pkg.Pool(Msg)
+pool_pkg.init(&p, initial_msgs = 64, max_msgs = 256)
+
+// Sender thread: take from pool, fill data, send.
+msg := pool_pkg.get(&p)
+if msg != nil {
+    msg.data = 42
+    mbox.send(&mb, msg)
+}
+
+// Receiver thread: receive, use, return to pool.
+got, err := mbox.wait_receive(&mb)
+if err == .None && got != nil {
+    // use got.data
+    pool_pkg.put(&p, got)
+}
+
+// Cleanup (after all threads are done):
+pool_pkg.destroy(&p)
+```
+
+Rules:
+- A message is either in the pool OR in a mailbox. Never both.
+- Call destroy only after all threads have stopped using the pool.
+- put() on a full pool frees the message instead of returning it.
+
+---
+
+## 11. MASTER pattern (pool + mailbox, coordinated shutdown)
+
+One struct owns the pool and the mailbox. One shutdown call handles everything.
+
+Key rule: drain the mailbox BEFORE destroying the pool.
+If you destroy the pool first, the messages still in the mailbox become dangling pointers.
+
+```odin
+import pool_pkg "path/to/odin-mbox/pool"
+
+Master :: struct {
+    pool:  pool_pkg.Pool(Msg),
+    inbox: mbox.Mailbox(Msg),
+}
+
+master_init :: proc(m: ^Master) -> bool {
+    return pool_pkg.init(&m.pool, initial_msgs = 8, max_msgs = 64)
+}
+
+master_shutdown :: proc(m: ^Master) {
+    // 1. Close inbox. Get back any undelivered messages.
+    remaining, _ := mbox.close(&m.inbox)
+
+    // 2. Return them to pool — not free, pool owns them.
+    for node := list.pop_front(&remaining); node != nil; node = list.pop_front(&remaining) {
+        msg := container_of(node, Msg, "node")
+        pool_pkg.put(&m.pool, msg)
+    }
+
+    // 3. Now safe to destroy pool.
+    pool_pkg.destroy(&m.pool)
+}
+```
+
+See `examples/master.odin` for a working version of this pattern.

doc.odin

@@ -2,9 +2,9 @@
 Package mbox is an inter-thread communication library for Odin.
 
 Core concepts:
-- Zero allocations: Messages are linked, not copied.
+- Zero copies: Messages are linked, not copied.
 - Intrusive: Your message struct must have a field named "node" of type "list.Node".
-- Thread-safe: Designed for high-concurrency flows.
+- Thread-safe: Safe to use from multiple threads.
 
 Mailbox types:
 - Mailbox($T): For worker threads. Blocks until a message arrives.

docs/README.md

@@ -26,8 +26,8 @@ Odin has [channels](https://pkg.odin-lang.org/core/sync/chan/). Use them if they
 
 **mbox** helps when you need:
 
-- **Zero allocations**: No copying. It links your struct directly.
-- **Recycling**: Use the same message over and over.
+- **Zero copies**: No data copying. It links your struct directly.
+- **Recycling**: Use a pool to reuse messages with zero allocations per send.
 - **nbio**: Wakes the `nbio` loop when a message arrives.
 - **Timeouts**: Stop waiting after a certain time.
 - **Interrupts**: Wake a thread without sending a message. One-time signal.
@@ -74,12 +74,16 @@ Both are thread-safe. Both have zero allocations for sending or receiving.
 
 Check the [examples/](https://github.com/g41797/odin-mbox/tree/main/examples) directory for:
 
-- **Endless Game**: 4 threads pass a single message in a circle.
+- **Endless Game**: 4 threads pass a single heap-allocated message in a circle.
 - **Negotiation**: Request and reply between a worker thread and an `nbio` loop.
 - **Life and Death**: Full flow: from allocation to cleanup.
-- **Stress Test**: Many threads sending thousands of messages to one receiver.
+- **Stress Test**: Many producers, one consumer, pool-based message recycling.
 - **Interrupt**: How to wake a waiting thread without sending a message.
 - **Close**: Stop the game and get back all unprocessed messages.
+- **Master**: Pool + mailbox owned by one struct. Coordinated shutdown.
+
+> **Note**: Always use heap-allocated messages across threads.
+> Never send stack-allocated messages. Use `new`/`free` or the `pool` package.
 
 ## Credits
 

examples/close.odin

@@ -5,22 +5,21 @@ import list "core:container/intrusive/list"
 import "core:thread"
 import "core:time"
 
-// close_example shows how to stop the game and get all messages back.
+// close_example shows how to stop a mailbox and get all undelivered messages back.
 close_example :: proc() -> bool {
 	mb: mbox.Mailbox(Msg)
 
-	// --- Part 1: close() wakes waiters ---
-	// We use an empty mailbox to ensure the waiter blocks.
+	// --- Part 1: close() wakes a blocked waiter ---
 	err_result: mbox.Mailbox_Error
 	t := thread.create_and_start_with_poly_data2(&mb, &err_result, proc(mb: ^mbox.Mailbox(Msg), res: ^mbox.Mailbox_Error) {
 		_, err := mbox.wait_receive(mb)
 		res^ = err
 	})
 
-	// Wait for the thread to be inside wait_receive.
+	// Wait for the thread to enter wait_receive.
 	time.sleep(10 * time.Millisecond)
 
-	// Close the empty mailbox. This must wake the waiter with .Closed.
+	// Close the empty mailbox. Waiter must wake with .Closed.
 	_, was_open := mbox.close(&mb)
 	if !was_open {
 		return false
@@ -34,23 +33,26 @@ close_example :: proc() -> bool {
 	}
 
 	// --- Part 2: close() returns undelivered messages ---
-	// Reset the mailbox for a fresh start.
-	mb = {} 
-	
-	// Create two messages. 
-	a := Msg{data = 1}
-	b := Msg{data = 2}
-	
+	mb = {}
+
+	// Allocate two messages on the heap.
+	a := new(Msg)
+	a.data = 1
+	b := new(Msg)
+	b.data = 2
+
 	// Send them. Mailbox now owns the references.
-	mbox.send(&mb, &a)
-	mbox.send(&mb, &b)
+	mbox.send(&mb, a)
+	mbox.send(&mb, b)
 
 	// Close and get all undelivered messages back.
 	remaining, _ := mbox.close(&mb)
 
-	// Verify we got both references back.
+	// Free each returned message.
 	count := 0
 	for node := list.pop_front(&remaining); node != nil; node = list.pop_front(&remaining) {
+		msg := container_of(node, Msg, "node")
+		free(msg)
 		count += 1
 	}