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
1 change: 0 additions & 1 deletion quest/m2/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,6 @@ deletes the quests that follow it.
- [Drop in the TypeScript translator](/quest/m2/ts-drop.md) - a `Drop` type's `drop()` runs where Rust drops it
- [Async in the TypeScript translator](/quest/m2/ts-async.md) - async code translates with Rust's lazy futures
- [Shared ownership](/quest/m2/ts-shared.md) - `Arc`/`Rc`/`Weak` keep exact counts, and locks and atomics become plain values
- [Iterators](/quest/m2/ts-iter.md) - lazy `rt.ts` adaptors with a `DONE` protocol
- [Collections](/quest/m2/ts-collections.md) - maps, sets, and queues keep Rust's key semantics
- [Source order](/quest/m2/ts-source-order.md) - each module's items come out in Rust source order
- [Translate moq-net's model to TypeScript](/quest/m2/ts-model.md) - the driver grows from moq-net's codec to its model, for moq to compare against WASM
Expand Down
4 changes: 3 additions & 1 deletion quest/m2/ts-collections.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,10 +19,12 @@ by the translated `Ord`, and `VecDeque` a ring buffer.
- Which keys are primitive depends on the
[wide-integer representation](/quest/m2/ts-wide-ints.md): a hi/lo `u64` is
not one.
- Each collection's iterators (`iter`, `values`, `range`, `drain`) are `rt.Iter`s,
as `rt/iter.ts` makes std's, so the adaptors over them already translate. moq-net's
`BTreeMap::range` takes `RangeFrom` and `RangeTo`, which are not values yet.

Public API: the translator's output for collections.

## Required

- [Wide integer spike](/quest/m2/ts-wide-ints.md) - which keys lower to primitives
- [Iterators in the TypeScript translator](/quest/m2/ts-iter.md) - collections iterate through the same protocol
28 changes: 0 additions & 28 deletions quest/m2/ts-iter.md

This file was deleted.

1 change: 0 additions & 1 deletion quest/m2/ts-model.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,5 +35,4 @@ Public API: the translator's output for moq-net's model.
- [Drop in the TypeScript translator](/quest/m2/ts-drop.md) - kio closes a channel when its last producer drops
- [Async in the TypeScript translator](/quest/m2/ts-async.md) - kio's producers and consumers are futures
- [Shared ownership](/quest/m2/ts-shared.md) - kio's waiters are `Arc`/`Weak` with observable counts
- [Iterators](/quest/m2/ts-iter.md) - the model's adaptor chains
- [Collections](/quest/m2/ts-collections.md) - the model's maps and queues
37 changes: 28 additions & 9 deletions ts/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -46,7 +46,7 @@ it finds; translation still fails on any refusal.

Each Rust module with translated items becomes a file (`lib.ts`, `coding/varint.ts`),
with a `.ts.map` source map into the Rust it came from. `rt.ts` beside them is the
runtime: what std does that JS does not.
runtime: what std does that JS does not, with iterators in `rt/iter.ts`.

| Rust | TypeScript |
| --- | --- |
Expand All @@ -60,6 +60,8 @@ runtime: what std does that JS does not.
| `Result<T, E>` | `rt.Result<T, E>`: `{ ok: true, value }` or `{ ok: false, error }` |
| tuple, `[T; N]`, `&[T]`, `Vec<T>` | an array, `Uint8Array` for bytes, `rt.ByteVec` for `Vec<u8>` |
| `&T`, `&mut T`, `Box<T>` | the value: a `&mut` must point at an object JS can change in place |
| an iterator | `rt.Iter<Item>`, whose adaptors are its methods: `v.iter().map(f)` |
| `a..b`, `a..=b` | `rt.Range<T>`, `rt.RangeInclusive<T>`, which are iterators too |
| closure | an arrow function |
| constant | its value, inlined as Rust inlines it |

Expand All @@ -79,6 +81,15 @@ prints it. A caller prints a `printable` type as `to_string()` and `format!("{er
would: `rt.fmt.toString((f) => DecodeError.fmt$Display(err, f))` and
`rt.fmt.format([(f) => DecodeError.fmt$Debug(err, f)])`.

An iterator's `next()` returns its next item or `rt.DONE`, never `undefined`, so an
iterator of `Option` keeps each `None` apart from its end. std's adaptors and consumers
are `rt.Iter` methods, lazy and short-circuiting as std's are, and call their closures in
the same order and as often. A `for` loop reads an iterator by that protocol, a slice,
array, `Vec`, or `slice.iter()` with `for ... of`, and a range written in place with a
counter. The crate's own `impl Iterator` returns `rt.DONE` from its `next` too, and joins
std's adaptors through `rt.iter.from`. A caller calls `next()` for one item, or iterates
an `rt.Iter` with `for ... of`.

Functions and members are camelCase. Functions are monomorphized: each instance is its
own function, and instances that share a name are suffixed by type, as in
`roundtripLite$Group` or `get$Wrap_Pair`. Types are translated once, generically, so a
Expand All @@ -101,6 +112,11 @@ Imports name the `.ts` file, which Node, Bun, and bundlers run as is. A `tsc` bu
- `Result` is a plain `{ ok, value } | { ok, error }` object rather than an exception, so
`?` and `match` keep Rust's control flow exactly. Making no `Ok` objects at all measured
no faster on `just ts bench`, in V8 or JavaScriptCore.
- Iterators are the runtime's lazy classes rather than generators or ES iterator
helpers: std's adaptors have no THIR to lower, ES helpers lack most of them
(`rev`, `zip`, `peekable`), and a `next` returning an item or `rt.DONE` allocates
nothing per item. `just ts bench` measures chains of `map`, `filter`, `any`, `skip`,
and `take` 1.4-8x faster than the same ES helpers in Node, Bun, and Chrome.
- Bodies lower from THIR, which keeps loops, `match`, and `?` shaped as written. It does
not say where values drop; [Drop](/quest/m2/ts-drop.md) decides how to get that from
MIR.
Expand All @@ -114,8 +130,10 @@ bind to hand-written TS through config ([model](/quest/m2/ts-model.md)).
## Not yet

These fail translation: floats, `char`, statics, `async`,
types that implement `Drop`, iterator adaptors (`for` over ranges, slices, arrays, and
`Vec` works), or-patterns that bind, other format specs (a precision, `+`, `{:b}`, `{:x?}`,
types that implement `Drop`, iterators of std's collections and the adaptors without a
mapping in `src/lower/iter.rs` (such as `cycle`, `unzip`, and `partition`), an own
`impl Iterator` with `next_back`, `len`, or another provided method of its own,
`while let` or `match` on the `next` of an iterator of `Option`, or-patterns that bind, other format specs (a precision, `+`, `{:b}`, `{:x?}`,
and widths from arguments), writing to a `String` with `write!`, a `move` closure
copying a mutable variable, `mem::swap`, `replace`, or `take` of a reference's whole
pointee, and std functions without a mapping in `src/lower/library.rs`.
Expand All @@ -137,9 +155,9 @@ built natively for wasm32 and run beside its translation on the same inputs by
- `codec` vendors moq-net's sync codec, which a harness outside the crate could not reach,
and writes its errors' `Display` and `Debug`.
- `lang` covers every integer width's arithmetic and casts, control flow, patterns,
`Copy` aggregates, formatting, and methods on generic types. Its differential test runs
through `caller.ts`, a hand-written caller that also prints a `printable` error nothing
translated prints.
`Copy` aggregates, formatting, methods on generic types, and iterators, with closures
that log what each adaptor reads. Its differential test runs through `caller.ts`, a
hand-written caller that also prints a `printable` error nothing translated prints.
- `reject` holds constructs outside the subset; its expected errors are `expected.txt`,
and its expected census is `census.md`.

Expand All @@ -150,9 +168,10 @@ nix develop .#bench --command just ts bench # report to target/bench/report.md
```

The codec fixture's `bench::run` holds the cases moq's own TypeScript benchmarks time
(`js/net/bench/varint.ts` and `lite-varint.ts`), at the pinned moq revision. Each runs
four ways: natively, as wasm32 at moq-wasm's size-optimized profile, as moq's
hand-written `js/net` (`bench/moq.ts`), and translated; every route's output must match
(`js/net/bench/varint.ts` and `lite-varint.ts`), at the pinned moq revision, and
iterator chains over bytes. Each runs four ways: natively, as wasm32 at moq-wasm's
size-optimized profile, hand-written (moq's `js/net` in `bench/moq.ts`, and ES iterator
helpers in `bench/iter.ts`), and translated; every route's output must match
native Rust's first. The JS routes run in Node, Bun, and Chrome, with the WASM route's
copies across the boundary timed apart from its compute, and an A/A copy of the
translation to show the noise. The report records the host and engine versions, and
Expand Down
52 changes: 52 additions & 0 deletions ts/bench/iter.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,52 @@
// The iterator workloads' hand-written route: each chain in the codec fixture's
// `bench.rs` op 6, written with ES iterator helpers (`Iterator.prototype.map` and the
// rest), as TypeScript would write it without the translation's `rt.Iter`. Helpers
// without an ES counterpart, `enumerate` here, are a `for ... of` with a counter.

/** Run one chain, as `bench::run`'s op 6 does, over `data`. */
export function iterate(chain: number, data: Uint8Array): Uint8Array {
switch (chain) {
case 0:
return u64(
data
.values()
.map((b) => b >> 1)
.filter((b) => (b & 1) === 0)
.reduce((n) => n + 1, 0),
);
case 1:
return Uint8Array.of(data.values().some((b) => b === 0xff) ? 1 : 0);
case 2:
return u64(
data
.values()
.filter((b) => (b & 1) === 1)
.toArray().length,
);
case 3:
return u64(data.values().reduce((sum, b) => sum + b, 0));
case 4:
return u64(
data
.values()
.drop(16)
.take(512)
.reduce((acc, b) => acc ^ b, 0),
);
default: {
let last = 0;
let i = 0;
for (const b of data.values()) {
if (b === 0x80) last = i;
i++;
}
return u64(last);
}
}
}

function u64(value: number): Uint8Array {
const out = new Uint8Array(8);
new DataView(out.buffer).setBigUint64(0, BigInt(value));
return out;
}
7 changes: 4 additions & 3 deletions ts/bench/main.ts
Original file line number Diff line number Diff line change
Expand Up @@ -193,13 +193,14 @@ function render(): string {
`- moq: ${text(["git", "-C", checkout, "rev-parse", "HEAD"])}`,
...engines.map((e) => `- ${e.engine}`),
"",
"Each cell is nanoseconds per item (a varint, a frame header, or a message): the median",
"Each cell is nanoseconds per item (a varint, a frame header, a message, or a byte iterated): the median",
`of ${rounds} samples of at least ${sampleMs} ms, ± half their interquartile range. Each round interleaves`,
"every route and workload. `native` is a release build on the host. `wasm` is the same",
"Rust at moq-wasm's size-optimized profile, run with its input already in memory;",
"copying the input in and the output out are timed apart. `hand-written` is moq's",
"`js/net`, called as its own benchmarks call it. `A/A` is the translation loaded a",
"second time: its gap from `translated` is the noise.",
"`js/net`, called as its own benchmarks call it, and for `iter/` the same chain with ES",
"iterator helpers (`bench/iter.ts`). `A/A` is the translation loaded a second time: its",
"gap from `translated` is the noise.",
"",
"## Bundle size",
"",
Expand Down
4 changes: 4 additions & 0 deletions ts/bench/moq.ts
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,8 @@ import { Version as Lite } from "moq/js/net/src/lite/version.ts";
import { Cursor, Reader, Writer } from "moq/js/net/src/stream.ts";
import * as Varint from "moq/js/net/src/varint.ts";

import { iterate } from "./iter.ts";

type Version = (typeof Lite)[keyof typeof Lite];

// bench.rs reads a selector through the harness's `form` and `lite_version`; these are the
Expand Down Expand Up @@ -41,6 +43,8 @@ export function run(input: Uint8Array): Uint8Array | Promise<Uint8Array> {
return encodeGroup(data, lite(selector));
case 5:
return decodeGroup(data, lite(selector));
case 6:
return iterate(selector, data);
default:
throw new Error(`unknown workload ${op}`);
}
Expand Down
14 changes: 11 additions & 3 deletions ts/bench/workloads.ts
Original file line number Diff line number Diff line change
Expand Up @@ -3,10 +3,10 @@
// reads what its encode wrote.

export interface Workload {
/** What is coded, such as `varint/quic/2B` or `frames/video/lite-07`. */
/** What is coded, such as `varint/quic/2B` or `frames/video/lite-07`, or iterated. */
name: string;
op: "encode" | "decode";
/** Varints, frame headers, or messages per call, which each time is divided by. */
op: "encode" | "decode" | "iterate";
/** Varints, frame headers, messages, or items per call, which each time is divided by. */
items: number;
input: Uint8Array;
}
Expand Down Expand Up @@ -44,6 +44,14 @@ export function workloads(encode: (input: Uint8Array) => Uint8Array): Workload[]
pair(`frames/audio/${version}`, 50, 2, selector, [50n, 20_000n, 160n, 160n, 0n, 0n]);
pair(`group/${version}`, 1, 4, selector, [3n, 1_234n]);
}

// Iterator chains over bytes, as `bench.rs`'s op 6 picks them by selector; no byte is
// 0xff, so `any` reads them all.
const bytes = Uint8Array.from({ length: 1024 }, (_, i) => (i * 167 + 13) % 255);
const chains = ["map-filter-count", "any", "filter-collect", "sum", "skip-take-fold", "enumerate-for"];
chains.forEach((chain, selector) => {
out.push({ name: `iter/${chain}`, op: "iterate", items: bytes.length, input: Uint8Array.of(6, selector, ...bytes) });
});
return out;
}

