From bbe5fcdf4c203db67e409092d067c76e3b397dac Mon Sep 17 00:00:00 2001 From: Abdelrahman Said Date: Sat, 4 Jul 2026 20:39:57 +0100 Subject: [PATCH] Update AGENTS.md --- AGENTS.md | 26 ++++++++++++++++++++++++-- 1 file changed, 24 insertions(+), 2 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 82a2260..97536a0 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -167,8 +167,30 @@ can fail if the backing buffer is exhausted. passing a runtime variable triggers undefined behaviour and compiler warnings. Use `wpArrayAllocCapacity` with an arena allocator for runtime sizes. -Initialise arrays with `WP_ARRAY_INIT_FILLED` to set `count = capacity` -immediately, allowing direct indexing. +Always use typed array aliases (`WpU64Array`, `PrNodeIdArray`, etc.) rather +than raw pointers when declaring array variables. Follow the existing typedef +pattern in the module (`typedef Type *TypeArray`). + +Use named init flags (`WP_ARRAY_INIT_NONE`, `WP_ARRAY_INIT_FILLED`) instead of +bare `0` — they make the initialisation policy explicit. + +- `WP_ARRAY_INIT_FILLED`: sets `count = capacity` on allocation. Required when + you plan to index into the array directly (not via append/push), since the + array's `count` must reflect valid elements for any downstream use. +- `WP_ARRAY_INIT_NONE`: leaves `count = 0`. Use when you'll fill the array + incrementally via `wpArrayAppendCapped` / `wpArrayAppendAlloc`. + +Use `wpArrayCapacity(arr)`, `wpArrayCount(arr)`, `wpArraySetCount(arr, n)` to +query and control array state rather than computing sizes manually. + +### Local/scratch arenas + +For function-local scratch allocations, use `wpMemArenaAllocatorInitZero` with a +fixed size rather than a stack buffer + `InitWithBuffer`: + +```c +WpAllocator scratch = wpMemArenaAllocatorInitZero(KiB(16)); +``` ## Documentation