ext/yac: Add a Memory Management chapter and improve the examples - #5822
Merged
Conversation
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
force-pushed
the
yac-docs-2026-09-01
branch
from
September 2, 2026 05:38
978b761 to
8ec44d6
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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:kickscounter actually counts; whyslots_used == slots_sizeis not an errorrecycleoverwrites the oldest values, whose reads fail the integrity guard and degrade to misses; the 1 MB stored-entry and 64 MB raw-value limitsYac::info()counters (interval hit rate rather than lifetime average;kicks,recycles,fails) and which knob to turn for each symptomExamples
Yac::add/Yac::set/Yac::get/Yac::deleteexamples into one self-contained, runnable example per parameter form (single key, TTL, array form,defaultvalue, delayed deletion), verified against the extensionYac::dump()paging example, which printedint(100)on an empty cache (it returned an empty array), and correct the per-entryhitsdescription (the counter resets on overwrite, not on delete or expiry)Other changes
YAC_VERSION,YAC_MAX_VALUE_RAW_LEN,YAC_MAX_RAW_COMPRESSED_LEN) and fix typos inconstants.xml$keys->$key)compress_thresholdclamping (1024..1M, -1 disables) and the-1disable semantics in the ini descriptionconfigure.xmltemplate, which duplicated the installation section ofsetup.xmlunder the samexml:idAll examples were executed against the current extension build to verify their output.