1#pragma once
 2
 3#include "fastfetch.h"
 4
 5// A cache for a value that is built at most once per generation.
 6//
 7// The value itself is owned by the entry owner (usually a file scope `static`); the entry only
 8// remembers whether that value is still valid and knows how to drop it. `--dynamic-interval`
 9// starts a new generation for every round, dropping all the values that have been built so far,
10// so the modules re-detect them instead of replaying the first round's snapshot.
11//
12// An entry registers itself the first time it is used. There is therefore no central list to keep
13// in sync, and a cache cannot be forgotten in it. Do not use this type for state that is carried
14// across calls to derive a rate (cpuusage, diskio, netio, top): that is a baseline rather than a
15// snapshot, and dropping it makes the first sample of a round read as zero.
16//
17// The storage pointed to by `storage` must stay valid for the whole run; only the value behind it
18// is dropped by an invalidation.
19//
20// Not thread safe: entries are only touched from a single thread, on a frame boundary, while the
21// modules are not running.
22typedef struct FFcacheEntry {
23    const char* name;               // For diagnostics.
24    void* storage;                  // Owned by the entry owner. May be nullptr.
25    void (*init)(void* storage);    // Optional. Runs whenever the entry is stale.
26    void (*destroy)(void* storage); // Optional. Must be idempotent, and tolerate a partially initialized storage.
27    bool initialized;
28    bool registered;
29    struct FFcacheEntry* next; // Internal: registry link.
30} FFcacheEntry;
31
32// Returns `entry->storage`, running `init` on it first when the entry is stale. The entry is marked
33// initialized before `init` runs, so a call made from within `init` returns the partially built
34// value instead of recursing.
35[[gnu::nonnull(1)]] void* ffCacheGet(FFcacheEntry* entry);
36
37// Staleness test for entries whose initialization needs arguments that are not part of the cache
38// identity (such as the cover file request of `ffDetectMedia`) and therefore cannot live behind
39// `init(void*)`. Returns true exactly once per generation: the caller must then build the value
40// itself.
41[[gnu::nonnull(1), nodiscard]] bool ffCacheBeginInit(FFcacheEntry* entry);
42
43// Drops the cached value of one entry, so that the next request builds it again. Idempotent, and
44// safe on an entry that has never been used.
45[[gnu::nonnull(1)]] void ffCacheInvalidate(FFcacheEntry* entry);
46
47// Drops every value that has been built so far. Called once per `--dynamic-interval` round.
48void ffCacheInvalidateAll(void);