ubq 7.0.0

Lock-free unbounded MPMC queue with no_std + alloc support.
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
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151

# BSC-CNS Presentation Runbook

This runbook is for previewing UBQ results locally or on `hebrides`, then
running the publication-quality benchmark suite on the BSC-CNS machine.

## Current Preview Results

I ran a bounded local preview on this machine with:

```bash
cargo run --release --features bench_registry,bench_rbbq,bench_lfqueue --bin bench_matrix -- \
  --machine-label local-preview \
  --runs-dir bench_results/presentation_runs \
  --queues ubq,segqueue,concurrent-queue,rbbq,lfqueue \
  --ubq-label balanced,1,page,crossbeam \
  --fastfifo-block-sizes 64,256,1024,4096 \
  --lfqueue-segment-sizes 1024 \
  --scenarios 1p4c,4p4c,16p16c,64p64c \
  --modes throughput \
  --items-per-producer 100000 \
  --repeats 1 \
  --parallelism 128 \
  --reuse-existing
```

The runner only reported one hardware thread through
`std::thread::available_parallelism()`, so this is a sanity check rather than a
paper result. The command uses `--parallelism 128` to allow the selected
multi-threaded scenarios to run.

| scenario | UBQ ops/sec | best non-UBQ | best non-UBQ ops/sec | UBQ speedup |
| --- | ---: | --- | ---: | ---: |
| 1p4c | 5,905,583 | concurrent-queue | 5,179,422 | 1.14x |
| 4p4c | 11,475,306 | concurrent-queue | 14,997,747 | 0.77x |
| 16p16c | 4,298,067 | crossbeam SegQueue | 6,819,665 | 0.63x |
| 64p64c | 15,700,386 | crossbeam SegQueue | 25,958,356 | 0.60x |

Interpretation: this fixed preview is enough to show the queue comparison shape,
but it is only a local sanity check. Use the BSC run below for real claims.

I also attempted:

```bash
ssh hebrides hostname
```

from this environment, but DNS resolution failed:

```text
ssh: Could not resolve hostname hebrides: Temporary failure in name resolution
```

Run the hebrides preview from a networked shell where that host resolves.

## Preview Run On Local Or Hebrides

Run the preview directly on the target machine:

```bash
cargo run --release --features bench_registry,bench_rbbq,bench_lfqueue --bin bench_grid -- \
  --machine-label local-preview \
  --runs-dir bench_results/presentation_runs \
  --queues ubq,segqueue,concurrent-queue,rbbq,lfqueue \
  --scenarios 1p4c,4p4c,16p16c,64p64c \
  --modes throughput \
  --items-per-producer 100000 \
  --repeats 1 \
  --parallelism=<hardware-thread-count>
```

Use a machine-specific label such as `hebrides-preview` when running the same
command after logging into another host.

Preview output locations:

- `bench_results/presentation_runs`
- `bench_results/presentation_plots`

## Real BSC-CNS Run

On the BSC-CNS machine, clone or update this repository, then run:

```bash
cargo run --release --features bench_registry,bench_rbbq,bench_lfqueue,bench_wcq --bin bench_grid -- \
  --machine-label bsc-cns \
  --queues ubq,segqueue,concurrent-queue,rbbq,lfqueue,wcq \
  --modes throughput,complex_throughput,data_latency,fairness \
  --repeats 3 \
  --parallelism=<hardware-thread-count>
```

This uses:

- every feasible power-of-two producer/consumer pair for the detected thread
  count,
- `throughput`, `complex_throughput`, `data_latency`, and `fairness`,
- both UBQ backoff policies at page-derived block capacity, including scalar
  and all configured `push_batch` sizes for throughput,
- SegQueue, concurrent-queue, RBBQ/BBQ, LSCQ, and wCQ baselines,
- three repeats for the paper run.

If the full run is too long, use the explicit preview command above with
`--machine-label bsc-cns-preview`.

## Paper Figures From BSC-CNS Results

First render the standard plots, then generate paper-oriented advantage plots
from the BSC-CNS CSVs:

```bash
python3 scripts/plot_runs_folder.py \
  --runs-dir bench_results/runs \
  --out-dir bench_results/plots
```

```bash
python3 scripts/plot_paper_advantages.py \
  --results-dir bench_results/plots/bsc-cns/csv \
  --out-dir bench_results/plots/bsc-cns/paper
```

Recommended figures for a colleague presentation:

1. `throughput_speedup_heatmap.svg`: best UBQ variant versus best non-UBQ queue.
2. `throughput_scaling_lines.svg`: per-family throughput scaling.
3. `complex_high_contention_speedup_heatmap.svg`: high-contention robustness.
4. `data_latency_elapsed_speedup_distribution.svg`: operation-cost advantage.
5. `throughput_workload_class_summary.svg`: win rate and geomean by workload shape.
6. `fairness_throughput_pareto_64p64c.svg`: fairness/throughput supporting view.

## Application Targets To Discuss

The most favorable states from `grace_results` were:

- `1pNc` fan-out throughput: UBQ wins 6/6 scenarios, geomean 2.13x.
- balanced `NpNc` throughput: UBQ wins 6/6 scenarios, geomean 1.36x.
- high-MPMC throughput: UBQ wins 6/6 scenarios, geomean 1.42x.
- complex high-MPMC throughput: UBQ wins 5/6 scenarios, geomean 1.25x.
- data-latency operation cost: UBQ wins 45/49 push-elapsed scenarios and 39/49
  pop-elapsed scenarios.

Map those to:

- ingress-to-worker dispatch,
- runtime global task-injection queues,
- parallel graph/frontier worklists,
- small-message low-latency pipelines,
- unbounded FIFO burst buffers where bounded pre-sizing is operationally costly.

Do not lead with `Np1c` single-consumer throughput. That is not UBQ's strongest
state and should be framed as a caveat or avoided through sharding/batching.