From 27b753a7ba3333a46ed205c96a04e1b79797434b Mon Sep 17 00:00:00 2001 From: "google-labs-jules[bot]" <161369871+google-labs-jules[bot]@users.noreply.github.com> Date: Wed, 10 Jun 2026 00:09:16 +0000 Subject: [PATCH 1/3] =?UTF-8?q?=F0=9F=93=9C=20Codex:=20Documentation=20Syn?= =?UTF-8?q?chronization=20and=20Architectural=20Articulation?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: tedd <493224+tedd@users.noreply.github.com> --- .jules/codex.md | 3 +++ README.md | 15 +++++++++++++-- 2 files changed, 16 insertions(+), 2 deletions(-) create mode 100644 .jules/codex.md diff --git a/.jules/codex.md b/.jules/codex.md new file mode 100644 index 0000000..6714f17 --- /dev/null +++ b/.jules/codex.md @@ -0,0 +1,3 @@ +## 2026-06-10 - Architectural Execution Flow Articulation +**Observation:** The README.md documentation exhibited a deficit regarding the explicit articulation of the underlying multi-tiered allocation strategy (TLS cache, fast slot, shared array, and fallback). It lacked a clear delineation of the internal mechanics and did not explicitly state the absence of planned hypothetical enhancements, leaving room for speculative assumptions. Code examples were also not utilizing contemporary .NET features like target-typed `new()`. +**Strategic Action:** Synchronized the README.md to explicitly articulate the architectural execution flow, separating implemented capabilities from hypotheses. Updated code examples to leverage modern C# syntax. diff --git a/README.md b/README.md index d5adc1a..73e9a3c 100644 --- a/README.md +++ b/README.md @@ -34,7 +34,7 @@ using Tedd; using System.Text; var pool = new ObjectPool( - factory: () => new StringBuilder(capacity: 256), + factory: () => new(capacity: 256), cleanup: sb => sb.Clear(), // reset before publishing back size: 64 // total pool slots ); @@ -139,7 +139,7 @@ pool.Prefill(count: 32); ```csharp var socketPool = new ObjectPool( - factory: () => new System.Net.Sockets.Socket(System.Net.Sockets.SocketType.Stream, System.Net.Sockets.ProtocolType.Tcp), + factory: () => new(System.Net.Sockets.SocketType.Stream, System.Net.Sockets.ProtocolType.Tcp), cleanup: s => { /* reset if applicable */ }, size: 32, disposeWhenFull: true // overflowed sockets are disposed instead of dropped @@ -163,6 +163,17 @@ var socketPool = new ObjectPool( - The pool does not own lifetime of items except when `disposeWhenFull: true` is enabled for overflow. - `Dispose()` only tears down internal thread-local storage; it does not dispose pooled items. +## Architectural Execution Flow + +Tedd.ObjectPool utilizes a multi-tiered allocation strategy designed to minimize lock contention and interlocked operations on hot paths: + +1. **Thread-Local Storage (TLS) Cache:** The highest-priority path utilizes a per-thread, single-item cache (`ThreadLocal`). Most `Allocate` and `Free` pairs execute sequentially without touching shared memory or requiring CAS (Compare-And-Swap) instructions. +2. **Fast Slot (`_firstItem`):** If the TLS cache is empty during allocation (or full during deallocation), the pool attempts an optimistic read and a single CAS operation against a dedicated, highly-contended "fast slot". +3. **Shared Array (`_items`):** When the fast slot is occupied, the pool probes a shared array. To prevent cache-line ping-pong and CAS collisions under extreme concurrency, the probe initiates at a rotating index (`_allocIdx` / `_freeIdx`). +4. **Factory Fallback / Overflow:** If the array is exhausted during allocation, a new instance is instantiated via the provided delegate. During deallocation, if the pool is at maximum capacity, the object is either dropped for garbage collection or explicitly disposed (if `disposeWhenFull` is configured and the type implements `IDisposable`). + +*Note: The aforementioned architecture represents the established framework capabilities. There are currently no speculative future enhancements (hypotheses) planned for the core execution flow, ensuring strict deterministic behavior.* + ## Implementation and performance details - **Fast paths kept tiny**: `Allocate`/`Free` are aggressively inlined; slow paths are marked `NoInlining` to keep the I-cache hot. From ac0b78e78907225c022e1d4721f09b9fdf31ed2a Mon Sep 17 00:00:00 2001 From: Tedd Date: Wed, 17 Jun 2026 11:35:10 +0200 Subject: [PATCH 2/3] Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- README.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/README.md b/README.md index 73e9a3c..7a1cd95 100644 --- a/README.md +++ b/README.md @@ -167,9 +167,7 @@ var socketPool = new ObjectPool( Tedd.ObjectPool utilizes a multi-tiered allocation strategy designed to minimize lock contention and interlocked operations on hot paths: -1. **Thread-Local Storage (TLS) Cache:** The highest-priority path utilizes a per-thread, single-item cache (`ThreadLocal`). Most `Allocate` and `Free` pairs execute sequentially without touching shared memory or requiring CAS (Compare-And-Swap) instructions. -2. **Fast Slot (`_firstItem`):** If the TLS cache is empty during allocation (or full during deallocation), the pool attempts an optimistic read and a single CAS operation against a dedicated, highly-contended "fast slot". -3. **Shared Array (`_items`):** When the fast slot is occupied, the pool probes a shared array. To prevent cache-line ping-pong and CAS collisions under extreme concurrency, the probe initiates at a rotating index (`_allocIdx` / `_freeIdx`). +2. **Fast Slot (`_firstItem`):** If the TLS cache is empty during allocation, the pool attempts an optimistic read and a single CAS operation against a dedicated, highly-contended "fast slot". During deallocation (when TLS is already occupied), the pool publishes to the fast slot using `Volatile.Read`/`Volatile.Write` when it is observed empty. 4. **Factory Fallback / Overflow:** If the array is exhausted during allocation, a new instance is instantiated via the provided delegate. During deallocation, if the pool is at maximum capacity, the object is either dropped for garbage collection or explicitly disposed (if `disposeWhenFull` is configured and the type implements `IDisposable`). *Note: The aforementioned architecture represents the established framework capabilities. There are currently no speculative future enhancements (hypotheses) planned for the core execution flow, ensuring strict deterministic behavior.* From bdf4ccb2cde094b3eaca1772d0499cccd8fb96f9 Mon Sep 17 00:00:00 2001 From: Tedd Date: Wed, 17 Jun 2026 11:35:20 +0200 Subject: [PATCH 3/3] Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 7a1cd95..bc96a1e 100644 --- a/README.md +++ b/README.md @@ -170,7 +170,7 @@ Tedd.ObjectPool utilizes a multi-tiered allocation strategy designed to minimize 2. **Fast Slot (`_firstItem`):** If the TLS cache is empty during allocation, the pool attempts an optimistic read and a single CAS operation against a dedicated, highly-contended "fast slot". During deallocation (when TLS is already occupied), the pool publishes to the fast slot using `Volatile.Read`/`Volatile.Write` when it is observed empty. 4. **Factory Fallback / Overflow:** If the array is exhausted during allocation, a new instance is instantiated via the provided delegate. During deallocation, if the pool is at maximum capacity, the object is either dropped for garbage collection or explicitly disposed (if `disposeWhenFull` is configured and the type implements `IDisposable`). -*Note: The aforementioned architecture represents the established framework capabilities. There are currently no speculative future enhancements (hypotheses) planned for the core execution flow, ensuring strict deterministic behavior.* +*Note: The architecture described above reflects the current implementation. There are currently no speculative future enhancements (hypotheses) planned for the core execution flow.* ## Implementation and performance details