Adding di.cache module #76

jonathonmcmurray · 2026-01-27T08:49:47Z

we should have a function for users to change these config settings

jonathonmcmurray · 2026-01-27T08:49:56Z

add a comment to explain this

jonathonmcmurray · 2026-01-27T08:49:06Z

inconsistent indentation

jonathonmcmurray · 2026-01-27T08:50:31Z

comments should start with lowercase as per style guide

jonathonmcmurray · 2026-01-27T08:54:44Z

I think it would be worth refactoring this to avoid the code block inside $ https://github.com/DataIntellectTech/kdbx-modules/blob/main/style.md#conditionals-and-execution-control

e.g. something like this, reversing the condition & returning early if the result is too large

Suggested change

$[(maxindividual*MB)>size:-22!res;

/ check if we need more space to store this item

[now:cp[];

if[0>requiredsize:(maxsize*MB) - size+sum exec size from cache; evict[neg requiredsize;now]];

/ Insert to the cache table

.z.M.cache upsert (id;now;now;size);

/ and insert to the function and results dictionary

funcs[id]:enlist function;

results[id]:enlist res;

/ Update the performance

trackperf[id;status;now]];

/ Otherwise just log it as an addfail - the result set is too big

trackperf[id;`fail;cp[]]];

if[(maxindividual*MB)<=size:-22!res;

/ log it as an addfail - the result set is too big

trackperf[id;`fail;cp[]];

:res;

];

/ check if we need more space to store this item

now:cp[];

if[0>requiredsize:(maxsize*MB) - size+sum exec size from cache;

evict[neg requiredsize;now];

];

/ Insert to the cache table

.z.M.cache upsert (id;now;now;size);

/ and insert to the function and results dictionary

funcs[id]:enlist function;

results[id]:enlist res;

/ Update the performance

trackperf[id;status;now]];

jonathonmcmurray · 2026-01-27T08:50:10Z

comments from here onwards use // instead of /

jonathonmcmurray · 2026-01-27T08:56:01Z

I don't think add or drop should be exposed to end users, I don't think we'd expect them to be using those functions directly

