Skip to content

ext/yac: Add a Memory Management chapter and improve the examples - #5822

Merged
lacatoire merged 1 commit into
php:masterfrom
laruence:yac-docs-2026-09-01
Sep 2, 2026
Merged

ext/yac: Add a Memory Management chapter and improve the examples#5822
lacatoire merged 1 commit into
php:masterfrom
laruence:yac-docs-2026-09-01

Conversation

@laruence

@laruence laruence commented Sep 2, 2026

Copy link
Copy Markdown
Member

This adds a Memory Management chapter and reworks the method examples.

Memory Management chapter

New chapter (memory.xml, four sections) explaining the two independent shared-memory pools:

  • What Each Pool Holds — the key slot table vs. the value pool, embedded values, and a sizing guide for both pools
  • The key pool (slots) — fixed-size slot table; expired and deleted slots are reused for free, only a probe path of four live entries triggers an eviction (least recently used, then least hit, then earliest probe), which is what the kicks counter actually counts; why slots_used == slots_size is not an error
  • The value pool (segments) — 4M segments with a wrap-around bump allocator; a recycle overwrites the oldest values, whose reads fail the integrity guard and degrade to misses; the 1 MB stored-entry and 64 MB raw-value limits
  • Sizing and what to watch — how to read the Yac::info() counters (interval hit rate rather than lifetime average; kicks, recycles, fails) and which knob to turn for each symptom

Examples

  • Split the combined Yac::add / Yac::set / Yac::get / Yac::delete examples into one self-contained, runnable example per parameter form (single key, TTL, array form, default value, delayed deletion), verified against the extension
  • Fix the Yac::dump() paging example, which printed int(100) on an empty cache (it returned an empty array), and correct the per-entry hits description (the counter resets on overwrite, not on delete or expiry)

Other changes

  • Fill the empty constant descriptions (YAC_VERSION, YAC_MAX_VALUE_RAW_LEN, YAC_MAX_RAW_COMPRESSED_LEN) and fix typos in constants.xml
  • Align the synopsis parameter names with the arginfo ($keys -> $key)
  • Link the benchmarks section of the README from the introduction
  • Document the compress_threshold clamping (1024..1M, -1 disables) and the -1 disable semantics in the ini description
  • Drop the stale configure.xml template, which duplicated the installation section of setup.xml under the same xml:id

All examples were executed against the current extension build to verify their output.

Add a Memory Management chapter that explains the two independent
shared-memory pools:
- the key pool: a fixed-size slot table; expired and deleted slots are
  reused for free, and only a probe path of four live entries triggers
  an eviction (the least recently used, then the least hit), counted
  in the kicks counter
- the value pool: 4M segments with a wrap-around allocator whose
  recycles overwrite the oldest values, detected by a CRC integrity
  guard and turned into misses

Document how to size both pools and how to read the Yac::info counters
(interval hit rate, kicks, recycles, fails) so each number maps to a
concrete action.

Also improve the examples:
- split the combined add/set/get/delete examples into one runnable
  example per parameter form (single key, TTL, array form, default
  value, delayed deletion), each self-contained
- fix the Yac::dump paging example, which returned an empty array on
  an empty cache while claiming int(100), and correct the per-entry
  hits reset semantics (reset on overwrite, not on delete or expiry)

Further fixes:
- fill the empty constant descriptions (YAC_VERSION,
  YAC_MAX_VALUE_RAW_LEN, YAC_MAX_RAW_COMPRESSED_LEN) and fix typos
- align the synopsis parameter names with the arginfo ($keys -> $key)
- document compress_threshold clamping (1024..1M, -1 disables) and the
  1 MB stored-size / 64 MB raw-size limits
- drop the stale configure.xml template (duplicated the installation
  section of setup.xml)
@laruence
laruence force-pushed the yac-docs-2026-09-01 branch from 978b761 to 8ec44d6 Compare September 2, 2026 05:38
@lacatoire
lacatoire merged commit c05fbe7 into php:master Sep 2, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants