Skip to content

fs: size the FAT cache from the volume instead of a fixed 8192 elements #978

Closed

Description

@LSantha

Summary

Fat constructs new FatCache(this, 8192, 512) unconditionally. The CacheMap constructor
pre-allocates cacheSize + 1 = 8193 CacheElements, each wrapping new byte[elementSize + 1], plus
a LinkedHashMap sized to hold them - roughly 4.2 MiB allocated at mount for every JFAT volume,
regardless of volume size or available RAM
. It is the largest single filesystem allocation, and on
a small JNode target that matters.

On top of the size, the free-element pool is a legacy java.util.Stack (synchronized methods, used
single-threaded, pure overhead) and getCacheStat() has no logging site other than
FatFileSystem.flush's debug line.

Still unfixed; neither JFAT round touched cache sizing.

Evidence (static + measured, current master 305f050359, re-verified before filing)

// Fat.java:79
cache = new FatCache(this, 8192, 512);

// FatCache.java CacheMap ctor
for (int i = 0; i < cacheSize + 1; i++)
    free.push(new CacheElement());
// CacheElement ctor
this.elem = ByteBuffer.wrap(new byte[elementSize + 1]);    // 513 B each, 8193 times
private final Stack<CacheElement> free = new Stack<CacheElement>();   // line 311

So: 8193 x 513 B ~ 4.2 MiB of element data, plus 8193 CacheKey objects, plus 8193 ByteBuffer
wrappers, plus a LinkedHashMap with initial capacity ~10923. The doc's arithmetic matches.

Measured on a 200 MiB / 50,071-cluster FAT32 volume: a clean flush() costs median 30 us - so the
cache works; the problem is purely the fixed footprint and the pool's overhead.

Complexity, effort and impact (source doc, Appendix F/I)

  • Maps to: OPT-06, plus the Stack -> ArrayDeque half of OPT-02
  • Complexity: S-M Effort: 2-5 d
  • Impact: Medium memory and hit-ratio - up to ~4 MiB less per mount on small volumes; avoids
    scan-induced eviction of the working set. No effect when the working set already fits.
  • Workloads moved: mixed workloads and small-RAM targets
  • Why it costs what it costs (Appendix I): the sizing heuristic plus 2Q/scan-resistance plus
    Stack -> ArrayDeque plus metric wiring.

What to fix

  1. Size from the volume and the config. Something like
    min(8192, max(256, sectorsPerFat / 4)), overridable by a jnode.fat.cacheSize property with the
    current 8192 as the documented default. A 1 GiB FAT32 volume has ~2K FAT sectors, so half the
    elements would be dead weight today.
  2. Replace Stack with ArrayDeque. Mechanical; removes per-operation synchronization on the
    free list. (01-performance/p04's dirty set may replace this pool entirely - do them together or
    say which wins.)
  3. Scan resistance. getFreeSpace-style full scans walk the whole FAT through this cache and
    evict the working set. getFreeSpace is now O(1) via the counter (fs: the free-cluster counter is never updated, so free-space tracking drifts #860), so the remaining scan is
    allocateTail's free search - worth a small scan-resistant tier (or fixing p05, which removes
    the scan).
  4. Promote getCacheStat to a real metric. One log.info on FatFileSystem.flush plus the
    access/hit/ratio fields is enough; it makes every other perf ticket verifiable.

Acceptance criteria

  • Cache size is computed, not a literal, with the config override documented in
    jnode.properties (and the "what happens if set absurdly" case handled).
  • Small volumes allocate proportionally less; the default behaviour on today's test images is
    unchanged or better.
  • No java.util.Stack remains in FatCache.
  • getCacheStat is reachable from a log line (guarded by isInfoEnabled/debug, not unconditional).
  • FatCopyComparisonTest, FatFreeClusterCountTest, FatFailurePathTest (eviction paths) stay
    green - eviction is where a sizing change bites.
  • sh build.sh -f fs/build-tests.xml all-junit green; FatWriteBench not regressed.

Out of scope

  • Selective flush (01-performance/p04).
  • The CacheKey single-mutable-lookup-key pattern (already handled by jfat-review/02-concurrency/r14).
  • Memory-pressure hooks into the JNode allocator (a separate infrastructure question).

Environment

- Commit: `305f050359` (the draft quoted `7b49565eb1`, ~30 merges back; re-checked, premise unchanged: `Fat.java:104` still `new FatCache(this, 8192, 512)` and the pool is still `Stack`)
- Host JDK: OpenJDK 11.0.13 (build accepts 1.6/1.7/1.8)
- Build target: `sh build.sh -f fs/build-tests.xml all-junit`
- Source doc refs: `jfat-ide-fileio-performance-analysis.md` section 4.3, OPT-06, OPT-02 (Stack)

