# rigtorp/hiccups architecture

> Architecture diagram of the GitHub repository rigtorp/hiccups, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rigtorp/hiccups
- Repository: https://github.com/rigtorp/hiccups

## Overview

hiccups is a Linux command-line utility that measures scheduling jitter for CPU-bound threads. The user supplies runtime, threshold, and sample-capacity options; the program discovers allowed CPUs, calibrates a default threshold when needed, pins workers, and records timestamp gaps above that threshold. After the workers finish, it sorts each CPU’s samples and prints counts and latency percentiles. The runtime is concentrated in one source file, so nodes describe its distinct stages rather than implying separate modules. All relationships below are visible in the excerpted implementation.

Main entry points: [`src/hiccups.cpp`](https://github.com/rigtorp/hiccups/blob/master/src/hiccups.cpp) (CPU discovery)

## Diagram (Mermaid)

```mermaid
flowchart TD

node_user(("User"))
node_cli["CLI options<br/>[hiccups.cpp]"]
node_cpu_discovery["CPU discovery<br/>[hiccups.cpp]"]
node_threshold["Threshold calibration<br/>[hiccups.cpp]"]
node_worker_setup["Worker setup<br/>[hiccups.cpp]"]
node_memory_lock["Memory locking<br/>[hiccups.cpp]"]
node_sampling["Jitter sampling<br/>[hiccups.cpp]"]
node_statistics["Statistics output<br/>[hiccups.cpp]"]
node_linux_kernel(("Linux kernel"))
node_stdout(("Standard output"))

node_user -->|"sets options"| node_cli
node_cli -->|"continues with options"| node_cpu_discovery
node_cpu_discovery -->|"queries affinity"| node_linux_kernel
node_cpu_discovery -->|"provides CPUs"| node_threshold
node_threshold -->|"sets threshold"| node_sampling
node_cpu_discovery -->|"provides CPUs"| node_worker_setup
node_worker_setup -->|"pins threads"| node_linux_kernel
node_worker_setup -->|"waits for workers"| node_memory_lock
node_memory_lock -->|"locks memory"| node_linux_kernel
node_memory_lock -->|"starts deadline"| node_sampling
node_worker_setup -->|"starts workers"| node_sampling
node_sampling -->|"provides samples"| node_statistics
node_statistics -->|"prints results"| node_stdout

click node_cli "https://github.com/rigtorp/hiccups/blob/master/src/hiccups.cpp"
click node_cpu_discovery "https://github.com/rigtorp/hiccups/blob/master/src/hiccups.cpp"
click node_threshold "https://github.com/rigtorp/hiccups/blob/master/src/hiccups.cpp"
click node_worker_setup "https://github.com/rigtorp/hiccups/blob/master/src/hiccups.cpp"
click node_memory_lock "https://github.com/rigtorp/hiccups/blob/master/src/hiccups.cpp"
click node_sampling "https://github.com/rigtorp/hiccups/blob/master/src/hiccups.cpp"
click node_statistics "https://github.com/rigtorp/hiccups/blob/master/src/hiccups.cpp"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_user toneBlue
class node_cli,node_cpu_discovery,node_threshold,node_memory_lock,node_sampling,node_statistics toneTeal
class node_worker_setup toneRose
class node_linux_kernel,node_stdout toneIndigo
```

## Components

### Other components

- **User**
- [CLI options](https://github.com/rigtorp/hiccups/blob/master/src/hiccups.cpp): `src/hiccups.cpp`
- [CPU discovery](https://github.com/rigtorp/hiccups/blob/master/src/hiccups.cpp): `src/hiccups.cpp`
- [Threshold calibration](https://github.com/rigtorp/hiccups/blob/master/src/hiccups.cpp): `src/hiccups.cpp`
- [Worker setup](https://github.com/rigtorp/hiccups/blob/master/src/hiccups.cpp): `src/hiccups.cpp`
- [Memory locking](https://github.com/rigtorp/hiccups/blob/master/src/hiccups.cpp): `src/hiccups.cpp`
- [Jitter sampling](https://github.com/rigtorp/hiccups/blob/master/src/hiccups.cpp): `src/hiccups.cpp`
- [Statistics output](https://github.com/rigtorp/hiccups/blob/master/src/hiccups.cpp): `src/hiccups.cpp`
- **Linux kernel**
- **Standard output**

## Connections

- User → CLI options: sets options (evidence: `src/hiccups.cpp`)
- CLI options → CPU discovery: continues with options (evidence: `src/hiccups.cpp`)
- CPU discovery → Linux kernel: queries affinity (evidence: `src/hiccups.cpp`)
- CPU discovery → Threshold calibration: provides CPUs (evidence: `src/hiccups.cpp`)
- Threshold calibration → Jitter sampling: sets threshold (evidence: `src/hiccups.cpp`)
- CPU discovery → Worker setup: provides CPUs (evidence: `src/hiccups.cpp`)
- Worker setup → Linux kernel: pins threads (evidence: `src/hiccups.cpp`)
- Worker setup → Memory locking: waits for workers (evidence: `src/hiccups.cpp`)
- Memory locking → Linux kernel: locks memory (evidence: `src/hiccups.cpp`)
- Memory locking → Jitter sampling: starts deadline (evidence: `src/hiccups.cpp`)
- Worker setup → Jitter sampling: starts workers (evidence: `src/hiccups.cpp`)
- Jitter sampling → Statistics output: provides samples (evidence: `src/hiccups.cpp`)
- Statistics output → Standard output: prints results (evidence: `src/hiccups.cpp`)