Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 23 additions & 10 deletions bench/ffi/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -522,13 +522,13 @@ From the CPU tables of 2026-11-10, measured at rust2 `7383790d` at a load averag
29 and since replaced by the tables above, read against the code each call runs. In order of what it costs moq's
frame path:

1. **A call per frame timestamp.** At moq `ffcb7cd9`, `Timestamp` was `Copy` with private
fields, so it crossed as its 16 bytes, and a stamped frame allocated and freed nothing in
Rust; at `1aa86d5e6` it is a handle again until
[niche values](/quest/m1/ffi-export/niche-values.md) lands. As a handle, it cost 21 ns
in C, 27 in Swift, 140 in Python, 250 in Kotlin, 260 in Go, and 245 in Dart (stamped
write minus write, in the tables above); as a value, see [Copy values](#copy-values):
what remains is each language's call and, in Kotlin and Python, an object of its own.
1. **A call per frame timestamp.** `Timestamp` is `Copy` with private fields, so it
crosses as its 16 bytes, and a stamped frame allocates and frees nothing in Rust. As a
handle, at moq `1aa86d5e6` before its `Option<Timescale>` field crossed by value, it
cost 21 ns in C, 27 in Swift, 140 in Python, 250 in Kotlin, 260 in Go, and 245 in Dart
(stamped write minus write, in the tables above); as a value, see
[Copy values](#copy-values): what remains is each language's call and, in Kotlin and
Python, an object of its own.
2. **Ownership of a returned object.** An object return costs C 25 ns, but Go 263 and
Dart 242, ten times C, and most of the difference is each runtime's per-object
registration with its collector. Profiled 2026-11-14 on **nixos** with `perf`, for an
Expand Down Expand Up @@ -655,9 +655,9 @@ measure them at the load beside them.
### Copy values

A `Copy` type with private fields whose every value fills its bytes crosses by value, as
`Timestamp` did at moq `ffcb7cd9`: a struct of its bytes in C, C++, Swift, Go, and Dart, a
class of a `Long` per word in Kotlin (a word value class when it fits one), and a class of
the runtime's `Value` holding its bytes in Python.
`Timestamp` does, its `None` scale written as its niche's whole `u64`: a struct of its bytes
in C, C++, Swift, Go, and Dart, a class of a `Long` per word in Kotlin (a word value class
when it fits one), and a class of the runtime's `Value` holding its bytes in Python.
Measured 2026-11-13 at rust2 `7766768f`, moq `ffcb7cd9`, on an AMD Ryzen 9 9950X (32 threads),
Linux, at a load average of 13 to 15, the median of 3 rounds, in CPU time:

Expand All @@ -681,6 +681,19 @@ in the tables above came from another load, so Python's was also measured agains
build on the same host, interleaved over 5 rounds at a load of 10 to 12: stamped minus write
fell from 205 ns to 166, and the stamped write from 441 to 391.

At moq `1aa86d5e6`, `Timestamp` gained an `Option<Timescale>` and crossed as a handle until
the exporter counted a `None` as the niche it writes. Measured 2026-11-19 on **fedora**, the
same CPU, at a load average of 17 to 24, the median of 3 rounds of `just ffi bench` each, in
CPU time, stamped minus write:

| | C | C++ | Swift | Go | Dart | Kotlin | Python | TS (Node) |
|---|---|---|---|---|---|---|---|---|
| handle, main at `2f63f110` | 40 | 30 | 56 | 149 | 111 | 210 | 218 | 283 |
| value | 20 | 10 | 7 | 58 | 36 | 220 | 138 | 138 |

Rust's own `from_micros` takes 8 to 9 ns of each, against none at `ffcb7cd9`. Kotlin's CPU
time, which counts its JIT and collector, moved within its noise.

### Against the targets

Where the cases match, on wall time: Kotlin's getter costs 24 ns against BoltFFI's 5.8,
Expand Down
16 changes: 9 additions & 7 deletions ffi/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -348,13 +348,15 @@ Linux's exports, as the merge queue runs on, since a header names its targets.
included, as a `<T> *` Rust writes what the call left back through, so only that copy
changes; it never makes or reads one itself, and frees none. Its fields fill it under
any order a `rustc` may give them, with a byte for an enum's tag where no field has a
niche to hold it, so it has no padding whichever `rustc` builds the glue, which asserts
each target's size. They must also fill a model layout at both 4- and 8-byte pointers,
each primitive aligned to its size and a `repr`'s field order kept, so every target
decides alike. Any other `Copy` type, such as std's `Instant`, padded on a 64-bit
target, or an `Option<u32>`, whose bytes depend on its value, is an object instead, so
no byte Rust leaves uninitialized reaches a language, which may serialize what it
holds. Its size and alignment are the largest of the export's targets, so one
niche to hold it, and a variant without data in another's niche counted as that niche's
whole scalar, which it writes, so it has no padding whichever `rustc` builds the glue,
which asserts each target's size: `None` of an `Option<NonZero<u64>>` fills its 8 bytes.
They must also fill a model layout at both 4- and 8-byte pointers, each primitive
aligned to its size and a `repr`'s field order kept, so every target decides alike. Any
other `Copy` type, such as std's `Instant`, padded on a 64-bit target, or an
`Option<u32>` or `Option<&[u8]>`, whose `None` leaves bytes uninitialized, is an object
instead, so no byte Rust leaves uninitialized reaches a language, which may serialize
what it holds. Its size and alignment are the largest of the export's targets, so one
header serves them all, a few bytes past a 32-bit target's own. A change of size is an
ABI change, as a record's field change is.
- **In and out**: a `&mut` of a value is two parameters, the value passed in as one taken
Expand Down
23 changes: 23 additions & 0 deletions ffi/fixtures/api/src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -1940,6 +1940,29 @@ impl Berth {
}
}

/// A count at a scale that may be absent: `Copy` with private fields, whose `None` writes
/// its niche's whole `u64`, so a value whatever it holds.
#[derive(Clone, Copy, Debug, PartialEq)]
pub struct Rated {
count: u64,
scale: Option<NonZero<u64>>,
}

impl Rated {
/// `count` at `scale` a second, or unscaled at a scale of zero.
pub fn new(count: u64, scale: u64) -> Self {
Self {
count,
scale: NonZero::new(scale),
}
}

/// Its scale, or zero when unscaled.
pub fn scale(&self) -> u64 {
self.scale.map_or(0, NonZero::get)
}
}

/// A running count, as moq's `stats::Traffic`: `Copy` with private fields, changed in place
/// through `&mut self`, so a value whose every copy changes alone.
#[derive(Clone, Copy, Debug)]
Expand Down
34 changes: 12 additions & 22 deletions ffi/moq/bench/export.c
Original file line number Diff line number Diff line change
Expand Up @@ -98,9 +98,9 @@ static moq_frame_Frame *read_frame(moq_group_Consumer *reader) {
return read;
}

/* A new timestamp `micros` microseconds in, to free. */
static moq_Timestamp *stamp(uint64_t micros) {
moq_Timestamp *at = NULL;
/* A timestamp `micros` microseconds in. */
static moq_Timestamp stamp(uint64_t micros) {
moq_Timestamp at;
moq_TimeOverflow overflow;
if (!moq_Timestamp_from_micros(micros, &at, &overflow)) {
fail("from_micros");
Expand All @@ -109,7 +109,7 @@ static moq_Timestamp *stamp(uint64_t micros) {
}

/* A group keyed by its start, which must exceed every earlier group's on the track. */
static moq_group_Producer *append_group(moq_track_Producer *track, const moq_Timestamp *start) {
static moq_group_Producer *append_group(moq_track_Producer *track, moq_Timestamp start) {
moq_group_Producer *group = NULL;
moq_Error *err = NULL;
if (!moq_track_Producer_append_group(track, start, &group, &err, NULL)) {
Expand All @@ -118,7 +118,7 @@ static moq_group_Producer *append_group(moq_track_Producer *track, const moq_Tim
return group;
}

static void write_frame(moq_group_Producer *group, const moq_Timestamp *at, moq_buf frame) {
static void write_frame(moq_group_Producer *group, moq_Timestamp at, moq_buf frame) {
moq_Error *err = NULL;
if (!moq_group_Producer_write_frame(group, at, frame, &err, NULL)) {
fail("write_frame");
Expand Down Expand Up @@ -147,7 +147,7 @@ static span throughput(moq_track_Producer *track, moq_track_Subscriber *subscrib
snprintf(name, sizeof name, "throughput[%zu]", size);
span start = begin();
for (size_t g = 0; g < groups; g++) {
moq_Timestamp *at = stamp((*micros)++);
moq_Timestamp at = stamp((*micros)++);
moq_group_Producer *group = append_group(track, at);
moq_group_Consumer *reader = recv_group(subscriber);
for (int f = 0; f < FRAMES; f++) {
Expand All @@ -159,7 +159,6 @@ static span throughput(moq_track_Producer *track, moq_track_Subscriber *subscrib
moq_frame_Frame_free(read);
}
finish(group);
moq_Timestamp_free(at);
moq_group_Consumer_free(reader);
}
span ns = end(start, (double)(groups * FRAMES * size), name);
Expand Down Expand Up @@ -254,9 +253,7 @@ static void round_(int print) {

/* Groups start where the frames before them left off, as moq's own bench keys them. */
uint64_t micros = 0;
moq_Timestamp *demanded_at = stamp(micros++);
moq_group_Producer *demanded = append_group(track, demanded_at);
moq_Timestamp_free(demanded_at);
moq_group_Producer *demanded = append_group(track, stamp(micros++));
moq_group_Demand *demand = moq_group_Producer_demand(demanded, NULL);
start = begin();
for (int i = 0; i < N; i++) {
Expand Down Expand Up @@ -313,13 +310,9 @@ static void round_(int print) {
* group started at its first frame's. */
start = begin();
for (int g = 0; g < GROUPS; g++) {
moq_Timestamp *first = stamp(micros);
moq_group_Producer *group = append_group(track, first);
moq_Timestamp_free(first);
moq_group_Producer *group = append_group(track, stamp(micros));
for (int f = 0; f < FRAMES; f++) {
moq_Timestamp *at = stamp(micros++);
write_frame(group, at, frame);
moq_Timestamp_free(at);
write_frame(group, stamp(micros++), frame);
}
finish(group);
}
Expand All @@ -328,13 +321,12 @@ static void round_(int print) {
/* Every frame at its group's start, converted once per group. */
start = begin();
for (int g = 0; g < GROUPS; g++) {
moq_Timestamp *at = stamp(micros++);
moq_Timestamp at = stamp(micros++);
moq_group_Producer *group = append_group(track, at);
for (int f = 0; f < FRAMES; f++) {
write_frame(group, at, frame);
}
finish(group);
moq_Timestamp_free(at);
}
span write = end(start, N, "write");

Expand All @@ -351,7 +343,7 @@ static void round_(int print) {
moq_frame_Frame *last = NULL;
start = begin();
for (int g = 0; g < GROUPS; g++) {
moq_Timestamp *at = stamp(micros++);
moq_Timestamp at = stamp(micros++);
moq_group_Producer *group = append_group(track, at);
moq_group_Consumer *reader = recv_group(subscriber);
for (int f = 0; f < FRAMES; f++) {
Expand All @@ -362,15 +354,14 @@ static void round_(int print) {
last = read_frame(reader);
}
finish(group);
moq_Timestamp_free(at);
moq_group_Consumer_free(reader);
}
span ready = end(start, N, "ready");

/* Each read polled before its frame is written, so it pends, then polled again. */
start = begin();
for (int g = 0; g < GROUPS; g++) {
moq_Timestamp *at = stamp(micros++);
moq_Timestamp at = stamp(micros++);
moq_group_Producer *group = append_group(track, at);
moq_group_Consumer *reader = recv_group(subscriber);
for (int f = 0; f < FRAMES; f++) {
Expand All @@ -387,7 +378,6 @@ static void round_(int print) {
moq_frame_Frame_free(read);
}
finish(group);
moq_Timestamp_free(at);
moq_group_Consumer_free(reader);
}
span woken = end(start, N, "woken");
Expand Down
17 changes: 3 additions & 14 deletions ffi/moq/bench/export.dart
Original file line number Diff line number Diff line change
Expand Up @@ -117,7 +117,6 @@ Future<Span> throughput(moq.TrackProducer track, moq.TrackSubscriber subscriber,
reader.close();
group.finish().close();
group.close();
at.close();
}
final ns = end(start, name, count * frames * size);
return Span(1e3 / ns.wall, 1e3 / ns.cpu);
Expand All @@ -136,9 +135,7 @@ Future<Map<String, Span>> round() async {
}
out['call'] = end(start, 'call');

final demandedAt = groupStart();
final demanded = track.appendGroup(demandedAt);
demandedAt.close();
final demanded = track.appendGroup(groupStart());
final demand = demanded.demand();
start = begin();
for (var i = 0; i < n; i++) {
Expand Down Expand Up @@ -190,13 +187,9 @@ Future<Map<String, Span>> round() async {
// Each frame stamped through a fresh timestamp, as a caller holding an int must.
start = begin();
for (var g = 0; g < groups; g++) {
final first = moq.Timestamp.fromMicros(moq.U64(micros));
final group = track.appendGroup(first);
first.close();
final group = track.appendGroup(moq.Timestamp.fromMicros(moq.U64(micros)));
for (var f = 0; f < frames; f++) {
final at = moq.Timestamp.fromMicros(moq.U64(micros++));
group.writeFrame(at, frame);
at.close();
group.writeFrame(moq.Timestamp.fromMicros(moq.U64(micros++)), frame);
}
group.finish().close();
group.close();
Expand All @@ -212,7 +205,6 @@ Future<Map<String, Span>> round() async {
}
group.finish().close();
group.close();
at.close();
}
out['write'] = end(start, 'write');

Expand All @@ -236,7 +228,6 @@ Future<Map<String, Span>> round() async {
reader.close();
group.finish().close();
group.close();
at.close();
}
out['ready'] = end(start, 'ready');

Expand All @@ -255,7 +246,6 @@ Future<Map<String, Span>> round() async {
reader.close();
group.finish().close();
group.close();
at.close();
}
out['woken'] = end(start, 'woken');

Expand All @@ -274,7 +264,6 @@ Future<Map<String, Span>> round() async {
if (!await next.moveNext()) throw StateError('missing group acknowledgement');
group.finish().close();
group.close();
at.close();
}
await next.cancel();
}
Expand Down
17 changes: 3 additions & 14 deletions ffi/moq/bench/export.go
Original file line number Diff line number Diff line change
Expand Up @@ -113,7 +113,6 @@ func throughput(ctx context.Context, track *net.TrackProducer, subscriber *net.T
}
reader.Close()
must(group.Finish()).Close()
at.Close()
}
ns := end(start, name, count*frames*size)
return span{1e3 / ns.wall, 1e3 / ns.cpu}
Expand Down Expand Up @@ -188,10 +187,8 @@ func round(measured bool) []result {
// Groups are keyed by their start, which must rise, so each starts at the next of
// micros, the time its frames are stamped at.
var micros uint64
demandedAt := must(net.TimestampFromMicros(micros))
demanded := must(track.AppendGroup(must(net.TimestampFromMicros(micros))))
micros++
demanded := must(track.AppendGroup(demandedAt))
demandedAt.Close()
demand := must(demanded.Demand())
start = begin()
for range n {
Expand Down Expand Up @@ -253,14 +250,10 @@ func round(measured bool) []result {
// Each frame stamped through a fresh timestamp, as a caller holding a u64 must.
start = begin()
for range groups {
groupAt := must(net.TimestampFromMicros(micros))
group := must(track.AppendGroup(groupAt))
groupAt.Close()
group := must(track.AppendGroup(must(net.TimestampFromMicros(micros))))
for range frames {
at := must(net.TimestampFromMicros(micros))
check(group.WriteFrame(must(net.TimestampFromMicros(micros)), frame))
micros++
check(group.WriteFrame(at, frame))
at.Close()
}
must(group.Finish()).Close()
}
Expand All @@ -275,7 +268,6 @@ func round(measured bool) []result {
check(group.WriteFrame(at, frame))
}
must(group.Finish()).Close()
at.Close()
}
out = append(out, result{"write", end(start, "write", n)})

Expand All @@ -302,7 +294,6 @@ func round(measured bool) []result {
}
reader.Close()
must(group.Finish()).Close()
at.Close()
}
out = append(out, result{"ready", end(start, "ready", n)})

Expand All @@ -323,7 +314,6 @@ func round(measured bool) []result {
}
reader.Close()
must(group.Finish()).Close()
at.Close()
}
out = append(out, result{"woken", end(start, "woken", n)})

Expand All @@ -345,7 +335,6 @@ func round(measured bool) []result {
}
<-permits // Keep this group until its reader has consumed every frame.
must(group.Finish()).Close()
at.Close()
}
}()
for range groups {
Expand Down
Loading