Measured on 305f050359 (ProbeCacheSize, ThreadMXBean allocated bytes around the constructor,
host JVM, FAT32 1 KiB clusters):

new FatCache(fat,  8192, 512) ->   5.08 MiB allocated   (0.6 KiB/element)
new FatCache(fat,  4096, 512) ->   2.54 MiB
new FatCache(fat,  2048, 512) ->   1.27 MiB
new FatCache(fat,  1024, 512) ->   0.64 MiB
pool type at runtime: java.util.Stack

So the mount-time cost is ~5.08 MiB, not the 4.2 MiB the draft estimated (0.6 KiB per element rather
than 0.5), and it is exactly linear in cacheSize, which is what makes sizing by volume/RAM a clean
lever. Note dirtyElements is already an ArrayDeque, so only the free pool is still Stack.

Triage Addendum (auto, 2026-11-16)

  • Area / Kind: area/fs (Sub: FAT cache) + area/build; kind/chore
  • Blast radius: L2 package (org.jnode.fs.jfat: Fat, FatCache, FatFileSystem; exported package, keep public signatures; FAT mount/eviction/write path)
  • Expected scope: Fat.java computed/clamped cache size + jnode.fat.cacheSize; FatCache.java Stack -> ArrayDeque; FatFileSystem.java guarded getCacheStat log; config docs. ~40-80 lines. No on-disk format, public API, p04/p05, or allocator-hook changes.
  • Test path: sh build.sh -f fs/build-tests.xml all-junit (FatCopyComparisonTest, FatFreeClusterCountTest, FatFailurePathTest); FatWriteBench non-regression; QEMU FAT mount/write/flush smoke.
  • Merge signal: human-review (FAT mount/eviction/write path; sizing heuristic and clamp policy need review; host tests do not cover real volume geometry)
  • Gaps: non-blocking: confirm runtime property source (jnode.properties.dist / .github/qemu/jnode.properties, not root jnode.properties); define clamp policy for absurd values; decide scan-resistance vs p05 follow-up.
  • Full report: ## Triage comment below.

✅ Ticket Runner Status

Field Value
Phase DONE
Turn 1/7
Retries 0/3
PR #979
Review in progress no
Started 2026-11-16T13:20:46.180Z