Expand Down
54 changes: 54 additions & 0 deletions ts/fixtures/codec/expected/bench.ts
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,8 @@ export function run(input: Uint8Array): rt.ByteVec {
decoded(decodeFrames(data2, liteVersion(selector), out), out);
} else if (op === 4) {
encoded(encodeGroup(data2, liteVersion(selector), out), out);
} else if (op === 6) {
iterate(selector, data2, out);
} else {
decoded(decodeGroup(data2, liteVersion(selector), out), out);
}
Expand Down Expand Up @@ -161,6 +163,58 @@ export function encodeGroup(data: Uint8Array, version: Version, out: rt.ByteVec)
return group.encode(Encoder.new(out, Form.from(version)), version);
}

/**
* One iterator chain over every byte, picked by `chain`, with closures that cost little
* next to the iterator protocol they run through.
*/
export function iterate(chain: number, data: Uint8Array, out: rt.ByteVec): void {
if (chain === 0) {
putUsize(out, rt.iter.slice(data).map((arg: number): number => {
const b = arg;
return b >> 1;
}).filter((arg2: number): boolean => {
const b2 = arg2;
return (b2 & 1) === 0;
}).count());
} else if (chain === 1) {
out.push(rt.iter.slice(data).any((arg3: number): boolean => {
const b3 = arg3;
return b3 === 0xff;
}) ? 1 : 0);
} else if (chain === 2) {
const odd = rt.iter.slice(data).filter((arg4: number): boolean => {
const b4 = arg4;
return (b4 & 1) === 1;
}).toByteVec();
putUsize(out, odd.length);
} else if (chain === 3) {
putU64(out, BigInt(rt.iter.slice(data).map((arg5: number): number => {
const b5 = arg5;
return b5;
}).sum(rt.u32.add, 0)));
} else if (chain === 4) {
putU64(out, BigInt(rt.iter.slice(data).skip(16).take(512).fold(0, (acc: number, arg6: number): number => {
const b6 = arg6;
return (acc ^ b6) >>> 0;
})));
} else {
let last: number = 0;
const iter = rt.iter.slice(data).enumerate();
while (true) {
const item = iter.next();
if (item === rt.DONE) {
break;
}
const i = item[0];
const b7 = item[1];
if (b7 === 0x80) {
last = i;
}
}
putUsize(out, last);
}
}

