kcl-lib 0.2.165

KittyCAD Language implementation and tools
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133

# KCL Memory Backend Profiling

This directory contains the memory backend implementations. Use
`KCL_MEMORY_IMPL` to choose which backend to run:

```sh
KCL_MEMORY_IMPL=legacy
KCL_MEMORY_IMPL=arena
```

Set the backend explicitly for comparisons. Do not rely on the default while
changing which implementation is preferred.

Run all commands from the Rust workspace root:

```sh
cd rust
```

## Validate A Backend

Run the memory backend parity tests first:

```sh
KCL_MEMORY_IMPL=arena cargo nextest run --retries 3 --no-fail-fast -p kcl-lib --locked -- memory_backends
KCL_MEMORY_IMPL=legacy cargo nextest run --retries 3 --no-fail-fast -p kcl-lib --locked -- memory_backends
```

For a full workspace check, run:

```sh
KCL_MEMORY_IMPL=arena cargo nextest run --workspace --retries 3 --no-fail-fast --locked
KCL_MEMORY_IMPL=legacy cargo nextest run --workspace --retries 3 --no-fail-fast --locked
```

## CPU Benchmarks

Use the Criterion memory benchmark for CPU timing:

```sh
KCL_MEMORY_IMPL=legacy cargo bench -p kcl-lib --bench memory_benchmark_criterion --locked
KCL_MEMORY_IMPL=arena cargo bench -p kcl-lib --bench memory_benchmark_criterion --locked
```

Criterion writes detailed reports under:

```text
target/criterion/memory_execution/
```

Compare the same workload names between backends. Current workloads are:

```text
many_closure_snapshots
many_bindings_and_lookups
shadowed_function_calls
function_chain_calls
wide_object_access
array_index_lookups
std_prelude_lookups
```

For stable CPU numbers, keep the machine quiet and avoid comparing Criterion
results against DHAT runs. DHAT changes the allocator and adds instrumentation
overhead.

## Heap Profiling

Use the `memory_profile` bench with the `dhat-heap` feature for allocation and
live-heap stats. The output is CSV.

Run all workloads:

```sh
KCL_MEMORY_IMPL=legacy cargo bench -p kcl-lib --bench memory_profile --features dhat-heap --locked -- --iterations 20
KCL_MEMORY_IMPL=arena cargo bench -p kcl-lib --bench memory_profile --features dhat-heap --locked -- --iterations 20
```

Run one workload:

```sh
KCL_MEMORY_IMPL=legacy cargo bench -p kcl-lib --bench memory_profile --features dhat-heap --locked -- --workload function_chain_calls --iterations 20
KCL_MEMORY_IMPL=arena cargo bench -p kcl-lib --bench memory_profile --features dhat-heap --locked -- --workload function_chain_calls --iterations 20
```

Capture results for comparison:

```sh
KCL_MEMORY_IMPL=legacy cargo bench -p kcl-lib --bench memory_profile --features dhat-heap --locked -- --iterations 20 | tee /tmp/kcl-memory-legacy.csv
KCL_MEMORY_IMPL=arena cargo bench -p kcl-lib --bench memory_profile --features dhat-heap --locked -- --iterations 20 | tee /tmp/kcl-memory-arena.csv
```

CSV columns:

```text
workload
iterations
elapsed_ms
elapsed_ms_per_iter
total_alloc_blocks
alloc_blocks_per_iter
total_alloc_bytes
alloc_bytes_per_iter
process_max_live_mb
end_live_mb
```

Use these columns for heap comparison:

```text
alloc_blocks_per_iter
alloc_bytes_per_iter
process_max_live_mb
end_live_mb
```

The `elapsed_ms_per_iter` column is useful as a rough sanity check, but use
Criterion for CPU conclusions.

## Suggested Comparison Flow

1. Run parity tests for both backends.
2. Run Criterion CPU benchmarks for `legacy`.
3. Run Criterion CPU benchmarks for `arena`.
4. Run DHAT heap profiling for `legacy`.
5. Run DHAT heap profiling for `arena`.
6. Compare workload-by-workload ratios:

```text
arena / legacy
```

Use ratios above `1.0` as regressions and below `1.0` as improvements.