Added timeout to get from pool.

Author: g41797

README.md

@@ -104,6 +104,9 @@ Both are thread-safe. Both have zero allocations for sending or receiving.
 | [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. |
+| [Pool Wait](examples/pool_wait.odin) | N players share M tokens (M < N); players wait for a recycled token. |
+
+See the [Pool section](#pool) below for message recycling.
 
 ---
 
@@ -214,6 +217,7 @@ To reuse messages, use the `pool` package.
 ```odin
 import pool_pkg "path/to/odin-mbox/pool"
 import "core:mem"
+import "core:time"
 
 // Your struct — both fields required when using pool.
 My_Msg :: struct {
@@ -229,10 +233,14 @@ if ok, _ := pool_pkg.init(&p, initial_msgs = 64, max_msgs = 256, reset = nil); !
 }
 
 // Sender: get from pool, fill, send.
+// .Always (default): allocates new if pool empty.
 msg, _ := pool_pkg.get(&p)
 msg.data = 42
 mbox.send(&mb, msg)
 
+// .Pool_Only + timeout: wait up to 100 ms for a recycled message.
+msg2, status := pool_pkg.get(&p, .Pool_Only, 100 * time.Millisecond)
+
 // Receiver: receive, use, return to pool.
 got, err := mbox.wait_receive(&mb)
 if err == .None { pool_pkg.put(&p, got) }

build_docs.sh

@@ -18,5 +18,7 @@ echo "--- Generating HTML ---"
 "$ROOT_DIR/docs/generate.sh"
 
 # 3. Start local preview
+# Opens http://localhost:8000 — Source File links point to GitHub and require
+# the changes to be pushed before they resolve. Press Ctrl+C to stop.
 echo "--- Starting Preview ---"
 "$ROOT_DIR/tools/preview_docs.sh"

docs/generate.sh

@@ -35,15 +35,29 @@ sed -i 's|href="/|href="./|g' index.html
 sed -i 's|src="/|src="./|g' index.html
 # Fix the library link specifically (it should point to its own subdirectory)
 sed -i 's|href="./odin-mbox"|href="./odin-mbox/"|g' index.html
+# Fix the blank root package link text
+sed -i 's|<a href="./odin-mbox/"></a>|<a href="./odin-mbox/">mbox</a>|g' index.html
 
-# 2. Package index.html (in odin-mbox/ directory)
+# 2. Collection home index.html (in odin-mbox/ directory — depth 1)
 if [ -d "odin-mbox" ]; then
     sed -i 's|href="/|href="../|g' odin-mbox/index.html
     sed -i 's|src="/|src="../|g' odin-mbox/index.html
     # Fix self-links and navigation in the package page
     sed -i 's|href="\.\./odin-mbox"|href="../odin-mbox/"|g' odin-mbox/index.html
+    # Fix the blank root package link text
+    sed -i 's|<a href="../odin-mbox/"></a>|<a href="../odin-mbox/">mbox</a>|g' odin-mbox/index.html
 fi
 
+# 3. Sub-package index.html files (in odin-mbox/*/ directory — depth 2)
+for subdir in odin-mbox/*/; do
+    if [ -f "${subdir}index.html" ]; then
+        sed -i 's|href="/|href="../../|g' "${subdir}index.html"
+        sed -i 's|src="/|src="../../|g' "${subdir}index.html"
+        # Fix the blank root package link text
+        sed -i 's|<a href="../../odin-mbox/"></a>|<a href="../../odin-mbox/">mbox</a>|g' "${subdir}index.html"
+    fi
+done
+
 cd ..
 
 rm odin-mbox.odin-doc

examples/pool_wait.odin

@@ -0,0 +1,70 @@
+package examples
+
+import mbox ".."
+import pool_pkg "../pool"
+import list "core:container/intrusive/list"
+import "core:sync"
+import "core:thread"
+
+N_PLAYERS :: 6
+M_TOKENS  :: 2 // fewer tokens than players — forces waiting
+ROUNDS    :: 5
+
+// pool_wait_example shows N players sharing M tokens (M < N).
+// Players must wait (pool.get .Pool_Only, timeout=-1) until a token is returned.
+pool_wait_example :: proc() -> bool {
+	p: pool_pkg.Pool(Msg)
+	if ok, _ := pool_pkg.init(&p, initial_msgs = M_TOKENS, max_msgs = M_TOKENS, reset = nil); !ok {
+		return false
+	}
+
+	mb: mbox.Mailbox(Msg)
+	done: sync.Sema
+
+	// Collector: receives all messages and returns each token to pool.
+	thread.run_with_poly_data3(
+		&mb, &p, &done,
+		proc(mb: ^mbox.Mailbox(Msg), p: ^pool_pkg.Pool(Msg), done: ^sync.Sema) {
+			total :: N_PLAYERS * ROUNDS
+			count := 0
+			for count < total {
+				msg, err := mbox.wait_receive(mb)
+				if err == .Closed {
+					break
+				}
+				if err == .None {
+					pool_pkg.put(p, msg)
+					count += 1
+				}
+			}
+			sync.sema_post(done)
+		},
+	)
+
+	// N_PLAYERS players: each waits for a token, then sends it.
+	// Only M_TOKENS tokens exist — excess players block in pool.get until one is returned.
+	for _ in 0 ..< N_PLAYERS {
+		thread.run_with_poly_data2(
+			&mb, &p,
+			proc(mb: ^mbox.Mailbox(Msg), p: ^pool_pkg.Pool(Msg)) {
+				for _ in 0 ..< ROUNDS {
+					msg, status := pool_pkg.get(p, .Pool_Only, -1)
+					if status == .Closed {
+						break
+					}
+					mbox.send(mb, msg)
+				}
+			},
+		)
+	}
+
+	sync.sema_wait(&done)
+
+	remaining, _ := mbox.close(&mb)
+	for node := list.pop_front(&remaining); node != nil; node = list.pop_front(&remaining) {
+		msg := container_of(node, Msg, "node")
+		pool_pkg.put(&p, msg)
+	}
+	pool_pkg.destroy(&p)
+	return true
+}

pool/doc.odin

@@ -29,6 +29,11 @@ Your struct must have two fields required by the pool where clause:
 Status returns:
 - init returns (bool, Pool_Status): (true, .Ok) on success; (false, .Out_Of_Memory) on pre-alloc failure.
 - get returns (^T, Pool_Status): .Ok, .Pool_Empty, .Out_Of_Memory, or .Closed.
+  With .Pool_Only strategy and timeout parameter:
+  - timeout==0 (default): return immediately if empty (.Pool_Empty). Non-blocking.
+  - timeout<0: wait forever until put or destroy.
+  - timeout>0: wait up to that duration; returns (nil, .Pool_Empty) on expiry.
+  - Returns (nil, .Closed) if pool is destroyed while waiting.
 - put returns ^T: nil if the message was recycled or freed; the original pointer if it was foreign
   (msg.allocator != pool allocator — caller must free it).
 

pool/pool.odin

@@ -7,8 +7,9 @@ import "base:intrinsics"
 import list "core:container/intrusive/list"
 import "core:mem"
 import "core:sync"
+import "core:time"
 
-// _PoolNode, _PoolMutex, _PoolAllocator, _PoolEvent ensure imports are used — required by -vet for generic code.
+// _PoolNode, _PoolMutex, _PoolAllocator, _PoolEvent, _PoolDuration ensure imports are used — required by -vet for generic code.
 @(private)
 _PoolNode :: list.Node
 @(private)
@@ -17,6 +18,8 @@ _PoolMutex :: sync.Mutex
 _PoolAllocator :: mem.Allocator
 @(private)
 _PoolEvent :: Pool_Event
+@(private)
+_PoolDuration :: time.Duration
 
 // Pool_State is the internal lifecycle of a pool.
 Pool_State :: enum {
@@ -52,6 +55,7 @@ Allocation_Strategy :: enum {
 Pool :: struct($T: typeid) {
 	allocator: mem.Allocator,
 	mutex:     sync.Mutex,
+	cond:      sync.Cond,                    // wakes waiting get(.Pool_Only) calls
 	list:      list.List,
 	curr_msgs: int,
 	max_msgs:  int,                          // 0 = unlimited
@@ -102,13 +106,16 @@ init :: proc(
 }
 
 // get returns a message from the free-list.
-// .Always (default): allocates a new one if the pool is empty.
-// .Pool_Only: returns (nil, .Pool_Empty) if the pool is empty.
-// Returns (nil, .Closed) if the pool state is not Active.
+// .Always (default): allocates a new one if the pool is empty. timeout is ignored.
+// .Pool_Only + timeout==0: returns (nil, .Pool_Empty) immediately if empty (default behavior).
+// .Pool_Only + timeout<0: waits forever until put or destroy.
+// .Pool_Only + timeout>0: waits up to that duration; returns (nil, .Pool_Empty) on expiry.
+// Returns (nil, .Closed) if the pool state is not Active (including destroy while waiting).
 // Sets msg.allocator on every returned message. Calls reset(.Get) only for recycled messages.
 get :: proc(
 	p: ^Pool($T),
 	strategy := Allocation_Strategy.Always,
+	timeout: time.Duration = 0,
 ) -> (^T, Pool_Status) where intrinsics.type_has_field(T, "node"),
 	intrinsics.type_field_type(T, "node") == list.Node,
 	intrinsics.type_has_field(T, "allocator"),
@@ -121,6 +128,36 @@ get :: proc(
 	}
 
 	raw := list.pop_front(&p.list)
+	if raw == nil && strategy == .Pool_Only {
+		if timeout == 0 {
+			sync.mutex_unlock(&p.mutex)
+			return nil, .Pool_Empty
+		}
+		// Wait loop: block until a message is available, pool is closed, or timeout expires.
+		for p.list.head == nil {
+			if p.state != .Active {
+				sync.mutex_unlock(&p.mutex)
+				return nil, .Closed
+			}
+			ok: bool
+			if timeout < 0 {
+				sync.cond_wait(&p.cond, &p.mutex)
+				ok = true
+			} else {
+				ok = sync.cond_wait_with_timeout(&p.cond, &p.mutex, timeout)
+			}
+			if p.state != .Active {
+				sync.mutex_unlock(&p.mutex)
+				return nil, .Closed
+			}
+			if !ok {
+				sync.mutex_unlock(&p.mutex)
+				return nil, .Pool_Empty // timeout expired
+			}
+		}
+		raw = list.pop_front(&p.list)
+	}
+
 	if raw != nil {
 		p.curr_msgs -= 1
 		alloc := p.allocator
@@ -134,12 +171,7 @@ get :: proc(
 		return msg, .Ok
 	}
 
-	if strategy == .Pool_Only {
-		sync.mutex_unlock(&p.mutex)
-		return nil, .Pool_Empty
-	}
-
-	// Fresh allocation — do not call reset.
+	// strategy == .Always and pool was empty: fresh allocation — do not call reset.
 	alloc := p.allocator
 	sync.mutex_unlock(&p.mutex)
 
@@ -187,6 +219,7 @@ put :: proc(
 	msg.node = {}
 	list.push_back(&p.list, &msg.node)
 	p.curr_msgs += 1
+	sync.cond_signal(&p.cond) // wake one waiting get(.Pool_Only)
 	sync.mutex_unlock(&p.mutex)
 	return nil
 }
@@ -220,5 +253,6 @@ destroy :: proc(
 		p.curr_msgs -= 1
 		free(msg, alloc)
 	}
+	sync.cond_broadcast(&p.cond) // wake all waiting get(.Pool_Only) calls
 	sync.mutex_unlock(&p.mutex)
 }

pool_tests/pool_test.odin

@@ -2,7 +2,10 @@ package pool_tests
 
 import list "core:container/intrusive/list"
 import "core:mem"
+import "core:sync"
 import "core:testing"
+import "core:thread"
+import "core:time"
 
 import pool_pkg "../pool"
 
@@ -394,3 +397,105 @@ test_pool_reset_on_put :: proc(t: ^testing.T) {
 		free(recycled, recycled.allocator)
 	}
 }
+
+// ----------------------------------------------------------------------------
+// Timeout tests
+// ----------------------------------------------------------------------------
+
+@(test)
+test_pool_get_timeout_zero :: proc(t: ^testing.T) {
+	p: pool_pkg.Pool(Test_Msg)
+	pool_pkg.init(&p, reset = nil)
+	defer pool_pkg.destroy(&p)
+
+	// Empty pool, .Pool_Only, timeout=0 — must return immediately with .Pool_Empty.
+	msg, status := pool_pkg.get(&p, .Pool_Only, 0)
+	testing.expect(t, msg == nil, "msg should be nil")
+	testing.expect(t, status == .Pool_Empty, "status should be .Pool_Empty")
+}
+
+@(test)
+test_pool_get_timeout_elapsed :: proc(t: ^testing.T) {
+	p: pool_pkg.Pool(Test_Msg)
+	pool_pkg.init(&p, reset = nil)
+	defer pool_pkg.destroy(&p)
+
+	// Empty pool, .Pool_Only, short timeout — nobody puts, should expire with .Pool_Empty.
+	msg, status := pool_pkg.get(&p, .Pool_Only, time.Millisecond)
+	testing.expect(t, msg == nil, "msg should be nil after timeout")
+	testing.expect(t, status == .Pool_Empty, "status should be .Pool_Empty after timeout")
+}
+
+// _put_wakes_ctx holds shared state for test_pool_get_timeout_put_wakes.
+_Put_Wakes_Ctx :: struct {
+	pool:  ^pool_pkg.Pool(Test_Msg),
+	msg:   ^Test_Msg,
+	ready: sync.Sema,
+}
+
+@(test)
+test_pool_get_timeout_put_wakes :: proc(t: ^testing.T) {
+	p: pool_pkg.Pool(Test_Msg)
+	pool_pkg.init(&p, reset = nil)
+	defer pool_pkg.destroy(&p)
+
+	// Pre-allocate a message to put back from the second thread.
+	msg, _ := pool_pkg.get(&p)
+	testing.expect(t, msg != nil, "initial get should return non-nil")
+	if msg == nil {
+		return
+	}
+
+	ctx := _Put_Wakes_Ctx{pool = &p, msg = msg}
+
+	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)
+	got, status := pool_pkg.get(&p, .Pool_Only, time.Second)
+	thread.join(th)
+	thread.destroy(th)
+
+	testing.expect(t, got != nil, "get should return non-nil after put wakes it")
+	testing.expect(t, status == .Ok, "status should be .Ok")
+	if got != nil {
+		free(got, got.allocator)
+	}
+}
+
+// _destroy_wakes_ctx holds shared state for test_pool_get_timeout_destroy_wakes.
+_Destroy_Wakes_Ctx :: struct {
+	pool:  ^pool_pkg.Pool(Test_Msg),
+	ready: sync.Sema,
+}
+
+@(test)
+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}
+
+	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)
+	got, status := pool_pkg.get(&p, .Pool_Only, -1)
+	thread.join(th)
+	thread.destroy(th)
+
+	testing.expect(t, got == nil, "get should return nil when pool is destroyed")
+	testing.expect(t, status == .Closed, "status should be .Closed")
+}

tests/all_test.odin

@@ -45,6 +45,11 @@ test_master_example :: proc(t: ^testing.T) {
 	testing.expect(t, examples.master_example(), "master_example failed")
 }
 
+@(test)
+test_pool_wait :: proc(t: ^testing.T) {
+	testing.expect(t, examples.pool_wait_example(), "pool_wait_example failed")
+}
+
 // --- Mailbox edge-case tests ---
 
 // Msg is the local test message type.