deloxide 1.1.0

Deloxide scrubs your threads clean by detecting deadlocks in real time—keeping your system smooth, safe, and corrosion-free. 🦀🧼🔒
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

#!/usr/bin/env python3
"""Generate deterministic SVG charts from recorded documentation evidence."""

import argparse
import csv
import sys
from html import escape
from pathlib import Path


ROOT = Path(__file__).resolve().parents[1]
CHARTS = {
    ROOT / "docs/performance/results/2026-07-29-fast-path.csv": (
        ROOT / "docs/src/assets/mutex-latency.svg",
        "latency",
    ),
    ROOT / "docs/performance/results/2026-07-29-manifestation.csv": (
        ROOT / "docs/src/assets/manifestation-rate.svg",
        "manifestation",
    ),
}


def read_rows(path: Path) -> list[dict[str, str]]:
    with path.open(newline="", encoding="utf-8") as handle:
        return list(csv.DictReader(handle))


def bar_chart(
    title: str,
    description: str,
    values: list[tuple[str, float, str]],
) -> str:
    width = 960
    row_height = 42
    height = 100 + row_height * len(values)
    maximum = max(value for _, value, _ in values)
    bar_x = 430
    plot_width = 400
    rows = []
    for index, (label, value, display) in enumerate(values):
        y = 70 + index * row_height
        bar_width = 0 if maximum == 0 else value / maximum * plot_width
        rows.append(
            f'<text x="20" y="{y + 18}">{escape(label)}</text>'
            f'<rect x="{bar_x}" y="{y}" width="{bar_width:.2f}" height="24" '
            'fill="#e66a2c"/>'
            f'<text x="{bar_x + 10 + bar_width:.2f}" y="{y + 18}">'
            f'{escape(display)}</text>'
        )
    return (
        f'<svg xmlns="http://www.w3.org/2000/svg" width="{width}" '
        f'height="{height}" viewBox="0 0 {width} {height}">'
        f"<title>{escape(title)}</title>"
        f"<desc>{escape(description)}</desc>"
        f'<rect width="{width}" height="{height}" fill="#fff"/>'
        '<style>text{font:14px sans-serif;fill:#222}</style>'
        + "".join(rows)
        + "</svg>\n"
    )


def latency_svg(rows: list[dict[str, str]]) -> str:
    selected = [
        row
        for row in rows
        if row["case"] != "mutex/two_thread_handoff" and row["unit"] == "ns"
    ]
    values = [
        (
            f'{row["implementation"]}: {row["case"]}',
            float(row["median"]),
            f'{float(row["median"]):.2f} ns',
        )
        for row in selected
    ]
    return bar_chart(
        "Focused synchronization latency",
        "Median nanoseconds per uncontended operation; lower is better.",
        values,
    )


def manifestation_svg(rows: list[dict[str, str]]) -> str:
    values = [
        (
            f'{row["scenario"]}: {row["mode"]}',
            float(row["rate_percent"]),
            f'{float(row["rate_percent"]):.1f}%',
        )
        for row in rows
    ]
    return bar_chart(
        "Deadlock manifestation rate",
        "Share of runs producing an active wait-for cycle; higher means the "
        "schedule exposed the intended deadlock more often.",
        values,
    )


def render(kind: str, rows: list[dict[str, str]]) -> str:
    if kind == "latency":
        return latency_svg(rows)
    if kind == "manifestation":
        return manifestation_svg(rows)
    raise ValueError(f"unknown chart kind: {kind}")


def main() -> int:
    parser = argparse.ArgumentParser()
    parser.add_argument("--check", action="store_true")
    args = parser.parse_args()

    stale = []
    for input_path, (output_path, kind) in CHARTS.items():
        content = render(kind, read_rows(input_path))
        if args.check:
            if not output_path.exists() or output_path.read_text(encoding="utf-8") != content:
                stale.append(output_path)
        else:
            output_path.write_text(content, encoding="utf-8")
    for output_path in stale:
        print(output_path)
    return 1 if stale else 0


if __name__ == "__main__":
    sys.exit(main())