-Original file line number
+Diff line change
@@ -0,0 +1,131 @@
+    # Cache
+    `cache.q` provides an in-memory, parameterized caching mechanism for storing and reusing function results, reducing computation time for repeat calls.
+    ## Configuration Variables
+    - **`.cache.maxsize`** — Maximum total cache size in MB.
+    - **`.cache.maxindividual`** — Maximum size in MB allowed for a single cache entry; capped at `maxsize`.
+    - **`MB`** — Defines one megabyte as `2 * xexp 20`.
+    ## Core Structures
+    - **`cache`** (table) — Tracks cache entries:
+      - `id` (long)
+      - `lastrun`, `lastaccess` (timestamps)
+      - `size` (bytes)
+    - **`funcs`** (dict) — Maps `id` to the cached function.
+    - **`results`** (dict) — Maps `id` to the resulting data.
+    - **`perf`** (table) — Logs cache performance with columns:
+      - `time` (timestamp)
+      - `id` (long)
+      - `status` (symbol: `add`, `hit`, `fail`, `evict`, `rerun`)
+    ## Main Functions
+    ### `getid`
+    Generates unique IDs for new cache entries by incrementing a global counter.
+    ### `add`
+    Takes parameters `[function; id; status]` and:
+. Executes `function` via `value`.
+. If result size ≤ `.cache.maxindividual * MB`, ensures enough space:
+       - Calculates required space and evicts older entries as needed.
+. Inserts or updates cache table, `funcs`, `results`, logs performance.
+. Otherwise, logs a `fail` and returns the result without caching.
+    ### `drop`
+    Removes specific cache entries by `id`, updating both the cache table and results dict.
+    ### `evict`
+    Evicts least-recently-accessed items until required space is freed:
+    - Sorts by `lastaccess`, sums sizes, iteratively drops entries.
+    - Logs `evict` in `perf`.
+    ### `trackperf`
+    Logs performance events (`add`, `hit`, `fail`, `evict`, `rerun`) with timestamps into `perf`.
+    ### `execute`
+    Parameters: `[func; age]`.
+. Looks for matching cache entry by function identity.
+. If found and `age <= now – lastrun`:
+       - Updates `lastaccess`, logs a `hit`, returns cached result.
+. If found but stale:
+       - Drops entry, logs `rerun`, re-executes via `add`.
+. If not present:
+       - Adds a new cache entry via `add`.
+    ### `getperf`
+    Returns `perf` table with function mappings added for each event entry.
+    # Cache Example Usage
+    This example demonstrates how `.cache.execute` works with caching and stale time logic, along with performance tracking using `.cache.getperf[]`.
+    ## Example Steps
+    ### 1. First Execution
+    The function is run and the result placed in the cache:
+    ```q
+    q)       \t r:execute[({system"sleep 2"; x+y};1;2);0D00:01]
+    q)r
+    ```
+    ### 2. Second Execution (Cache Hit)
+    The second time round, the result set is returned immediately from the cache as we are within the stale time value:
+    ```q
+    q)       \t r1:execute[({system"sleep 2"; x+y};1;2);0D00:01]
+    q)r1
+    ```
+    ### 3. Execution After Stale Time (Re-run)
+    If the time since the last execution is greater than the required stale time, the function is re-run, the cached result is updated, and the result returned:
+    ```q
+    q)       \t r2:execute[({system"sleep 2"; x+y};1;2);0D00:00]
+    q)r2
+    ```
+    ### 4. Cache Performance Tracking
+    The cache performance is tracked using `.cache.getperf[]`:
+    ```q
+    q).cache.getperf[]
+    time                          id status function
+    ------------------------------------------------------------------
+.11.06D12:41:53.103508000 2  add    {system"sleep 2"; x+y} 1 2
+.11.06D12:42:01.647731000 2  hit    {system"sleep 2"; x+y} 1 2
+.11.06D12:42:53.930404000 2  rerun  {system"sleep 2"; x+y} 1 2
+    ```
+    ---
+    ## Cache Table Schema
+    | Column       | Type       | Description                                      |
+    |--------------|------------|--------------------------------------------------|
+    | `id`         | `long`     | Unique identifier for cached entry               |
+    | `lastrun`    | `timestamp`| When the entry was initially added               |
+    | `lastaccess` | `timestamp`| When entry was last served from cache            |
+    | `size`       | `long`     | Byte size of the cached result                   |
+    ## perf Table Schema
+    | Column  | Type        | Description                                |
+    |---------|-------------|--------------------------------------------|
+    | `time`  | `timestamp` | When the cache event occurred              |
+    | `id`    | `long`      | Corresponding cache entry ID               |
+    | `status`| `symbol`    | Event type (`add`, `hit`, `fail`, etc.)    |
+    | `function` (added via `getperf`) | `function` | Cached function for the event |
+    ---

-Original file line number
+Diff line change
@@ -0,0 +1,4 @@
+    / Load core functionality into root module namespace
+    \l ::cache.q
+    export:([getperf;add;drop;execute])

