Adding di.cache module

di/cache/cache.md

@@ -0,0 +1,134 @@
+# 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`.
+
+- Default values for maxsize and maxindividual are set as 10 and 50 respectively
+- These can be changed using setmaxsize and setmaxindiv functions by using a single input in each with desired values.
+
+## 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:
+1. Executes `function` via `value`.
+2. If result size ≤ `.cache.maxindividual * MB`, ensures enough space:
+   - Calculates required space and evicts older entries as needed.
+3. Inserts or updates cache table, `funcs`, `results`, logs performance.
+4. 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]`.
+1. Looks for matching cache entry by function identity.
+2. If found and `age <= now – lastrun`:
+   - Updates `lastaccess`, logs a `hit`, returns cached result.
+3. If found but stale:
+   - Drops entry, logs `rerun`, re-executes via `add`.
+4. 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]
+2023
+q)r
+3
+```
+
+### 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]
+0
+q)r1
+3
+```
+
+### 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]
+2008
+q)r2
+3
+```
+
+### 4. Cache Performance Tracking
+The cache performance is tracked using `.cache.getperf[]`:
+
+```q
+q).cache.getperf[]
+time                          id status function
+------------------------------------------------------------------
+2013.11.06D12:41:53.103508000 2  add    {system"sleep 2"; x+y} 1 2
+2013.11.06D12:42:01.647731000 2  hit    {system"sleep 2"; x+y} 1 2
+2013.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 |
+
+---
+

di/cache/cache.q

@@ -0,0 +1,105 @@
+/ Library to provide a mechanism for storing function results in a cache and returning them from the cache if they are available and non stale.
+
+/ return timestamp function
+cp:.z.p;
+
+/ the maximum size of the cache in MB
+maxsize:10;
+
+/ the maximum size of any individual result set in MB
+maxindividual:50;
+
+/ function to change default max individual value
+setmaxindiv:{.z.m.maxindividual:x}
+
+/ function to change default max size value
+setmaxsize:{.z.m.maxsize:x}
+
+/ make sure the maxindividual isn't bigger than maxsize
+maxindividual:maxsize&maxindividual;
+
+/ mb conversion factor
+MB:2 xexp 20;
+
+/ a table to store the cache values in memory
+cache:([id:`u#`long$()] lastrun:`timestamp$();lastaccess:`timestamp$();size:`long$());
+
+/ a dictionary of the functions
+.z.M.funcs set (`u#`long$())!();
+
+/ the results of the functions
+results:(`u#`long$())!();
+
+/ table to track the cache performance
+perf:([]time:`timestamp$();id:`long$();status:`symbol$());
+
+id:0j;
+getid:{:id+::1};
+
+/ add to cache
+add:{[function;id;status]
+  / don't trap the error here - if it throws an error, we want it to be propagated out
+  res:value function;
+  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];;
+  / return the result
+  res};
+
+// Drop some ids from the cache
+drop:{[ids]
+  ids,:();
+  delete from .z.M.cache where id in ids;
+  results:: ids _ results;
+ };
+
+/ evict some items from the cache - need to clear enough space for the new item
+/ evict the least recently accessed items which make up the total size
+/ feel free to write a more intelligent cache eviction policy !
+evict:{[reqsize;currenttime]
+  r:select 
+    from
+      (update totalsize:sums size from `lastaccess xasc select lastaccess,id,size from cache)
+    where 
+      prev[totalsize]<reqsize;
+  drop[r`id];
+  trackperf[r`id;.z.M.evict;currenttime];
+ };
+
+trackperf:{[id;status;currenttime] .z.M.perf insert ((count id)#currenttime;id;(count id)#status)};
+
+/ check the cache to see if a function exists with a young enough result set
+execute:{[func;age]
+  / check for a value in the cache which we can use
+  $[count r:select id,lastrun from cache where .z.M.funcs[id]~\:enlist func;
+    / There is a value in the cache.
+    [r:first r;
+    / We need to check the age - if the specified age is greater than the actual age, return it
+    / else delete it
+    $[age > (now:.z.p) - r`lastrun;
+      / update the cache stats, return the cached result
+      [update lastaccess:now from .z.M.cache where id=r`id;
+      trackperf[r`id;`hit;now];
+      first results[r`id]];
+      / value found, but too old - re-run it under the same id
+      [drop[r`id];
+      add[func;r`id;`rerun]]]];
+    / it's not in the cache, so add it
+    add[func;getid[];`add]]};
+
+/ get the cache performance
+getperf:{update function:funcs[id] from perf}

di/cache/init.q

@@ -0,0 +1,4 @@
+/ Load core functionality into root module namespace
+\l ::cache.q
+
+export:([getperf;execute;setmaxindiv;setmaxsize]) 

di/cache/test.csv

@@ -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
+
+