[alloc+atomic] Making FirstFitBStackAllocator thread safe and other optimizations and fixes

[williamwutq]

Description: Under the flag atomic, making FirstFitBStackAllocator operations atomic and safe across threads with a mutex, implementing the rust Sync trait. In addition, various bug fixes and optimization are brought to FirstFitBStackAllocator.

Important Feature: No
Type: Allocator - Optimization; Allocator - Concurrent
Tests: Included
Feature Flags: alloc + set + atomic
Breaking change: No
New Types: None
Rust Only: No
Fuzz: Yes
Safety Review: Needed: Crash Safety, Invariants, Thread Safety

[Copilot]

Pull request overview

Adds opt-in thread safety (Send + Sync) to FirstFitBStackAllocator under the atomic feature, via an in-memory mutex that serializes free-list mutation and stack extension/discard, plus a recovery_needed flag updated through BStack::cas / bstack_cas. Also includes two pre-existing crash-safety/refactor fixes (recovery clear after non-flag-triggered recovery; missing recovery_needed guard around realloc tail-grow), allocation-buffer hoisting out of critical sections, and removal of redundant recovery_needed toggling inside cascade_discard_free_tail. Bumps the on-disk magic from ALFF\x00\x01\x02\x00 to ALFF\x00\x01\x03\x00 (compatibility check only inspects the first 6 bytes, so older 0.1.x files still open). Mirrors the Rust implementation in the C port and adds a libbstack-alloc-set-atomic.a build target.

Changes:

• FirstFitBStackAllocator gains a Mutex<()> (Rust) / pthread/Win32 mutex (C) under atomic, making it Sync; lock-free paths preserved for in-place same-bucket / same-block writes; recovery_needed set/clear use CAS under atomic, with recovery using a direct set to authoritatively reset the flag.
• realloc tail-grow now sets/clears recovery_needed (crash-safety fix); alloc/realloc hoist heap-buffer allocation out of the critical section; cascade_discard_free_tail no longer manages recovery_needed (caller's responsibility).
• Documentation updates across crate / module / type docs / README.md; CHANGELOG.md entry; PLANNED.md cleanup; C Makefile adds libbstack-alloc-set-atomic.a + test-first-fit-atomic; magic-byte/version bump in C header and source.

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
src/lib.rs	Updates crate-level thread-safety blurb for FirstFitBStackAllocator.
src/alloc/mod.rs	Updates module overview to describe Send + Sync under atomic.
src/alloc/first_fit.rs	Core change: adds optional Mutex, CAS-based set/clear_recovery_needed, lock acquisition in alloc/dealloc/realloc, hoists buffers out of critical sections, fixes tail-grow recovery, switches zero-length slices to BStackSlice::empty, bumps magic.
README.md	Expanded thread-safety section describing atomic feature semantics and contrast with LinearBStackAllocator.
PLANNED.md	Removes the now-implemented planned section about atomic FirstFit.
CHANGELOG.md	New [Unreleased] entries; mixes optimization items into ### Fixed.
c/Makefile	New libbstack-alloc-set-atomic.a lib and test-first-fit-atomic target linking -lpthread.
c/bstack_alloc.h	Magic bump, thread-safety docs, opaque void *lock field under BSTACK_FEATURE_ATOMIC.
c/bstack_alloc.c	FF_LOCK/FF_UNLOCK macros, mutex lifecycle in new/free/into_stack, CAS-based recovery flag, lock acquisition in ff_vt_alloc/dealloc/realloc, cascade no longer touches flag, magic update, authoritative reset after recovery.

---

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

[williamwutq]

LGTM