-Original file line number
+Diff line change
@@ -0,0 +1,40 @@
+    action,ms,bytes,lang,code,repeat,minver,comment
+    before,0,0,q,cac:use`di.cache,1,1,load package into session
+    / Test 1: Baseline Addition with Sleep
+    run,0,0,q,system "t cac.execute[({system\"sleep 1\"; x+y};10;20);0D00:01]",1,1,Initial run with 1s sleep
+    true,0,0,q,0~ system "t cac.execute[({system\"sleep 1\"; x+y};10;20);0D00:01]",1,1,Speedup: Cached result returns in <1ms
+    / Test 2: String Manipulation Speed
+    run,0,0,q,system "t cac.execute[({system\"sleep 1\"; upper x};\"hello world\");0D00:01]",1,1,Initial run with string conversion
+    true,0,0,q,0~ system "t cac.execute[({system\"sleep 1\"; upper x};\"hello world\");0D00:01]",1,1,Speedup: String conversion cached
+    / Test 3: Matrix Multiplication (Mock)
+    run,0,0,q,system "t cac.execute[({system\"sleep 1\"; (reverse x) * y};500;1000);0D00:01]",1,1,Initial run with numeric calc
+    true,0,0,q,0~ system "t cac.execute[({system\"sleep 1\"; (reverse x) * y};500;1000);0D00:01]",1,1,Speedup: Numeric calc cached
+    / Test 4: Join Operations
+    run,0,0,q,system "t cac.execute[({system\"sleep 1\"; x uj y};([]a:1 2);([]a:3 4));0D00:01]",1,1,Initial run with table join
+    true,0,0,q,0~ system "t cac.execute[({system\"sleep 1\"; x uj y};([]a:1 2);([]a:3 4));0D00:01]",1,1,Speedup: Table join cached
+    / Test 5: Type Checking & Casting
+    run,0,0,q,system "t cac.execute[({system\"sleep 1\"; `int$x};123.456);0D00:01]",1,1,Initial run with casting
+    true,0,0,q,0~ system "t cac.execute[({system\"sleep 1\"; `int$x};123.456);0D00:01]",1,1,Speedup: Casting cached
+    / Test 6: Nested List Flattening
+    run,0,0,q,system "t cac.execute[({system\"sleep 1\"; raze x};(1 2;3 4;5 6));0D00:01]",1,1,Initial run with raze
+    true,0,0,q,0~ system "t cac.execute[({system\"sleep 1\"; raze x};(1 2;3 4;5 6));0D00:01]",1,1,Speedup: Raze cached
+    /Test 7: Check if output is correct
+    run,0,0,q,cac.execute[({x+1};1);0D00:01],1,1,cache sleep functionality
+    true,0,0,q,2~cac.execute[({x+1};1);0D00:01],1,1,cached sleep functionality
+    / Test 8: Table Result Correctness
+    run,0,0,q,res::([]a:1 2 3;b:`x`y`z);cac.execute[({x};res);0D00:01],1,1,Initial run: cache a table
+    true,0,0,q,res ~ cac.execute[({x};res);0D00:01],1,1,Check: Table retrieved from cache matches original
+    / Test 9: Complex Dictionary Result
+    run,0,0,q,dict::`stats`data!((avg;med);til 10);cac.execute[({x};dict);0D00:01],1,1,Initial run: cache a dictionary of functions and lists
+    true,0,0,q,dict ~ cac.execute[({x};dict);0D00:01],1,1,Check: Dictionary retrieved from cache matches original

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Adding di.cache module #76

Diff view

Diff view

There are no files selected for viewing

jonathonmcmurray Jan 27, 2026

Uh oh!

jonathonmcmurray Jan 27, 2026

Uh oh!

jonathonmcmurray Jan 27, 2026

Uh oh!

jonathonmcmurray Jan 27, 2026

Uh oh!

jonathonmcmurray Jan 27, 2026

Uh oh!

jonathonmcmurray Jan 27, 2026

Uh oh!

jonathonmcmurray Jan 27, 2026

Uh oh!

Adding di.cache module #76

Are you sure you want to change the base?

Adding di.cache module #76

Uh oh!

Uh oh!

Diff view

Diff view

There are no files selected for viewing

jonathonmcmurray Jan 27, 2026

Choose a reason for hiding this comment

Uh oh!

jonathonmcmurray Jan 27, 2026

Choose a reason for hiding this comment

Uh oh!

jonathonmcmurray Jan 27, 2026

Choose a reason for hiding this comment

Uh oh!

jonathonmcmurray Jan 27, 2026

Choose a reason for hiding this comment

Uh oh!

jonathonmcmurray Jan 27, 2026

Choose a reason for hiding this comment

Uh oh!

jonathonmcmurray Jan 27, 2026

Choose a reason for hiding this comment

Uh oh!

jonathonmcmurray Jan 27, 2026

Choose a reason for hiding this comment

Uh oh!