Add async memory operations with AsyncFileMem

[konard]

Summary

Implements GitHub issue #26: async memory access support with benchmarks.

• Add AsyncFileMem<T> type for async file-backed memory operations using tokio
• Add async feature flag to optionally enable async functionality
• Create comprehensive benchmarks comparing sync vs async memory operations
• Update documentation with async installation, usage examples, and API reference

Implementation Details

AsyncFileMem<T>

A new async file-backed memory type that provides:

• create(path) / open(path) / temp() - async constructors
• grow() / grow_filled() / grow_zeroed() / grow_from_slice() - async grow operations
• shrink() - async shrink operation
• get() / set() / as_slice() / as_slice_mut() - synchronous in-memory buffer access
• sync() / flush() - async persistence to disk

Why Not Async Mmap?

Memory-mapped file I/O cannot be truly asynchronous because page faults trigger synchronous disk operations. For truly async file access, AsyncFileMem uses explicit read/write operations with an in-memory buffer.

Feature Flags

# Enable async memory operations (uses tokio)
platform-mem = { version = "0.1", features = ["async"] }

Benchmarks

Added benchmarks in benches/memory_benchmarks.rs comparing:

• Sync allocator-based memory vs file-mapped memory
• Async file memory with sync operations
• Random read and sequential write patterns
• Grow/shrink cycles

Test plan

• All existing tests pass (72 coverage tests + 3 other tests)
• All new async tests pass (9 async-specific tests)
• Benchmarks compile and run
• Tests pass with and without async feature
• CI passes on all platforms (Ubuntu, macOS, Windows)

Files Changed

• Cargo.toml - Added async feature flag and tokio dependency
• src/lib.rs - Added conditional async module export
• src/async_mem.rs - New async memory implementation (493 lines)
• benches/memory_benchmarks.rs - Comprehensive benchmarks (280 lines)
• experiments/async_example.rs - Usage example
• README.md - Updated documentation

---

Fixes #26

🤖 Generated with Claude Code

[konard]

🤖 Solution Draft Log

This log file contains the complete execution trace of the AI solution draft process.

💰 Cost estimation:

• Public pricing estimate: $8.004834 USD
• Calculated by Anthropic: $5.706724 USD
• Difference: $-2.298110 (-28.71%)
  📎 Log file uploaded as Gist (1071KB)
  🔗 View complete solution draft log

---

Now working session is ended, feel free to review and add any feedback on the solution draft.