export function decodeGroup(wire: Uint8Array, version: Version, out: rt.ByteVec): rt.Result<undefined, DecodeError> {
const decodeSlice = Group.decodeSlice(wire, version);
if (!decodeSlice.ok) {
Expand Down
31 changes: 30 additions & 1 deletion ts/fixtures/codec/src/bench.rs
Original file line number Diff line number Diff line change
@@ -1,7 +1,8 @@
//! The workloads `just ts bench` times on every route, shaped like moq's own TypeScript
//! benchmarks: `js/net/bench/varint.ts` and `lite-varint.ts`. The first input byte picks
//! the workload and the second its wire format; an encode's output is the matching
//! decode's input.
//! decode's input. Op 6 runs iterator chains over its bytes instead, as moq-net's model
//! writes them.

use crate::coding::{Decode, DecodeError, Decoder, Encode, EncodeError, Encoder, Form, varint};
use crate::harness::{decode_error, encode_error, form, lite_version, put_u64, put_usize, take_u64};
Expand All @@ -23,6 +24,7 @@ pub fn run(input: &[u8]) -> Vec<u8> {
2 => encoded(encode_frames(data, lite_version(selector), &mut out), &mut out),
3 => decoded(decode_frames(data, lite_version(selector), &mut out), &mut out),
4 => encoded(encode_group(data, lite_version(selector), &mut out), &mut out),
6 => iterate(selector, data, &mut out),
_ => decoded(decode_group(data, lite_version(selector), &mut out), &mut out),
}
out
Expand Down Expand Up @@ -120,6 +122,33 @@ fn encode_group(data: &[u8], version: lite::Version, out: &mut Vec<u8>) -> Resul
group.encode(&mut Encoder::new(out, version.into()), version)
}

/// One iterator chain over every byte, picked by `chain`, with closures that cost little
/// next to the iterator protocol they run through.
fn iterate(chain: u8, data: &[u8], out: &mut Vec<u8>) {
match chain {
0 => put_usize(out, data.iter().map(|&b| b >> 1).filter(|&b| b & 1 == 0).count()),
1 => out.push(data.iter().any(|&b| b == 0xff) as u8),
2 => {
let odd: Vec<u8> = data.iter().copied().filter(|&b| b & 1 == 1).collect();
put_usize(out, odd.len());
}
3 => put_u64(out, data.iter().map(|&b| b as u32).sum::<u32>() as u64),
4 => put_u64(
out,
data.iter().skip(16).take(512).fold(0u32, |acc, &b| acc ^ b as u32) as u64,
),
_ => {
let mut last = 0;
for (i, &b) in data.iter().enumerate() {
if b == 0x80 {
last = i;
}
}
put_usize(out, last);
}
}
}

fn decode_group(wire: &[u8], version: lite::Version, out: &mut Vec<u8>) -> Result<(), DecodeError> {
let (group, used) = lite::Group::decode_slice(wire, version)?;
put_u64(out, group.subscribe);
Expand Down
Loading