Two release threads

src/thread_pipeline.hpp

@@ -268,6 +268,47 @@ int check_producer_capacity(
 //   }
 //   // Guard destructor marks items as consumed and available to next stage
 //
+// Multi-Thread Stage Processing:
+// When a stage has multiple threads (e.g., 1, 1, 1, 2 = 2 threads in stage 3):
+//
+// OVERLAPPING BATCHES - EACH THREAD SEES EVERY ENTRY:
+// - Multiple threads in the same stage get OVERLAPPING batches from the ring
+// buffer
+// - Thread 0: calls acquire<3, 0>() - gets batch from ring positions 100-110
+// - Thread 1: calls acquire<3, 1>() - gets batch from ring positions 100-110
+// (SAME)
+// - Both threads see the same entries and must coordinate processing
+//
+// PARTITIONING STRATEGIES:
+// Choose your partitioning approach based on your use case:
+//
+// 1. Ring buffer position-based partitioning:
+//   for (auto it = batch.begin(); it != batch.end(); ++it) {
+//     if (it.index() % 2 != thread_index) continue; // Skip entries for other
+//     threads process(*it); // Process only entries assigned to this thread
+//   }
+//
+// 2. Entry content-based partitioning:
+//   for (auto& item : guard.batch) {
+//     if (hash(item.connection_id) % 2 != thread_index) continue;
+//     process(item); // Process based on entry properties
+//   }
+//
+// 3. Process all entries (when each thread does different work):
+//   for (auto& item : guard.batch) {
+//     process(item); // Both threads process all items, but differently
+//   }
+//
+// Common Partitioning Patterns:
+// - Position-based: it.index() % num_threads == thread_index
+// - Hash-based: hash(item.key) % num_threads == thread_index
+// - Type-based: item.type == MY_THREAD_TYPE
+// - Load balancing: assign work based on thread load
+// - All entries: each thread processes all items but performs different
+// operations
+//
+// Note: it.index() returns the position in the ring buffer (0 to buffer_size-1)
+//
 // Memory Model:
 // - Ring buffer size must be power of 2 for efficient masking
 // - Actual ring slots accessed via: index & (slotCount - 1)