Activity

  1. added
    kind/choreRefactor, typo sweep, dead-code removal; no behavior change.
    area/fsfs/ — filesystem drivers (FAT, ext2, HFS+, NTFS, ISO9660, ExFAT).
    on Nov 16, 2026
  2. LSantha commented on Nov 16, 2026

    @LSantha
    OwnerAuthor

    /oc triage issue #978

    Triage run ONLY. Load the jnode-triage-issue skill and obey it. Output is exactly one ## Triage comment plus kind/area label edits. FORBIDDEN in this run: git checkout -b, git push, gh pr create, any branch, any PR.

  3. added
    area/buildBuild system, jnode.properties, plugin lists, ant targets.
    on Nov 16, 2026
  4. LSantha commented on Nov 16, 2026

    @LSantha
    OwnerAuthor

    Triage

    • Area: area/fs (Sub: FAT cache) + area/build (property documentation/wiring)
    • Kind: kind/chore (performance/memory optimization; no functional behavior change)
    • Repro: measured new FatCache(fat, 8192, 512) => 5.08 MiB; Fat.java:104 literal and FatCache.java:374 Stack verified at 305f050
    • Blast radius: L2 package (org.jnode.fs.jfat: Fat, FatCache, FatFileSystem; exported package org.jnode.fs.jfat.* so keep public signatures; FAT mount/eviction/write path)
    • Expected scope: Fat.java computed/clamped sizing + jnode.fat.cacheSize; FatCache.java Stack -> ArrayDeque; FatFileSystem.java guarded getCacheStat info log; config docs. ~40-80 lines. No on-disk format, public API, p04/p05, or allocator hooks.
    • Test path: sh build.sh -f fs/build-tests.xml all-junit (FatCopyComparisonTest, FatFreeClusterCountTest, FatFailurePathTest); FatWriteBench non-regression; QEMU FAT mount/write/flush smoke.
    • Merge signal: human-review (FAT mount/eviction/write path; sizing heuristic and clamp policy need review; host tests do not cover real volume geometry)
    • Gaps: non-blocking: runtime property source (jnode.properties.dist / .github/qemu/jnode.properties; no root jnode.properties); exact clamp policy for absurd values; scan-resistance vs p05 follow-up.
    • Suggested next: fix
    • Split proposal: none - focused (one package, ~4 files); p05 scan removal is a separate follow-up
    • Labels applied: kept kind/chore, area/fs; added area/build (config documentation/wiring); no removals.

    github run

  5. LSantha commented on Nov 16, 2026

    @LSantha
    OwnerAuthor

    /oc Please proceed with this task.

  6. LSantha commented on Nov 16, 2026

    @LSantha
    OwnerAuthor

    🤖 Working on this. Run: ack
    Plan: (1) read Fat/FatCache/FatFileSystem + config, (2) computed cache size + jnode.fat.cacheSize override + clamp, (3) Stack→ArrayDeque, guarded getCacheStat log, (4) run fs junit suite + write PR.

  7. LSantha commented on Nov 16, 2026

    @LSantha
    OwnerAuthor

    DEV report (run 305f050)

    Changes

    • Fat.java — cache size at mount now FatCache.resolveCacheSize(bs.getSectorsPerFat(), cacheSizeOverride()) instead of literal 8192; cacheSizeOverride() reads jnode.fat.cacheSize from VmIOContext.getGlobalProperties() (null-safe for host tests).
    • FatCache.java — new computeCacheSize(sectorsPerFat) = min(8192, max(256, sectorsPerFat / 4)); resolveCacheSize(sectorsPerFat, propertyValue): property wins when set/parsable, clamped to [16, 65536] with a warn log; unparseable value ignored with a warn log and the computed default used. java.util.Stack removed; free pool is now ArrayDeque. No public API removed (package is exported).
    • FatFileSystem.java — getCacheStat() now reachable via guarded log.info on flush() (if (log.isInfoEnabled())), was isDebugEnabled/debug.
    • .github/qemu/jnode.properties — jnode.fat.cacheSize documented (runtime-property home, same section as jnode.ide.writethrough); root jnode.properties untouched. Computed value is capped at the historical 8192; jnode.fat.cacheSize=8192 restores legacy behaviour exactly.
    • New FatCacheSizeTest (9 tests: compute/clamp/parse/whitespace paths), wired into FSTestSuite.
    • FatFailurePathTest.testFlushFailureReconcilesFreeClusterCount now pins jnode.fat.cacheSize=8192 for the duration of the test (try/finally resets to null): the test's premise is a cache-resident FAT (the rescan must not evict the dirty element, whose flush fails on the armed device); on the 68 MiB image the computed default (256) is no longer cache-resident, which made that premise false. All other 8 cacheSize-related behaviours unchanged.

    Not done / notes

    • Scan-resistance tier (item 3) intentionally not added: p05 removes the allocateTail free search outright and is a separate ticket; adding a 2Q tier now would be speculative on top of an unmerged change. Left as follow-up with p05.
    • Selective flush (p04) untouched, per out-of-scope.
    • Scan-induced eviction of the working set during allocateTail remains possible until p05 lands.

    Verification

    • sh build.sh -f fs/build-tests.xml all-junit → BUILD SUCCESSFUL; FSTestSuite 473 tests, 0 failures (was 464; +9 FatCacheSizeTest). FatWriteBench (in suite) green.
    • QEMU smoke (TCG, no KVM): booted jnode-x86-lite, 64 MiB FAT32 image (MBR type 0x0c) attached as hdb0 → FileSystemMounter logged Mounted JFAT on /devices/hdb0; echo hello-jfat-oc978 > /devices/hdb0/test.txt, sync, reboot, cat → persisted content read back; FatFileSystem logged FAT cache stats: Access: 127020 Hits: 126026 Ratio: 99.2% at INFO on flush. Note: with a 252-sector FAT the computed cache is 256 elements and the mount-time full scan works fine.
    • Host JDK 1.8.0_512 used for build; Java 1.6 source level respected (no diamond/lambda/multi-catch/try-with-resources in the diff).

    Merge signal per triage: human-review (sizing heuristic + clamp policy).

  8. LSantha commented on Nov 16, 2026

    @LSantha
    OwnerAuthor

    Created PR #979

    github run

  9. added
    agent/doneThe agent finished successfully; PR opened or comment posted.
    and removed
    agent/in-progressThe OpenCode agent is currently working on this issue.
    on Nov 16, 2026
  10. added a commit that references this issue on Nov 16, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    agent/doneThe agent finished successfully; PR opened or comment posted.area/buildBuild system, jnode.properties, plugin lists, ant targets.area/fsfs/ — filesystem drivers (FAT, ext2, HFS+, NTFS, ISO9660, ExFAT).kind/choreRefactor, typo sweep, dead-code removal; no behavior change.

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions