[core] In memory caching of stack length (clen)

[williamwutq]

Description: Caching the length of the bstack to reduce need for io syscalls when reading length.

New Feature: No; No change to API
Important Feature: No
Type: Core - Optimization
Feature Flags: None
Breaking change: No
New Types: None
Rust Only: No
Fuzz: Not needed
Safety Review: Needed: Crash Safety, Invariants, Concurrency

[Copilot]

Pull request overview

This PR introduces an in-memory cache of the committed payload length (“clen”) so len/is_empty can be answered under a read lock without performing file-size syscalls, while keeping the cache synchronized with on-disk header updates.

Changes:

• Added an in-memory committed-length cache (clen) to the Rust and C implementations and plumbed it through write paths.
• Updated Rust BStack::len / BStack::is_empty and C bstack_len / bstack_is_empty to read the cached length rather than calling metadata/fstat/GetFileSizeEx.
• Updated documentation (crate docs, README, changelog, and C header comments) to reflect the new caching behavior.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 10 comments.

Show a summary per file

File	Description
src/lib.rs	Stores (File, clen) behind the rwlock and updates len/is_empty to use cached committed length.
README.md	Documents that len/is_empty no longer require a syscall due to caching.
CHANGELOG.md	Notes the no-syscall behavior change for Rust/C length queries without API/signature changes.
c/bstack.h	Updates API comments to describe cached len/is_empty semantics.
c/bstack.c	Adds clen to bstack_t, updates length reads, and threads cache updates through length-committing write paths.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated 10 comments.

[Copilot]

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated 14 comments.

[Copilot]

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated 4 comments.

[williamwutq]

LGTM