diff --git a/CHANGELOG.md b/CHANGELOG.md
index 76de5c4..99cc2d0 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,27 @@ and [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
### Added
+- The `seq/1` feature between two labstream peers (`docs/extensions.md`). A
+ labstream inlet offers it in the request header `Labstream-Features`, and
+ a labstream outlet answers it. liblsl ignores the header on both sides.
+ The outlet numbers its samples, and the inlet counts the samples that
+ never arrived: from a full outlet queue, and from a lost connection.
+- `Inlet::lost` in `labstream` and `Inlet::samples_lost` in `labstream-net`.
+ The value is `None` when the connection does not use `seq/1`.
+- The configuration key `labstream.Features`. The value `{}` turns every
+ labstream feature off.
+- `labstream_proto::features` and `labstream_proto::seq`, with
+ `FeedParams::to_wire_with`, `FeedClient::start_with`,
+ `FeedClient::features` and `Accepted::to_wire_with`.
+- `SampleQueue::with_first_number`, `SampleQueue::pop_many_numbered` and
+ `Fanout::next_number`.
+- `docs/latency.md` and `conformance/oracle/latency.py`, with
+ `conformance/oracle/latency.c`. They measure the time from a push to a pull,
+ and the CPU of each side, for liblsl and labstream.
+- `docs/extensions.md`, a proposal for a feature header between two labstream
+ peers. Nothing in it is implemented.
+- `conformance/oracle/headerprobe.py`. It makes sure that an outlet ignores
+ the proposed header.
- `docs/repository.md`. It gives the layout of the repository, how the
workspace joins the crates, the daily commands, CI, and the dependency
updates.
diff --git a/conformance/oracle/headerprobe.py b/conformance/oracle/headerprobe.py
new file mode 100755
index 0000000..089d536
--- /dev/null
+++ b/conformance/oracle/headerprobe.py
@@ -0,0 +1,170 @@
+#!/usr/bin/env python3
+"""Make sure that the `Labstream-Features` request header changes nothing else.
+
+`docs/extensions.md` defines this header. It depends on two facts:
+
+- An outlet that does not know the header (liblsl) gives the same answer
+ with it and without it.
+- An outlet that knows it (labstream) adds one answer line, with only
+ offered tokens, and changes nothing else in the answer or in the test
+ pattern.
+
+The probe starts `oracle/publish.c`, linked to one library. It opens two feed
+connections by hand. One request has the extra header, and one does not.
+Without the `Labstream-Features` line, the answer headers must be the same,
+byte for byte. The two test pattern samples must be the same, byte for byte.
+
+Usage:
+ oracle/headerprobe.py # liblsl and the Rust library
+ oracle/headerprobe.py --lib oracle=.build/install/lib
+"""
+
+import argparse
+import os
+import re
+import socket
+import subprocess
+import sys
+import tempfile
+import time
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+CHANNELS = 8
+
+# The request that liblsl sends (`src/data_receiver.cpp:170-190`), with fixed
+# values.
+BASE_HEADERS = [
+ "Native-Byte-Order: 1234",
+ "Endian-Performance: 0",
+ "Has-IEEE754-Floats: 1",
+ "Supports-Subnormals: 1",
+ "Value-Size: 4",
+ "Data-Protocol-Version: 110",
+ "Max-Buffer-Length: 360",
+ "Max-Chunk-Length: 0",
+ "Hostname: probe",
+ "Source-Id: ",
+ "Session-Id: default",
+]
+EXTRA = "Labstream-Features: seq/1 shm/1=0a1b2c"
+
+
+def build(lib_dir: Path, out: Path) -> None:
+ subprocess.run(["cc", "-I", str(ROOT / ".build" / "install" / "include"),
+ str(ROOT / "oracle" / "publish.c"), "-o", str(out), "-lm",
+ "-L", str(lib_dir), "-llsl", f"-Wl,-rpath,{lib_dir}"], check=True)
+
+
+def find_stream(lib_dir: Path, name: str) -> tuple:
+ """Resolve the stream with pylsl and give its uid and IPv4 data port."""
+ code = (
+ "import pylsl,sys\n"
+ f"r=pylsl.resolve_byprop('name','{name}',1,10)\n"
+ "print(r[0].as_xml() if r else '')\n"
+ )
+ lib = next(p for p in sorted(lib_dir.glob("liblsl.so*")))
+ env = dict(os.environ, PYLSL_LIB=str(lib))
+ xml = subprocess.run([sys.executable, "-c", code], env=env, capture_output=True,
+ text=True, timeout=30).stdout
+ uid = re.search(r"([^<]*)", xml)
+ port = re.search(r"(\d+)", xml)
+ if not uid or not port:
+ raise RuntimeError("the stream was not found")
+ return uid.group(1), int(port.group(1))
+
+
+def read_exact(sock: socket.socket, n: int) -> bytes:
+ out = b""
+ while len(out) < n:
+ part = sock.recv(n - len(out))
+ if not part:
+ raise RuntimeError(f"the connection closed after {len(out)} bytes")
+ out += part
+ return out
+
+
+def feed(port: int, uid: str, extra: bool) -> tuple:
+ """Send one feed request. Give the answer headers and the test pattern."""
+ lines = [f"LSL:streamfeed/110 {uid}", *BASE_HEADERS]
+ if extra:
+ lines.append(EXTRA)
+ request = "\r\n".join(lines) + "\r\n\r\n"
+ with socket.create_connection(("127.0.0.1", port), timeout=5) as s:
+ s.sendall(request.encode())
+ head = b""
+ while b"\r\n\r\n" not in head:
+ part = s.recv(1)
+ if not part:
+ raise RuntimeError("the connection closed in the headers")
+ head += part
+ # Each test pattern sample: a tag, a timestamp, and the values.
+ # SPEC.md 6.4.
+ pattern = read_exact(s, 2 * (1 + 8 + 4 * CHANNELS))
+ # The publisher pushes all the time, so the first data byte follows.
+ first = read_exact(s, 1)[0]
+ return head.decode(errors="replace"), pattern, first
+
+
+def probe(name: str, lib_dir: Path, work: Path) -> bool:
+ binary = work / f"publish_{name}"
+ build(lib_dir, binary)
+ stream = f"HeaderProbe{os.getpid()}{name}"
+ pub = subprocess.Popen([str(binary), "--name", stream, "--channels", str(CHANNELS),
+ "--rate", "100", "--seconds", "20"],
+ stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+ try:
+ time.sleep(1.0)
+ uid, port = find_stream(lib_dir, stream)
+ plain_head, plain_pattern, plain_first = feed(port, uid, extra=False)
+ with_head, with_pattern, with_first = feed(port, uid, extra=True)
+ finally:
+ pub.kill()
+ pub.wait()
+ lines = with_head.split("\r\n")
+ feature_lines = [x for x in lines if x.lower().startswith("labstream-features:")]
+ rest = "\r\n".join(x for x in lines if x not in feature_lines)
+ offered = set(EXTRA.split(":", 1)[1].split())
+ answered = set(feature_lines[0].split(":", 1)[1].split()) if feature_lines else set()
+ heads_same = plain_head == rest
+ pattern_same = plain_pattern == with_pattern
+ answer_ok = len(feature_lines) <= 1 and answered <= offered
+ # A sample starts with tag 1 or 2 (SPEC.md 7.1). With seq/1 on, the data
+ # starts with a numbering record, tag 0xFE. `docs/extensions.md`.
+ plain_data_ok = plain_first in (1, 2)
+ with_data_ok = with_first == 0xFE if "seq/1" in answered else with_first in (1, 2)
+ ok = heads_same and pattern_same and answer_ok and plain_data_ok and with_data_ok
+ answer = (f"answer '{' '.join(sorted(answered))}'" if feature_lines
+ else "no Labstream-Features answer")
+ print(f" {name:<8} {'pass' if ok else 'FAIL'} other answer headers "
+ f"{'same' if heads_same else 'DIFFERENT'}, test pattern "
+ f"{'same' if pattern_same else 'DIFFERENT'}, {answer}, first data byte "
+ f"{plain_first:#04x} plain, {with_first:#04x} with the header")
+ if not ok:
+ print(" without:", plain_head.replace("\r\n", " | "))
+ print(" with: ", with_head.replace("\r\n", " | "))
+ return ok
+
+
+def main() -> int:
+ ap = argparse.ArgumentParser(description=__doc__,
+ formatter_class=argparse.RawDescriptionHelpFormatter)
+ ap.add_argument("--lib", action="append", default=None, metavar="NAME=DIR")
+ args = ap.parse_args()
+ libs = args.lib or [f"oracle={ROOT / '.build' / 'install' / 'lib'}",
+ f"rust={ROOT / '.build' / 'rustlib'}"]
+ work = Path(tempfile.mkdtemp(prefix="headerprobe-"))
+ results = []
+ for item in libs:
+ name, _, path = item.partition("=")
+ results.append(probe(name, Path(path).resolve(), work))
+ print()
+ if all(results):
+ print("the Labstream-Features header changes nothing else on any outlet")
+ return 0
+ print("the Labstream-Features header changed something else on an outlet")
+ return 1
+
+
+if __name__ == "__main__":
+ sys.exit(main())
diff --git a/conformance/oracle/latency.c b/conformance/oracle/latency.c
new file mode 100644
index 0000000..bd55098
--- /dev/null
+++ b/conformance/oracle/latency.c
@@ -0,0 +1,253 @@
+/* Measure the time from a push in one process to a pull in another.
+ *
+ * The program runs as an outlet or as an inlet. Link it once against real
+ * liblsl and once against the Rust library. The same program then measures
+ * both libraries, and the two can also measure each other.
+ *
+ * The clock is CLOCK_MONOTONIC of this program, not the clock of the
+ * library. The outlet passes the push time as the timestamp of each sample.
+ * The inlet does no post-processing, so it reads the push time back
+ * unchanged. Both processes run on one machine and read the same clock.
+ *
+ * Channel 0 carries the sample number. The inlet uses it to count lost,
+ * repeated, and reordered samples.
+ *
+ * Each process writes one JSON line to stdout when it ends.
+ * `oracle/latency.py` runs the pairs and makes the table.
+ *
+ * Build:
+ * cc -O2 -I .build/install/include oracle/latency.c -o BIN -lm -ldl \
+ * -L DIR -llsl -Wl,-rpath,DIR
+ */
+
+#define _GNU_SOURCE
+#include
+#include
+#include
+#include
+#include
+#include
+#include
+
+#include
+
+static double now(void) {
+ struct timespec t;
+ clock_gettime(CLOCK_MONOTONIC, &t);
+ return (double)t.tv_sec + (double)t.tv_nsec * 1e-9;
+}
+
+static void sleep_until(double t) {
+ struct timespec ts;
+ ts.tv_sec = (time_t)t;
+ ts.tv_nsec = (long)((t - (double)ts.tv_sec) * 1e9);
+ while (clock_nanosleep(CLOCK_MONOTONIC, TIMER_ABSTIME, &ts, NULL) != 0) {
+ }
+}
+
+/* User plus system CPU time of this process, in seconds. */
+static double cpu_seconds(void) {
+ struct rusage r;
+ getrusage(RUSAGE_SELF, &r);
+ return (double)r.ru_utime.tv_sec + (double)r.ru_utime.tv_usec * 1e-6 +
+ (double)r.ru_stime.tv_sec + (double)r.ru_stime.tv_usec * 1e-6;
+}
+
+/* The file of the library that the loader picked. An earlier run used the
+ * wrong library through a stale RUNPATH, so each row names its library. */
+static const char *library_path(void) {
+ Dl_info d;
+ if (dladdr((void *)lsl_library_info, &d) && d.dli_fname) return d.dli_fname;
+ return "unknown";
+}
+
+static int cmp_double(const void *a, const void *b) {
+ double x = *(const double *)a, y = *(const double *)b;
+ return (x > y) - (x < y);
+}
+
+/* The value at fraction q of a sorted array. */
+static double quantile(const double *v, long n, double q) {
+ if (n <= 0) return NAN;
+ long k = (long)(q * (double)(n - 1) + 0.5);
+ return v[k];
+}
+
+static void print_library(void) {
+ printf("\"library\": \"%s\", \"library_info\": \"%s\"", library_path(), lsl_library_info());
+}
+
+static int run_outlet(const char *name, int channels, double rate, int chunk, double seconds,
+ double offset_us) {
+ lsl_streaminfo info =
+ lsl_create_streaminfo(name, "Latency", channels, rate, cft_float32, name);
+ lsl_outlet out = lsl_create_outlet(info, 0, 360);
+ if (!out) {
+ fprintf(stderr, "ERROR could not create the outlet\n");
+ return 1;
+ }
+ fprintf(stderr, "READY\n");
+ if (!lsl_wait_for_consumers(out, 20.0)) {
+ fprintf(stderr, "ERROR no consumer in 20 s\n");
+ return 1;
+ }
+
+ long total = (long)(rate * seconds);
+ long pushes = (total + chunk - 1) / chunk;
+ float *data = calloc((size_t)chunk * (size_t)channels, sizeof(float));
+ double *stamps = calloc((size_t)chunk, sizeof(double));
+ double *lag = calloc((size_t)pushes, sizeof(double));
+
+ /* The inlet starts its reader at the first pull, so the first samples
+ * wait in the outlet for a short time. Give it time to start. */
+ sleep_until(now() + 0.5);
+
+ double cpu0 = cpu_seconds();
+ double t0 = now();
+ long k = 0;
+ for (long p = 0; p < pushes; p++) {
+ long n = total - k < chunk ? total - k : chunk;
+ double due = t0 + (double)(k + n) / rate;
+ sleep_until(due);
+ for (long i = 0; i < n; i++) {
+ data[i * channels] = (float)(k + i);
+ for (int c = 1; c < channels; c++) data[i * channels + c] = (float)c;
+ }
+ double t = now();
+ lag[p] = t - due;
+ for (long i = 0; i < n; i++) stamps[i] = t - offset_us * 1e-6;
+ if (n == 1)
+ lsl_push_sample_ft(out, data, stamps[0]);
+ else
+ lsl_push_chunk_ftn(out, data, (unsigned long)(n * channels), stamps);
+ k += n;
+ }
+ double wall = now() - t0;
+ double cpu = cpu_seconds() - cpu0;
+
+ /* Let the last samples leave before the outlet closes. */
+ sleep_until(now() + 1.0);
+
+ qsort(lag, (size_t)pushes, sizeof(double), cmp_double);
+ printf("{\"role\": \"outlet\", ");
+ print_library();
+ printf(", \"sent\": %ld, \"pushes\": %ld, \"wall_s\": %.3f, \"cpu_pct\": %.3f, "
+ "\"lag_p50_us\": %.1f, \"lag_p99_us\": %.1f, \"lag_max_us\": %.1f}\n",
+ total, pushes, wall, 100.0 * cpu / wall, quantile(lag, pushes, 0.5) * 1e6,
+ quantile(lag, pushes, 0.99) * 1e6, lag[pushes - 1] * 1e6);
+ fflush(stdout);
+ lsl_destroy_outlet(out);
+ return 0;
+}
+
+static int run_inlet(const char *name, int channels, double rate, double seconds,
+ double warmup) {
+ lsl_streaminfo found[1];
+ if (lsl_resolve_byprop(found, 1, "name", name, 1, 20.0) < 1) {
+ fprintf(stderr, "ERROR the stream %s was not found\n", name);
+ return 1;
+ }
+ lsl_inlet in = lsl_create_inlet(found[0], 360, 0, 1);
+ int32_t ec = 0;
+ lsl_open_stream(in, 20.0, &ec);
+ if (ec) {
+ fprintf(stderr, "ERROR open_stream gave %d\n", ec);
+ return 1;
+ }
+ fprintf(stderr, "READY\n");
+
+ long total = (long)(rate * seconds);
+ long skip = (long)(rate * warmup);
+ double *lat = calloc((size_t)total + 1, sizeof(double));
+ unsigned char *seen = calloc((size_t)total + 1, 1);
+ float *buf = calloc((size_t)channels, sizeof(float));
+ long got = 0, kept = 0, repeated = 0, reordered = 0, alien = 0;
+ long last = -1;
+ double cpu0 = 0, t0 = 0;
+
+ for (;;) {
+ double ts = lsl_pull_sample_f(in, buf, channels, 3.0, &ec);
+ double t = now();
+ if (ts == 0.0 || ec) break; /* no sample in 3 s: the outlet is gone */
+ if (got == 0) {
+ cpu0 = cpu_seconds();
+ t0 = t;
+ }
+ got++;
+ long idx = (long)buf[0];
+ if (idx < 0 || idx >= total) {
+ alien++;
+ continue;
+ }
+ if (seen[idx]) {
+ repeated++;
+ continue;
+ }
+ seen[idx] = 1;
+ if (idx < last) reordered++;
+ last = idx;
+ if (idx >= skip) lat[kept++] = t - ts;
+ if (idx == total - 1) break;
+ }
+ double wall = now() - t0;
+ double cpu = cpu_seconds() - cpu0;
+
+ long lost = 0;
+ for (long i = 0; i < total; i++)
+ if (!seen[i]) lost++;
+
+ qsort(lat, (size_t)kept, sizeof(double), cmp_double);
+ printf("{\"role\": \"inlet\", ");
+ print_library();
+ printf(", \"expected\": %ld, \"received\": %ld, \"lost\": %ld, \"repeated\": %ld, "
+ "\"reordered\": %ld, \"alien\": %ld, \"measured\": %ld, \"wall_s\": %.3f, "
+ "\"cpu_pct\": %.3f, \"p50_us\": %.1f, \"p90_us\": %.1f, \"p99_us\": %.1f, "
+ "\"p999_us\": %.1f, \"max_us\": %.1f, \"min_us\": %.1f}\n",
+ total, got, lost, repeated, reordered, alien, kept, wall,
+ wall > 0 ? 100.0 * cpu / wall : 0.0, quantile(lat, kept, 0.5) * 1e6,
+ quantile(lat, kept, 0.9) * 1e6, quantile(lat, kept, 0.99) * 1e6,
+ quantile(lat, kept, 0.999) * 1e6, kept ? lat[kept - 1] * 1e6 : NAN,
+ kept ? lat[0] * 1e6 : NAN);
+ fflush(stdout);
+ lsl_destroy_inlet(in);
+ return 0;
+}
+
+int main(int argc, char **argv) {
+ const char *role = NULL;
+ const char *name = "LatencyBench";
+ int channels = 8;
+ double rate = 512.0;
+ int chunk = 1;
+ double seconds = 10.0;
+ double warmup = 1.0;
+ double offset_us = 0.0;
+ for (int i = 1; i < argc; i++) {
+ if (!strcmp(argv[i], "outlet") || !strcmp(argv[i], "inlet")) {
+ role = argv[i];
+ continue;
+ }
+ if (i + 1 >= argc) {
+ fprintf(stderr, "the option %s has no value\n", argv[i]);
+ return 2;
+ }
+ if (!strcmp(argv[i], "--name")) name = argv[++i];
+ else if (!strcmp(argv[i], "--channels")) channels = atoi(argv[++i]);
+ else if (!strcmp(argv[i], "--rate")) rate = atof(argv[++i]);
+ else if (!strcmp(argv[i], "--chunk")) chunk = atoi(argv[++i]);
+ else if (!strcmp(argv[i], "--seconds")) seconds = atof(argv[++i]);
+ else if (!strcmp(argv[i], "--warmup")) warmup = atof(argv[++i]);
+ else if (!strcmp(argv[i], "--offset-us")) offset_us = atof(argv[++i]);
+ else {
+ fprintf(stderr, "unknown option %s\n", argv[i]);
+ return 2;
+ }
+ }
+ if (!role || channels < 1 || rate <= 0 || chunk < 1 || seconds <= 0) {
+ fprintf(stderr, "usage: latency outlet|inlet [--name N] [--channels C] [--rate R] "
+ "[--chunk K] [--seconds S] [--warmup S] [--offset-us U]\n");
+ return 2;
+ }
+ if (!strcmp(role, "outlet")) return run_outlet(name, channels, rate, chunk, seconds, offset_us);
+ return run_inlet(name, channels, rate, seconds, warmup);
+}
diff --git a/conformance/oracle/latency.py b/conformance/oracle/latency.py
new file mode 100755
index 0000000..48d4897
--- /dev/null
+++ b/conformance/oracle/latency.py
@@ -0,0 +1,205 @@
+#!/usr/bin/env python3
+"""Measure the push-to-pull latency of each library, and of each mixed pair.
+
+The script builds `oracle/latency.c` once for each library, runs an outlet
+process and an inlet process for each cell, and writes one table. Each cell
+runs more than once, because one run of a timing test proves little.
+
+The control row is liblsl to liblsl. With `--control`, the script also runs
+that pair with a known delay in the timestamps, and the table must show the
+same delay. If it does not, the instrument is wrong, not the library.
+
+Usage:
+ oracle/latency.py
+ oracle/latency.py --lib oracle=.build/install/lib --lib main=/path/to/dir
+ oracle/latency.py --loads 512x8x1,4000x64x32 --seconds 10 --repeat 3
+ oracle/latency.py --control
+
+A load `RATExCHANNELSxCHUNK` pushes CHUNK samples in each push call. The
+first `--lib` is the reference. The script runs each library against itself,
+and the reference against each other library, in both directions.
+"""
+
+import argparse
+import json
+import os
+import statistics
+import subprocess
+import sys
+import tempfile
+import threading
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+
+DEFAULT_LOADS = "512x8x1,512x8x16,4000x64x1,4000x64x32"
+
+
+def build(source: Path, lib_dir: Path, out: Path) -> None:
+ cmd = [
+ "cc", "-O2", "-I", str(ROOT / ".build" / "install" / "include"), str(source),
+ "-o", str(out), "-lm", "-ldl", "-L", str(lib_dir), "-llsl",
+ f"-Wl,-rpath,{lib_dir}",
+ ]
+ subprocess.run(cmd, check=True)
+
+
+def wait_ready(proc: subprocess.Popen, what: str, lines: list) -> None:
+ """Read stderr until the READY line. Keep the rest for an error report."""
+ for raw in proc.stderr:
+ line = raw.decode(errors="replace").rstrip()
+ lines.append(line)
+ if line == "READY":
+ # Drain the rest in the background, so the pipe never fills.
+ threading.Thread(target=lambda: [lines.append(r.decode(errors="replace").rstrip())
+ for r in proc.stderr], daemon=True).start()
+ return
+ raise RuntimeError(f"{what}: the peer stopped before READY: {lines[-5:]}")
+
+
+def last_json(text: str) -> dict:
+ for line in reversed(text.splitlines()):
+ line = line.strip()
+ if line.startswith("{"):
+ return json.loads(line)
+ raise RuntimeError("no JSON line in the output")
+
+
+def run_pair(out_bin: Path, in_bin: Path, name: str, rate: float, channels: int, chunk: int,
+ seconds: float, offset_us: float) -> tuple:
+ common = ["--name", name, "--rate", str(rate), "--channels", str(channels),
+ "--seconds", str(seconds)]
+ out_err, in_err = [], []
+ outlet = subprocess.Popen([str(out_bin), "outlet", *common, "--chunk", str(chunk),
+ "--offset-us", str(offset_us)],
+ stdout=subprocess.PIPE, stderr=subprocess.PIPE)
+ try:
+ wait_ready(outlet, "outlet", out_err)
+ inlet = subprocess.Popen([str(in_bin), "inlet", *common],
+ stdout=subprocess.PIPE, stderr=subprocess.PIPE)
+ try:
+ wait_ready(inlet, "inlet", in_err)
+ in_out = inlet.stdout.read().decode()
+ inlet.wait(timeout=seconds + 30)
+ finally:
+ if inlet.poll() is None:
+ inlet.kill()
+ out_out = outlet.stdout.read().decode()
+ outlet.wait(timeout=30)
+ finally:
+ if outlet.poll() is None:
+ outlet.kill()
+ return last_json(out_out), last_json(in_out)
+
+
+def spread(values: list) -> str:
+ if len(values) == 1:
+ return f"{values[0]:.0f}"
+ return f"{statistics.median(values):.0f} ({min(values):.0f}-{max(values):.0f})"
+
+
+def main() -> int:
+ ap = argparse.ArgumentParser(description=__doc__,
+ formatter_class=argparse.RawDescriptionHelpFormatter)
+ ap.add_argument("--lib", action="append", default=None, metavar="NAME=DIR",
+ help="a library directory that holds liblsl.so (repeat it)")
+ ap.add_argument("--loads", default=DEFAULT_LOADS)
+ ap.add_argument("--seconds", type=float, default=10.0)
+ ap.add_argument("--repeat", type=int, default=3)
+ ap.add_argument("--no-mixed", action="store_true",
+ help="run each library only against itself")
+ ap.add_argument("--control", action="store_true",
+ help="also measure a known delay of 1000 us with the reference pair")
+ ap.add_argument("--json", default=None, help="write every run to this file")
+ args = ap.parse_args()
+
+ libs = args.lib or [f"oracle={ROOT / '.build' / 'install' / 'lib'}",
+ f"rust={ROOT / '.build' / 'rustlib'}"]
+ named = []
+ for item in libs:
+ name, _, path = item.partition("=")
+ named.append((name, Path(path).resolve()))
+
+ work = Path(tempfile.mkdtemp(prefix="latency-"))
+ bins = {}
+ for name, path in named:
+ bins[name] = work / f"latency_{name}"
+ build(ROOT / "oracle" / "latency.c", path, bins[name])
+
+ ref = named[0][0]
+ pairs = [(n, n) for n, _ in named]
+ if not args.no_mixed:
+ for n, _ in named[1:]:
+ pairs += [(ref, n), (n, ref)]
+
+ loads = []
+ for spec in args.loads.split(","):
+ rate, channels, chunk = spec.split("x")
+ loads.append((float(rate), int(channels), int(chunk)))
+
+ runs = []
+ counter = 0
+
+ def one(out_name, in_name, rate, channels, chunk, offset_us=0.0):
+ nonlocal counter
+ counter += 1
+ stream = f"Lat{os.getpid()}_{counter}"
+ o, i = run_pair(bins[out_name], bins[in_name], stream, rate, channels, chunk,
+ args.seconds, offset_us)
+ row = {"outlet": out_name, "inlet": in_name, "rate": rate, "channels": channels,
+ "chunk": chunk, "offset_us": offset_us, "outlet_run": o, "inlet_run": i}
+ runs.append(row)
+ print(f" {out_name:>10} -> {in_name:<10} {rate:g} Hz x {channels} ch, chunk {chunk}: "
+ f"p50 {i['p50_us']:.0f} us, p99 {i['p99_us']:.0f} us, lost {i['lost']}",
+ file=sys.stderr)
+ return row
+
+ for rate, channels, chunk in loads:
+ for out_name, in_name in pairs:
+ for _ in range(args.repeat):
+ one(out_name, in_name, rate, channels, chunk)
+
+ control_ok = None
+ if args.control:
+ base = [one(ref, ref, 512.0, 8, 1)["inlet_run"]["p50_us"] for _ in range(args.repeat)]
+ late = [one(ref, ref, 512.0, 8, 1, 1000.0)["inlet_run"]["p50_us"]
+ for _ in range(args.repeat)]
+ shift = statistics.median(late) - statistics.median(base)
+ control_ok = abs(shift - 1000.0) < 100.0
+ print(f"\ncontrol: a delay of 1000 us shows as {shift:.0f} us "
+ f"({'pass' if control_ok else 'FAIL'})")
+
+ print("\n| outlet -> inlet | load | p50 us | p99 us | p99.9 us | max us | lost | "
+ "CPU outlet % | CPU inlet % |")
+ print("|---|---|---|---|---|---|---|---|---|")
+ for rate, channels, chunk in loads:
+ for out_name, in_name in pairs:
+ cell = [r for r in runs if r["outlet"] == out_name and r["inlet"] == in_name
+ and r["rate"] == rate and r["channels"] == channels
+ and r["chunk"] == chunk and r["offset_us"] == 0.0]
+ if not cell:
+ continue
+ ins = [r["inlet_run"] for r in cell]
+ outs = [r["outlet_run"] for r in cell]
+ print(f"| {out_name} -> {in_name} | {rate:g} Hz x {channels}, chunk {chunk} | "
+ f"{spread([x['p50_us'] for x in ins])} | {spread([x['p99_us'] for x in ins])} | "
+ f"{spread([x['p999_us'] for x in ins])} | {max(x['max_us'] for x in ins):.0f} | "
+ f"{sum(x['lost'] + x['repeated'] + x['alien'] for x in ins)} | "
+ f"{statistics.median(x['cpu_pct'] for x in outs):.1f} | "
+ f"{statistics.median(x['cpu_pct'] for x in ins):.1f} |")
+ print(f"\nEach cell: median of {args.repeat} runs, with the range in brackets. "
+ f"Each run: {args.seconds:g} s. The first second is not measured.")
+ print("Libraries:")
+ for name, path in named:
+ seen = {r["inlet_run"]["library"] for r in runs if r["inlet"] == name}
+ print(f" {name}: {path} (loaded: {', '.join(sorted(seen))})")
+
+ if args.json:
+ Path(args.json).write_text(json.dumps(runs, indent=1))
+ if control_ok is False:
+ return 1
+ return 0
+
+
+if __name__ == "__main__":
+ sys.exit(main())
diff --git a/crates/labstream-net/src/config.rs b/crates/labstream-net/src/config.rs
index 8f33b91..e44c52f 100644
--- a/crates/labstream-net/src/config.rs
+++ b/crates/labstream-net/src/config.rs
@@ -188,6 +188,10 @@ pub struct Config {
pub allow_ipv4: bool,
/// True when an outlet binds an IPv6 stack. `ports.IPv6`.
pub allow_ipv6: bool,
+ /// The labstream features that this process can use, for example `seq`.
+ /// `labstream.Features`. liblsl does not read this key. The value `{}`
+ /// turns every feature off. `docs/extensions.md`.
+ pub features: Vec,
/// Where the values came from, for a report.
pub source: String,
}
@@ -273,6 +277,7 @@ impl Config {
port_range: ini.int("ports.PortRange", 32) as u16,
session_id: ini.text("lab.SessionID", "default"),
known_peers: ini.set("lab.KnownPeers", "{}"),
+ features: ini.set("labstream.Features", "{seq}"),
multicast_addresses: addresses,
multicast_ttl: ttl,
watchdog_time_threshold: ini.float("tuning.WatchdogTimeThreshold", 15.0),
@@ -436,6 +441,14 @@ mod tests {
assert_eq!(c.use_protocol_version, 110);
}
+ #[test]
+ fn the_labstream_features_are_on_by_default_and_a_file_turns_them_off() {
+ let c = Config::from_ini(&Ini::default(), "test");
+ assert_eq!(c.features, vec!["seq".to_string()]);
+ let off = Ini::parse("[labstream]\nFeatures = {}\n").expect("a file");
+ assert!(Config::from_ini(&off, "test").features.is_empty());
+ }
+
#[test]
fn the_scope_decides_the_groups_and_the_hop_count() {
let of = |scope: &str| {
diff --git a/crates/labstream-net/src/inlet.rs b/crates/labstream-net/src/inlet.rs
index 0e65ceb..998998a 100644
--- a/crates/labstream-net/src/inlet.rs
+++ b/crates/labstream-net/src/inlet.rs
@@ -5,6 +5,7 @@ use crate::config;
use crate::info::StreamInfo;
use crate::queue::SampleQueue;
use labstream_proto::discovery;
+use labstream_proto::features;
use labstream_proto::feed::{FeedClient, FeedParams, State, TestPatternError};
use labstream_time::{flags, PostProcessor};
use labstream_wire::Sample;
@@ -365,6 +366,10 @@ struct ConnState {
/// The description of the stream that the reader is attached to. A
/// recovery replaces it, and the instance identifier changes.
info: Mutex,
+ /// True when the current connection uses `seq/1`. `docs/extensions.md`.
+ numbered: AtomicBool,
+ /// The samples that never arrived, from the `seq/1` numbers.
+ lost: AtomicU64,
}
/// How long without data before the reader treats the source as gone.
@@ -416,6 +421,7 @@ impl Inlet {
) -> std::io::Result {
let (stream, client, buf) = handshake(info, timeout, buffer_samples)?;
debug_assert_eq!(client.state(), State::Streaming);
+ let numbered = uses_seq(&client);
// The queue holds what the application has not pulled yet. Its size is
// the value that went out in `Max-Buffer-Length`, which is a count of
@@ -438,6 +444,8 @@ impl Inlet {
recoveries: AtomicU64::new(0),
connected: AtomicBool::new(true),
info: Mutex::new(info.clone()),
+ numbered: AtomicBool::new(numbered),
+ lost: AtomicU64::new(0),
});
// One thread owns the connection for its whole life: it reads, and when
@@ -586,6 +594,24 @@ impl Inlet {
self.queue.dropped()
}
+ /// How many samples never reached this inlet, since it opened.
+ ///
+ /// The count comes from the `seq/1` numbers (`docs/extensions.md`). It
+ /// shows a sample that the outlet dropped from a full queue, and the
+ /// samples between a lost connection and the next one. The value is
+ /// `None` when the current connection does not use `seq/1`, for example
+ /// with a liblsl outlet. `None` means unknown, not zero.
+ ///
+ /// The inlet queue drops after this count, so a full total adds
+ /// [`Inlet::samples_dropped`].
+ pub fn samples_lost(&self) -> Option {
+ if self.conn.numbered.load(Ordering::SeqCst) {
+ Some(self.conn.lost.load(Ordering::SeqCst))
+ } else {
+ None
+ }
+ }
+
/// The size of the queue, in samples.
pub fn buffer_capacity(&self) -> usize {
self.queue.capacity()
@@ -632,6 +658,10 @@ fn read_and_recover(
let srate = conn.info.lock().unwrap().nominal_srate;
let mut deducer = labstream_wire::TimestampDeducer::new(srate);
+ // The `seq/1` count. It lives as long as the inlet, so the first record
+ // after a reconnect to the same outlet shows the gap.
+ let mut counter = labstream_proto::seq::Counter::new();
+
loop {
if queue.is_closed() {
break;
@@ -639,7 +669,15 @@ fn read_and_recover(
// Decode everything already buffered before reading more. The whole
// read goes into the queue with one lock.
- let decoded = decode_buffered(&codec, &mut carry, &mut deducer, &mut batch);
+ let numbered = conn.numbered.load(Ordering::SeqCst);
+ let decoded = decode_buffered(
+ &codec,
+ &mut carry,
+ &mut deducer,
+ numbered.then_some(&mut counter),
+ &mut batch,
+ );
+ conn.lost.store(counter.lost(), Ordering::SeqCst);
if !batch.is_empty() {
last_data = Instant::now();
queue.push_owned(&mut batch);
@@ -725,6 +763,7 @@ fn read_and_recover(
sock = s;
carry = rest;
codec = *c.codec().expect("the handshake set the codec");
+ conn.numbered.store(uses_seq(&c), Ordering::SeqCst);
conn.recoveries.fetch_add(1, Ordering::SeqCst);
conn.connected.store(true, Ordering::SeqCst);
last_data = Instant::now();
@@ -755,6 +794,9 @@ fn read_and_recover(
}
clock.reset_offset();
deducer = labstream_wire::TimestampDeducer::new(fresh.nominal_srate);
+ // A new outlet has a new counter.
+ counter.restart();
+ conn.numbered.store(uses_seq(&c), Ordering::SeqCst);
*conn.info.lock().unwrap() = *fresh;
conn.recoveries.fetch_add(1, Ordering::SeqCst);
conn.connected.store(true, Ordering::SeqCst);
@@ -799,15 +841,33 @@ fn decode_buffered(
codec: &labstream_wire::Codec,
carry: &mut Vec,
deducer: &mut labstream_wire::TimestampDeducer,
+ mut counter: Option<&mut labstream_proto::seq::Counter>,
out: &mut Vec,
) -> Result<(), labstream_wire::Error> {
+ use labstream_proto::seq::{peek, Next, RECORD_LEN};
let mut pos = 0;
let result = loop {
+ // With `seq/1`, a numbering record can stand before a sample. A cut
+ // record waits for more bytes, as a cut sample does.
+ if let Some(c) = counter.as_deref_mut() {
+ match peek(&carry[pos..]) {
+ Next::Record(n) => {
+ c.record(n);
+ pos += RECORD_LEN;
+ continue;
+ }
+ Next::Incomplete => break Ok(()),
+ Next::Sample => {}
+ }
+ }
match codec.decode(&carry[pos..]) {
Ok((mut sample, used)) => {
pos += used;
sample.timestamp = deducer.apply(sample.timestamp);
out.push(sample);
+ if let Some(c) = counter.as_deref_mut() {
+ c.sample();
+ }
}
Err(labstream_wire::Error::Truncated) => break Ok(()),
Err(e) => break Err(e),
@@ -895,6 +955,11 @@ pub fn read_fullinfo(known: &StreamInfo, timeout: Duration) -> std::io::Result bool {
+ features::has(client.features(), features::SEQ, 1)
+}
+
/// Connect and run the whole handshake. SPEC.md 4 and 6.
///
/// The reader thread calls this again after a recovery, so it lives outside
@@ -916,7 +981,11 @@ fn handshake(
params.session_id = info.session_id.clone();
params.max_buffer_length = buffer_samples.max(1);
- let (mut client, request) = FeedClient::start(params, info.format, info.channel_count as usize);
+ // A labstream outlet answers the offer, and any other outlet ignores it.
+ // `docs/extensions.md`.
+ let offer = features::offer(&crate::config::get().features);
+ let (mut client, request) =
+ FeedClient::start_with(params, info.format, info.channel_count as usize, offer);
stream.write_all(&request)?;
stream.flush()?;
@@ -1022,13 +1091,84 @@ mod tests {
let mut from = 0;
for &to in cuts.iter().chain(std::iter::once(&bytes.len())) {
carry.extend_from_slice(&bytes[from..to]);
- decode_buffered(codec, &mut carry, &mut deducer, &mut out).unwrap();
+ decode_buffered(codec, &mut carry, &mut deducer, None, &mut out).unwrap();
from = to;
}
assert!(carry.is_empty(), "no byte stays behind at the end");
out
}
+ /// Decode in reads, with a `seq/1` counter. Give the samples and the
+ /// counter at the end.
+ fn decode_numbered(
+ codec: &Codec,
+ bytes: &[u8],
+ cuts: &[usize],
+ ) -> (Vec, labstream_proto::seq::Counter) {
+ let mut carry = Vec::new();
+ let mut deducer = TimestampDeducer::new(100.0);
+ let mut counter = labstream_proto::seq::Counter::new();
+ let mut out = Vec::new();
+ let mut from = 0;
+ for &to in cuts.iter().chain(std::iter::once(&bytes.len())) {
+ carry.extend_from_slice(&bytes[from..to]);
+ decode_buffered(
+ codec,
+ &mut carry,
+ &mut deducer,
+ Some(&mut counter),
+ &mut out,
+ )
+ .unwrap();
+ from = to;
+ }
+ assert!(carry.is_empty(), "no byte stays behind at the end");
+ (out, counter)
+ }
+
+ #[test]
+ fn a_numbered_stream_cut_at_any_byte_gives_the_same_samples_and_count() {
+ use labstream_proto::seq::write_record;
+ for order in [ByteOrder::Little, ByteOrder::Big] {
+ let codec = Codec::new(Format::Float32, 3, order);
+ let (samples, _) = stream(&codec, 12);
+ // Numbers 40..45, then a gap of 3, then 48..54.
+ let mut bytes = Vec::new();
+ write_record(&mut bytes, 40);
+ for s in &samples[..5] {
+ codec.encode(s, &mut bytes).unwrap();
+ }
+ write_record(&mut bytes, 48);
+ for s in &samples[5..] {
+ codec.encode(s, &mut bytes).unwrap();
+ }
+ let (whole, c) = decode_numbered(&codec, &bytes, &[]);
+ assert_eq!(whole.len(), 12);
+ assert_eq!(c.lost(), 3);
+ assert_eq!(c.expected(), Some(55));
+ for cut in 1..bytes.len() {
+ let (got, c) = decode_numbered(&codec, &bytes, &[cut]);
+ assert_eq!(got, whole, "a cut at {cut}");
+ assert_eq!(c.lost(), 3, "a cut at {cut}");
+ }
+ }
+ }
+
+ #[test]
+ fn a_plain_stream_never_reads_a_record() {
+ // Without `seq/1`, the byte 0xFE is not a record. Here it can only
+ // stand inside a value, and the codec reads it as data.
+ let codec = Codec::new(Format::Int8, 1, ByteOrder::native());
+ let s = Sample {
+ timestamp: 1.0,
+ values: vec![Value::I8(-2)],
+ };
+ let mut bytes = Vec::new();
+ codec.encode(&s, &mut bytes).unwrap();
+ assert!(bytes.contains(&0xFE));
+ assert_eq!(decode_in_reads(&codec, &bytes, &[]), vec![s]);
+ }
+
#[test]
fn a_cut_at_any_byte_gives_the_same_samples() {
let codec = Codec::new(Format::Float32, 3, ByteOrder::native());
@@ -1065,7 +1205,7 @@ mod tests {
let mut carry = bytes;
let mut deducer = TimestampDeducer::new(100.0);
let mut out = Vec::new();
- assert!(decode_buffered(&codec, &mut carry, &mut deducer, &mut out).is_err());
+ assert!(decode_buffered(&codec, &mut carry, &mut deducer, None, &mut out).is_err());
assert_eq!(out.len(), 2);
}
diff --git a/crates/labstream-net/src/outlet.rs b/crates/labstream-net/src/outlet.rs
index 9f5ac98..a7ea511 100644
--- a/crates/labstream-net/src/outlet.rs
+++ b/crates/labstream-net/src/outlet.rs
@@ -4,8 +4,10 @@ use crate::info::StreamInfo;
use crate::queue::{Fanout, SampleQueue};
use crate::{clock, config};
use labstream_proto::discovery;
+use labstream_proto::features;
use labstream_proto::header::parse_block;
use labstream_proto::negotiate::{negotiate, FeedRequest, Outcome, ServerStream, LITTLE};
+use labstream_proto::seq::Numbering;
use labstream_proto::timesync;
use labstream_wire::{Codec, Sample, TEST_PATTERN_OFFSETS};
use std::io::{Read, Write};
@@ -25,7 +27,7 @@ struct Shared {
/// One queue per connected consumer. SPEC.md 8.8.
fanout: Fanout,
/// The consumers of a blocking outlet, which holds no queue at all.
- sync: Mutex>,
+ sync: Mutex,
/// True when this outlet writes each sample before the push returns.
sync_mode: bool,
stop: Mutex,
@@ -38,6 +40,17 @@ struct Shared {
struct SyncConsumer {
stream: TcpStream,
codec: Codec,
+ /// The record state, when the consumer agreed to `seq/1`.
+ numbering: Option,
+}
+
+/// The consumers of a blocking outlet, and the number of the next sample.
+///
+/// One lock holds both, so the numbers follow the order of the writes.
+#[derive(Default)]
+struct SyncSet {
+ list: Vec,
+ next: u64,
}
/// A stream outlet.
@@ -139,7 +152,7 @@ impl Outlet {
let shared = Arc::new(Shared {
info: Mutex::new(info.clone()),
fanout: Fanout::new(),
- sync: Mutex::new(Vec::new()),
+ sync: Mutex::new(SyncSet::default()),
sync_mode,
stop: Mutex::new(false),
});
@@ -193,7 +206,7 @@ impl Outlet {
if self.shared.sync_mode {
// A blocking outlet registers its consumers with the writer rather
// than with the queue. `src/stream_outlet_impl.cpp:176-179`.
- return self.shared.sync.lock().unwrap().len();
+ return self.shared.sync.lock().unwrap().list.len();
}
self.shared.fanout.count()
}
@@ -255,24 +268,21 @@ impl Outlet {
/// A consumer whose socket fails is dropped. Nothing is queued, so a consumer
/// that reads slowly holds up the caller. That is the whole point of the mode.
fn write_blocking(shared: &Shared, sample: &Sample) {
- let mut out = Vec::new();
- let mut consumers = shared.sync.lock().unwrap();
- consumers.retain_mut(|c| {
- out.clear();
- if c.codec.encode(sample, &mut out).is_err() {
- return false;
- }
- c.stream.write_all(&out).is_ok() && c.stream.flush().is_ok()
- });
+ write_blocking_many(shared, std::slice::from_ref(sample));
}
/// Write several samples to every consumer, with one write for each consumer.
fn write_blocking_many(shared: &Shared, samples: &[Sample]) {
let mut out = Vec::new();
- let mut consumers = shared.sync.lock().unwrap();
- consumers.retain_mut(|c| {
+ let mut set = shared.sync.lock().unwrap();
+ let first = set.next;
+ set.next = first.wrapping_add(samples.len() as u64);
+ set.list.retain_mut(|c| {
out.clear();
- for s in samples {
+ for (i, s) in samples.iter().enumerate() {
+ if let Some(n) = c.numbering.as_mut() {
+ n.before(first.wrapping_add(i as u64), &mut out);
+ }
if c.codec.encode(s, &mut out).is_err() {
return false;
}
@@ -611,9 +621,17 @@ fn serve_client(mut stream: TcpStream, shared: Arc) -> std::io::Result<(
return Ok(());
}
+ // A labstream inlet offers its features in one more header. An inlet
+ // that sent none gets the plain answer. `docs/extensions.md`.
+ let answered = headers
+ .get(features::HEADER_KEY)
+ .map(|v| features::answer(&features::parse(v), &config::get().features));
+ let numbered = answered
+ .as_deref()
+ .is_some_and(|a| features::has(a, features::SEQ, 1));
stream.write_all(
accepted
- .to_wire(srv.configured_version, &info.uid)
+ .to_wire_with(srv.configured_version, &info.uid, answered.as_deref())
.as_bytes(),
)?;
@@ -657,11 +675,24 @@ fn serve_client(mut stream: TcpStream, shared: Arc) -> std::io::Result<(
if trace {
eprintln!("TRACE handing the socket to the blocking writer");
}
- shared
- .sync
- .lock()
- .unwrap()
- .push(SyncConsumer { stream, codec });
+ let mut set = shared.sync.lock().unwrap();
+ // A numbered consumer gets its first record at once, under the lock
+ // that numbers the writes. `docs/extensions.md`.
+ let numbering = if numbered {
+ let mut n = Numbering::new();
+ let mut record = Vec::new();
+ n.start(set.next, &mut record);
+ stream.write_all(&record)?;
+ stream.flush()?;
+ Some(n)
+ } else {
+ None
+ };
+ set.list.push(SyncConsumer {
+ stream,
+ codec,
+ numbering,
+ });
return Ok(());
}
@@ -681,7 +712,15 @@ fn serve_client(mut stream: TcpStream, shared: Arc) -> std::io::Result<(
};
let stop = || *shared.stop.lock().unwrap();
- let sent = feed(&queue, &codec, &mut stream, max_chunk, &stop, trace);
+ let sent = feed(
+ &queue,
+ &codec,
+ &mut stream,
+ max_chunk,
+ numbered,
+ &stop,
+ trace,
+ );
if trace {
eprintln!("TRACE session over after {sent} samples");
}
@@ -702,15 +741,33 @@ fn serve_client(mut stream: TcpStream, shared: Arc) -> std::io::Result<(
/// as the push-through flag. When the writer is slower than the source, one
/// write can carry more than one push call. No sample waits for a later push.
///
+/// When `numbered` is true, the consumer agreed to `seq/1`. A numbering
+/// record then goes before the first sample, and before each sample whose
+/// number does not follow the one before it. A record does not count toward
+/// the chunk size. `docs/extensions.md`.
+///
/// The result is the number of samples written.
fn feed(
queue: &SampleQueue,
codec: &Codec,
out: &mut W,
max_chunk: usize,
+ numbered: bool,
stop: &dyn Fn() -> bool,
trace: bool,
) -> usize {
+ let mut numbering = numbered.then(Numbering::new);
+ // The first record goes out at once, before any sample. A gap before
+ // this connection is then visible on a quiet stream too.
+ if let Some(n) = numbering.as_mut() {
+ let (_, next) = queue.pop_many_numbered(&mut Vec::new(), 0, Duration::ZERO);
+ let mut record = Vec::new();
+ n.start(next, &mut record);
+ if out.write_all(&record).is_err() {
+ return 0;
+ }
+ let _ = out.flush();
+ }
let mut batch: Vec = Vec::new();
let mut pending: Vec = Vec::new();
let mut count = 0usize;
@@ -736,10 +793,15 @@ fn feed(
break;
}
batch.clear();
- if queue.pop_many(&mut batch, usize::MAX, Duration::from_millis(200)) == 0 {
+ let (taken, first) =
+ queue.pop_many_numbered(&mut batch, usize::MAX, Duration::from_millis(200));
+ if taken == 0 {
continue;
}
- for s in &batch {
+ for (i, s) in batch.iter().enumerate() {
+ if let Some(n) = numbering.as_mut() {
+ n.before(first.wrapping_add(i as u64), &mut pending);
+ }
if codec.encode(s, &mut pending).is_err() {
return sent;
}
@@ -892,7 +954,7 @@ mod tests {
let once = AtomicBool::new(false);
// The first call to `stop` lets one round run. The second one stops.
let stop = || once.swap(true, Ordering::SeqCst);
- let sent = feed(queue, &codec, &mut out, max_chunk, &stop, false);
+ let sent = feed(queue, &codec, &mut out, max_chunk, false, &stop, false);
(sent, out)
}
@@ -926,6 +988,67 @@ mod tests {
assert_eq!(out.writes, 1);
}
+ /// Feed a numbered queue once, and read the records and samples back.
+ fn run_numbered(
+ queue: &SampleQueue,
+ max_chunk: usize,
+ order: ByteOrder,
+ ) -> (Vec, Vec, Counting) {
+ use labstream_proto::seq::{peek, Next, RECORD_LEN};
+ let codec = Codec::new(Format::Float32, 2, order);
+ let mut out = Counting::default();
+ let once = AtomicBool::new(false);
+ let stop = || once.swap(true, Ordering::SeqCst);
+ feed(queue, &codec, &mut out, max_chunk, true, &stop, false);
+ let mut pos = 0;
+ let (mut got, mut records) = (Vec::new(), Vec::new());
+ while pos < out.bytes.len() {
+ if let Next::Record(n) = peek(&out.bytes[pos..]) {
+ records.push(n);
+ pos += RECORD_LEN;
+ continue;
+ }
+ let (s, used) = codec.decode(&out.bytes[pos..]).unwrap();
+ got.push(s);
+ pos += used;
+ }
+ (got, records, out)
+ }
+
+ #[test]
+ fn a_numbered_feed_starts_with_a_record() {
+ for order in [ByteOrder::Little, ByteOrder::Big] {
+ let q = SampleQueue::with_first_number(1000, 500);
+ let sent = samples(20);
+ q.push_many(&sent);
+ let (got, records, _) = run_numbered(&q, usize::MAX, order);
+ assert_eq!(got, sent);
+ assert_eq!(records, vec![500], "one record, at the start");
+ }
+ }
+
+ #[test]
+ fn a_full_queue_shows_as_a_gap_in_the_numbers() {
+ // A queue of 4 that gets 10 samples keeps numbers 106 to 109.
+ let q = SampleQueue::with_first_number(4, 100);
+ q.push_many(&samples(10));
+ let (got, records, _) = run_numbered(&q, usize::MAX, ByteOrder::native());
+ assert_eq!(got.len(), 4);
+ assert_eq!(records, vec![106]);
+ }
+
+ #[test]
+ fn a_record_does_not_count_toward_the_chunk_size() {
+ let q = SampleQueue::with_first_number(1000, 7);
+ q.push_many(&samples(32));
+ let (got, records, out) = run_numbered(&q, 16, ByteOrder::native());
+ assert_eq!(got.len(), 32);
+ assert_eq!(records, vec![7]);
+ // The opening record is a write of its own, at the start of the
+ // connection. Then 16 samples go in each write.
+ assert_eq!(out.writes, 3, "the record, then two chunks of 16");
+ }
+
#[test]
fn the_bytes_decode_to_the_same_samples() {
let q = SampleQueue::new(1000);
diff --git a/crates/labstream-net/src/queue.rs b/crates/labstream-net/src/queue.rs
index e2bb66a..d0d93ee 100644
--- a/crates/labstream-net/src/queue.rs
+++ b/crates/labstream-net/src/queue.rs
@@ -16,10 +16,42 @@ use std::sync::atomic::{AtomicU64, Ordering};
use std::sync::{Arc, Condvar, Mutex};
use std::time::{Duration, Instant};
+/// The samples of a queue, and the number after the last one.
+///
+/// Each push adds one to `back`, also for a sample that the queue drops at
+/// once. A removal does not change it. The samples in the queue thus always
+/// have the numbers `back - len .. back`, with no gap: the queue drops only
+/// from the front, and a push only adds at the back. `docs/extensions.md`.
+#[derive(Debug)]
+struct Ring {
+ q: VecDeque,
+ back: u64,
+}
+
+impl std::ops::Deref for Ring {
+ type Target = VecDeque;
+ fn deref(&self) -> &VecDeque {
+ &self.q
+ }
+}
+
+impl std::ops::DerefMut for Ring {
+ fn deref_mut(&mut self) -> &mut VecDeque {
+ &mut self.q
+ }
+}
+
+impl Ring {
+ /// The number of the sample at the front.
+ fn front_number(&self) -> u64 {
+ self.back.wrapping_sub(self.q.len() as u64)
+ }
+}
+
/// A queue that never blocks its writer.
#[derive(Debug)]
pub struct SampleQueue {
- inner: Mutex>,
+ inner: Mutex,
room: Condvar,
capacity: usize,
dropped: AtomicU64,
@@ -32,9 +64,20 @@ impl SampleQueue {
/// A capacity of zero would drop every sample, so the value floors at 1.
/// liblsl floors the same way (`src/stream_info_impl.cpp:268`).
pub fn new(capacity: usize) -> Self {
+ Self::with_first_number(capacity, 0)
+ }
+
+ /// Build a queue whose first pushed sample gets the number `first`.
+ ///
+ /// The `seq` feature numbers the samples of an outlet with one counter.
+ /// A consumer that connects later starts at the current count.
+ pub fn with_first_number(capacity: usize, first: u64) -> Self {
let capacity = capacity.max(1);
SampleQueue {
- inner: Mutex::new(VecDeque::with_capacity(capacity.min(4096))),
+ inner: Mutex::new(Ring {
+ q: VecDeque::with_capacity(capacity.min(4096)),
+ back: first,
+ }),
room: Condvar::new(),
capacity,
dropped: AtomicU64::new(0),
@@ -76,6 +119,7 @@ impl SampleQueue {
self.dropped.fetch_add(1, Ordering::SeqCst);
}
q.push_back(s);
+ q.back = q.back.wrapping_add(1);
drop(q);
self.room.notify_one();
}
@@ -102,6 +146,7 @@ impl SampleQueue {
}
q.push_back(s.clone());
}
+ q.back = q.back.wrapping_add(samples.len() as u64);
drop(q);
if lost > 0 {
self.dropped.fetch_add(lost, Ordering::SeqCst);
@@ -123,6 +168,8 @@ impl SampleQueue {
let mut lost = 0u64;
// Samples that the queue drops at once are never moved in.
let skip = samples.len().saturating_sub(self.capacity);
+ // Each sample takes a number, also the ones that are never moved in.
+ q.back = q.back.wrapping_add(samples.len() as u64);
for s in samples.drain(..).skip(skip) {
if q.len() >= self.capacity {
q.pop_front();
@@ -208,6 +255,38 @@ impl SampleQueue {
}
}
+ /// Like [`SampleQueue::pop_many`], and also give the number of the first
+ /// sample that it took.
+ ///
+ /// The samples that it took have consecutive numbers. With no sample, the
+ /// number is the one that the next sample gets.
+ pub fn pop_many_numbered(
+ &self,
+ out: &mut Vec,
+ max: usize,
+ timeout: Duration,
+ ) -> (usize, u64) {
+ if max == 0 {
+ return (0, self.inner.lock().unwrap().front_number());
+ }
+ let end = Instant::now() + timeout;
+ let mut q = self.inner.lock().unwrap();
+ loop {
+ if !q.is_empty() || Instant::now() >= end || *self.closed.lock().unwrap() {
+ let first = q.front_number();
+ let take = q.len().min(max);
+ out.extend(q.drain(..take));
+ return (take, first);
+ }
+ let left = end.saturating_duration_since(Instant::now());
+ let (guard, _) = self
+ .room
+ .wait_timeout(q, left.min(Duration::from_millis(100)))
+ .unwrap();
+ q = guard;
+ }
+ }
+
/// Wake every reader and stop the queue.
pub fn close(&self) {
*self.closed.lock().unwrap() = true;
@@ -226,7 +305,17 @@ impl SampleQueue {
/// its own queue, so a slow consumer loses only its own samples. SPEC.md 8.8.
#[derive(Debug, Default)]
pub struct Fanout {
- consumers: Mutex>>,
+ consumers: Mutex,
+}
+
+/// The queues of a fanout, and the number of the next pushed sample.
+///
+/// One lock holds both, so a new queue starts at the number that the next
+/// push gives, and every queue sees the same numbers.
+#[derive(Debug, Default)]
+struct Consumers {
+ list: Vec>,
+ next: u64,
}
impl Fanout {
@@ -237,22 +326,29 @@ impl Fanout {
/// Add a consumer with its own queue.
pub fn add(&self, capacity: usize) -> Arc {
- let q = Arc::new(SampleQueue::new(capacity));
- self.consumers.lock().unwrap().push(Arc::clone(&q));
+ let mut set = self.consumers.lock().unwrap();
+ let q = Arc::new(SampleQueue::with_first_number(capacity, set.next));
+ set.list.push(Arc::clone(&q));
q
}
+ /// The number that the next pushed sample gets.
+ pub fn next_number(&self) -> u64 {
+ self.consumers.lock().unwrap().next
+ }
+
/// Remove a consumer.
pub fn remove(&self, q: &Arc) {
self.consumers
.lock()
.unwrap()
+ .list
.retain(|c| !Arc::ptr_eq(c, q));
}
/// How many consumers are connected.
pub fn count(&self) -> usize {
- self.consumers.lock().unwrap().len()
+ self.consumers.lock().unwrap().list.len()
}
/// Give one sample to every consumer.
@@ -261,8 +357,9 @@ impl Fanout {
/// waits, whatever any consumer is doing.
pub fn push(&self, s: &Sample) {
let mut set = self.consumers.lock().unwrap();
- set.retain(|q| !q.is_closed());
- for q in set.iter() {
+ set.next = set.next.wrapping_add(1);
+ set.list.retain(|q| !q.is_closed());
+ for q in set.list.iter() {
q.push(s.clone());
}
}
@@ -276,15 +373,16 @@ impl Fanout {
return;
}
let mut set = self.consumers.lock().unwrap();
- set.retain(|q| !q.is_closed());
- for q in set.iter() {
+ set.next = set.next.wrapping_add(samples.len() as u64);
+ set.list.retain(|q| !q.is_closed());
+ for q in set.list.iter() {
q.push_many(samples);
}
}
/// Close every consumer queue.
pub fn close(&self) {
- for q in self.consumers.lock().unwrap().iter() {
+ for q in self.consumers.lock().unwrap().list.iter() {
q.close();
}
}
@@ -538,4 +636,92 @@ mod tests {
f.push(&sample(2));
assert_eq!(a.len(), 1, "a removed consumer must receive nothing more");
}
+
+ /// A small generator, so the test runs the same steps on each run.
+ struct Steps(u64);
+
+ impl Steps {
+ fn next(&mut self, below: u64) -> u64 {
+ self.0 ^= self.0 << 13;
+ self.0 ^= self.0 >> 7;
+ self.0 ^= self.0 << 17;
+ self.0 % below
+ }
+ }
+
+ #[test]
+ fn the_numbers_follow_a_model_with_one_number_for_each_sample() {
+ // Each sample carries its own number as its value. The model keeps
+ // the numbers. Every way to push, drop and pop must agree with it.
+ for seed in 1..40u64 {
+ let mut steps = Steps(seed.wrapping_mul(0x9E37_79B9_7F4A_7C15));
+ let capacity = 1 + steps.next(12) as usize;
+ let first = steps.next(1000);
+ let q = SampleQueue::with_first_number(capacity, first);
+ let mut model: VecDeque = VecDeque::new();
+ let mut next = first;
+ for _ in 0..400 {
+ match steps.next(5) {
+ 0 => {
+ q.push(sample(next as i32));
+ model.push_back(next);
+ next += 1;
+ }
+ 1 | 2 => {
+ let k = steps.next(30) as usize;
+ let block: Vec =
+ (0..k).map(|i| sample((next + i as u64) as i32)).collect();
+ if steps.next(2) == 0 {
+ q.push_many(&block);
+ } else {
+ let mut owned = block;
+ q.push_owned(&mut owned);
+ }
+ for i in 0..k as u64 {
+ model.push_back(next + i);
+ }
+ next += k as u64;
+ }
+ 3 => {
+ let got = q.pop(Duration::ZERO);
+ let want = model.pop_front();
+ assert_eq!(got.map(|s| index(&s) as u64), want);
+ }
+ _ => {
+ let max = 1 + steps.next(20) as usize;
+ let mut out = Vec::new();
+ let (n, number) = q.pop_many_numbered(&mut out, max, Duration::ZERO);
+ assert_eq!(n, out.len());
+ let want_first = model.front().copied().unwrap_or(next);
+ assert_eq!(number, want_first, "seed {seed}");
+ for (i, s) in out.iter().enumerate() {
+ assert_eq!(index(s) as u64, number + i as u64, "seed {seed}");
+ assert_eq!(model.pop_front(), Some(number + i as u64));
+ }
+ }
+ }
+ while model.len() > capacity {
+ model.pop_front();
+ }
+ assert_eq!(q.len(), model.len(), "seed {seed}");
+ }
+ }
+ }
+
+ #[test]
+ fn a_late_consumer_starts_at_the_current_number() {
+ let f = Fanout::new();
+ let a = f.add(100);
+ for i in 0..5 {
+ f.push(&sample(i));
+ }
+ let b = f.add(100);
+ assert_eq!(f.next_number(), 5);
+ f.push_many(&[sample(5), sample(6)]);
+ let mut out = Vec::new();
+ assert_eq!(a.pop_many_numbered(&mut out, 100, Duration::ZERO), (7, 0));
+ out.clear();
+ assert_eq!(b.pop_many_numbered(&mut out, 100, Duration::ZERO), (2, 5));
+ assert_eq!(index(&out[0]), 5);
+ }
}
diff --git a/crates/labstream-net/tests/seq_live.rs b/crates/labstream-net/tests/seq_live.rs
new file mode 100644
index 0000000..edf6917
--- /dev/null
+++ b/crates/labstream-net/tests/seq_live.rs
@@ -0,0 +1,379 @@
+//! The `seq/1` feature, measured against a live outlet. `docs/extensions.md`.
+//!
+//! These tests open real sockets on the loopback interface, so they belong to
+//! the reporting tier and not to the merge gate. A failure here can come from
+//! the machine.
+//!
+//! Each test makes sure that the counts add up: every pushed sample is
+//! received, counted as lost, or counted as dropped by the inlet queue.
+
+use labstream_net::{Inlet, Outlet, StreamInfo};
+use labstream_proto::features::{self, Token};
+use labstream_proto::feed::{FeedClient, FeedParams, TestPatternError};
+use labstream_proto::seq;
+use labstream_wire::{Format, Sample, Value};
+use std::io::{Read, Write};
+use std::net::{Shutdown, TcpListener, TcpStream};
+use std::sync::atomic::{AtomicBool, AtomicUsize, Ordering};
+use std::sync::{Arc, Mutex};
+use std::time::{Duration, Instant};
+
+fn sample(k: usize) -> Sample {
+ Sample {
+ timestamp: 0.0,
+ values: vec![Value::F32(k as f32)],
+ }
+}
+
+fn value(s: &Sample) -> usize {
+ match s.values[0] {
+ Value::F32(v) => v as usize,
+ _ => panic!("wrong format"),
+ }
+}
+
+fn outlet(name: &str) -> Option {
+ let mut info = StreamInfo::new(name, "SeqTest", 1, Format::Float32, 1000.0);
+ info.source_id = format!("{name}_src");
+ Outlet::new(info).ok()
+}
+
+/// Pull until a sample with the value `last` arrives, or the time runs out.
+fn pull_until(inlet: &mut Inlet, last: usize, within: Duration) -> Vec {
+ let mut got = Vec::new();
+ let end = Instant::now() + within;
+ while Instant::now() < end {
+ let mut block = Vec::new();
+ let _ = inlet.pull_chunk(&mut block, 100_000, Duration::from_millis(20));
+ let done = block.iter().any(|s| value(s) == last);
+ got.extend(block);
+ if done {
+ break;
+ }
+ }
+ got
+}
+
+#[test]
+fn the_count_adds_up_when_the_outlet_queue_drops() {
+ let out = match outlet("SeqLive1") {
+ Some(o) => o,
+ None => {
+ eprintln!("no local network; skipping");
+ return;
+ }
+ };
+ // The inlet asks for 32 samples of buffer, so the outlet keeps a queue
+ // of 32 for it.
+ let mut inlet =
+ Inlet::open_recovering(out.info(), Duration::from_secs(5), 32).expect("the inlet opens");
+ assert!(out.wait_for_consumers(Duration::from_secs(5)));
+
+ // One sample sets the baseline of the count.
+ out.push(&sample(0));
+ let first = pull_until(&mut inlet, 0, Duration::from_secs(5));
+ assert_eq!(first.len(), 1, "the first sample arrives");
+ assert_eq!(inlet.samples_lost(), Some(0), "two labstream peers use seq");
+
+ // One push of a large block. The queue of 32 keeps the last 32 samples.
+ let n = 100_000;
+ out.push_samples((1..=n).map(sample).collect());
+ let got = pull_until(&mut inlet, n, Duration::from_secs(10));
+ assert_eq!(got.last().map(value), Some(n), "the last sample arrives");
+
+ let lost = inlet.samples_lost().expect("a count");
+ let dropped = inlet.samples_dropped();
+ println!("received {}, lost {lost}, dropped {dropped}", got.len());
+ assert_eq!(got.len() as u64 + lost + dropped, n as u64);
+ assert!(
+ lost >= (n - 64) as u64,
+ "the outlet dropped most of the block"
+ );
+}
+
+/// A TCP proxy that forwards each connection to `target`, and can cut them.
+struct Proxy {
+ port: u16,
+ accepted: Arc>>,
+ /// While true, the proxy closes each new connection at once.
+ paused: Arc,
+}
+
+impl Proxy {
+ fn start(target: u16) -> Option {
+ let listener = TcpListener::bind("127.0.0.1:0").ok()?;
+ let port = listener.local_addr().ok()?.port();
+ let accepted = Arc::new(Mutex::new(Vec::new()));
+ let list = Arc::clone(&accepted);
+ let paused = Arc::new(AtomicBool::new(false));
+ let hold = Arc::clone(&paused);
+ std::thread::spawn(move || {
+ for client in listener.incoming().flatten() {
+ if hold.load(Ordering::SeqCst) {
+ let _ = client.shutdown(Shutdown::Both);
+ continue;
+ }
+ let server = match TcpStream::connect(("127.0.0.1", target)) {
+ Ok(s) => s,
+ Err(_) => continue,
+ };
+ list.lock().unwrap().push(client.try_clone().unwrap());
+ pipe(client.try_clone().unwrap(), server.try_clone().unwrap());
+ pipe(server, client);
+ }
+ });
+ Some(Proxy {
+ port,
+ accepted,
+ paused,
+ })
+ }
+
+ fn cut(&self) {
+ for s in self.accepted.lock().unwrap().drain(..) {
+ let _ = s.shutdown(Shutdown::Both);
+ }
+ }
+}
+
+fn pipe(mut from: TcpStream, mut to: TcpStream) {
+ std::thread::spawn(move || {
+ let mut buf = [0u8; 16384];
+ while let Ok(n) = from.read(&mut buf) {
+ if n == 0 || to.write_all(&buf[..n]).is_err() {
+ break;
+ }
+ }
+ let _ = to.shutdown(Shutdown::Both);
+ let _ = from.shutdown(Shutdown::Both);
+ });
+}
+
+#[test]
+fn the_count_shows_the_samples_of_a_lost_connection() {
+ let out = match outlet("SeqLive2") {
+ Some(o) => Arc::new(o),
+ None => {
+ eprintln!("no local network; skipping");
+ return;
+ }
+ };
+ let real = out.info().clone();
+ let proxy = match Proxy::start(real.v4data_port) {
+ Some(p) => p,
+ None => {
+ eprintln!("no local network; skipping");
+ return;
+ }
+ };
+ let mut via_proxy = real.clone();
+ via_proxy.v4address = "127.0.0.1".to_string();
+ via_proxy.v4data_port = proxy.port;
+ let mut inlet = Inlet::open_recovering(&via_proxy, Duration::from_secs(5), 100_000)
+ .expect("the inlet connects through the proxy");
+ assert!(out.wait_for_consumers(Duration::from_secs(5)));
+
+ // A source thread pushes one sample each 200 us.
+ let pushed = Arc::new(AtomicUsize::new(0));
+ let stop = Arc::new(AtomicBool::new(false));
+ let source = {
+ let (out, pushed, stop) = (Arc::clone(&out), Arc::clone(&pushed), Arc::clone(&stop));
+ std::thread::spawn(move || {
+ let mut k = 0;
+ while !stop.load(Ordering::SeqCst) {
+ out.push(&sample(k));
+ k += 1;
+ pushed.store(k, Ordering::SeqCst);
+ std::thread::sleep(Duration::from_micros(200));
+ }
+ })
+ };
+
+ let mut got = pull_until(&mut inlet, 50, Duration::from_secs(5));
+ assert!(!got.is_empty(), "samples arrive before the cut");
+ proxy.cut();
+ // Wait for samples from after the recovery.
+ let cut_at = pushed.load(Ordering::SeqCst);
+ let end = Instant::now() + Duration::from_secs(10);
+ while Instant::now() < end && got.last().map(value).unwrap_or(0) < cut_at + 200 {
+ let mut block = Vec::new();
+ let _ = inlet.pull_chunk(&mut block, 100_000, Duration::from_millis(20));
+ got.extend(block);
+ }
+ stop.store(true, Ordering::SeqCst);
+ source.join().unwrap();
+ let last = pushed.load(Ordering::SeqCst) - 1;
+ if got.last().map(value) != Some(last) {
+ got.extend(pull_until(&mut inlet, last, Duration::from_secs(5)));
+ }
+ assert_eq!(got.last().map(value), Some(last), "the last sample arrives");
+
+ assert!(inlet.recoveries() >= 1, "the inlet connected again");
+ let first = value(&got[0]);
+ let lost = inlet.samples_lost().expect("a count after the recovery");
+ let dropped = inlet.samples_dropped();
+ let expected = (last - first + 1) as u64;
+ println!(
+ "pushed {expected} after the first received, received {}, lost {lost}, dropped {dropped}",
+ got.len()
+ );
+ assert_eq!(got.len() as u64 + lost + dropped, expected);
+}
+
+/// Open a feed by hand, and give the answer features and the first byte after
+/// the test pattern.
+fn raw_feed(out: &Outlet, offer: Vec) -> (Vec, u8) {
+ let info = out.info();
+ let mut stream =
+ TcpStream::connect(("127.0.0.1", info.v4data_port)).expect("the data port answers");
+ stream
+ .set_read_timeout(Some(Duration::from_secs(5)))
+ .unwrap();
+ let params = FeedParams::new(&info.uid, info.format);
+ let (mut client, request) = FeedClient::start_with(params, info.format, 1, offer);
+ stream.write_all(&request).unwrap();
+
+ let mut buf = Vec::new();
+ let mut tmp = [0u8; 4096];
+ loop {
+ match client.on_headers(&buf) {
+ Ok(used) => {
+ buf.drain(..used);
+ break;
+ }
+ Err(labstream_proto::header::Error::Incomplete) => {}
+ Err(e) => panic!("{e}"),
+ }
+ let n = stream.read(&mut tmp).unwrap();
+ assert!(n > 0, "the outlet closed in the headers");
+ buf.extend_from_slice(&tmp[..n]);
+ }
+ loop {
+ match client.on_test_pattern(&buf) {
+ Ok(used) => {
+ buf.drain(..used);
+ break;
+ }
+ Err(TestPatternError::Incomplete) => {}
+ Err(e) => panic!("{e:?}"),
+ }
+ let n = stream.read(&mut tmp).unwrap();
+ buf.extend_from_slice(&tmp[..n]);
+ }
+ // The consumer exists now. One push gives the first data byte.
+ let end = Instant::now() + Duration::from_secs(5);
+ while buf.is_empty() && Instant::now() < end {
+ out.push(&sample(1));
+ let _ = stream.set_read_timeout(Some(Duration::from_millis(50)));
+ if let Ok(n) = stream.read(&mut tmp) {
+ buf.extend_from_slice(&tmp[..n]);
+ }
+ }
+ (client.features().to_vec(), buf[0])
+}
+
+#[test]
+fn a_request_without_the_header_gets_plain_samples() {
+ let out = match outlet("SeqLive3") {
+ Some(o) => o,
+ None => {
+ eprintln!("no local network; skipping");
+ return;
+ }
+ };
+ let (agreed, first) = raw_feed(&out, Vec::new());
+ assert!(agreed.is_empty());
+ assert!(
+ first == 1 || first == 2,
+ "a sample tag, not a record: {first}"
+ );
+
+ let (agreed, first) = raw_feed(&out, vec![Token::new(features::SEQ, 1)]);
+ assert!(features::has(&agreed, features::SEQ, 1));
+ assert_eq!(first, seq::TAG, "a numbered feed starts with a record");
+}
+
+#[test]
+fn a_gap_shows_at_once_on_a_quiet_stream() {
+ // A marker stream can stay quiet for minutes. The loss of a lost
+ // connection must show when the inlet connects again, not at the next
+ // sample.
+ let out = match outlet("SeqLive4") {
+ Some(o) => o,
+ None => {
+ eprintln!("no local network; skipping");
+ return;
+ }
+ };
+ let real = out.info().clone();
+ let proxy = match Proxy::start(real.v4data_port) {
+ Some(p) => p,
+ None => {
+ eprintln!("no local network; skipping");
+ return;
+ }
+ };
+ let mut via_proxy = real.clone();
+ via_proxy.v4address = "127.0.0.1".to_string();
+ via_proxy.v4data_port = proxy.port;
+ let mut inlet = Inlet::open_recovering(&via_proxy, Duration::from_secs(5), 1000)
+ .expect("the inlet connects through the proxy");
+ assert!(out.wait_for_consumers(Duration::from_secs(5)));
+ out.push_samples((0..10).map(sample).collect());
+ assert_eq!(pull_until(&mut inlet, 9, Duration::from_secs(5)).len(), 10);
+
+ // Cut the connection, and hold the inlet off while 20 samples go out.
+ proxy.paused.store(true, Ordering::SeqCst);
+ proxy.cut();
+ std::thread::sleep(Duration::from_millis(100));
+ out.push_samples((10..30).map(sample).collect());
+ std::thread::sleep(Duration::from_millis(300));
+ proxy.paused.store(false, Ordering::SeqCst);
+
+ // No sample goes out after this point.
+ let end = Instant::now() + Duration::from_secs(10);
+ while inlet.samples_lost() != Some(20) && Instant::now() < end {
+ std::thread::sleep(Duration::from_millis(20));
+ }
+ assert!(inlet.recoveries() >= 1, "the inlet connected again");
+ assert_eq!(
+ inlet.samples_lost(),
+ Some(20),
+ "the gap shows with no new sample"
+ );
+}
+
+#[test]
+fn a_new_outlet_starts_a_new_count() {
+ // The second outlet has its own counter. It pushes 1000 samples before
+ // the inlet finds it. If the inlet kept the expected number of the first
+ // outlet, those 1000 would show as lost.
+ let make = || outlet("SeqLive5");
+ let first = match make() {
+ Some(o) => o,
+ None => {
+ eprintln!("no local network; skipping");
+ return;
+ }
+ };
+ let mut inlet = Inlet::open_recovering(first.info(), Duration::from_secs(5), 100_000)
+ .expect("the inlet connects");
+ assert!(first.wait_for_consumers(Duration::from_secs(5)));
+ first.push_samples((0..5).map(sample).collect());
+ assert_eq!(pull_until(&mut inlet, 4, Duration::from_secs(5)).len(), 5);
+ drop(first);
+
+ let second = make().expect("the second outlet opens");
+ second.push_samples((0..1000).map(sample).collect());
+ let mut k = 1000;
+ let mut got = Vec::new();
+ let end = Instant::now() + Duration::from_secs(20);
+ while got.is_empty() && Instant::now() < end {
+ second.push(&sample(k));
+ k += 1;
+ let _ = inlet.pull_chunk(&mut got, 100_000, Duration::from_millis(20));
+ }
+ assert!(!got.is_empty(), "samples of the second outlet arrive");
+ assert_eq!(inlet.current_info().uid, second.info().uid);
+ assert_eq!(inlet.samples_lost(), Some(0), "the count starts again");
+}
diff --git a/crates/labstream-proto/src/features.rs b/crates/labstream-proto/src/features.rs
new file mode 100644
index 0000000..096e9ce
--- /dev/null
+++ b/crates/labstream-proto/src/features.rs
@@ -0,0 +1,214 @@
+//! The feature header between two labstream peers. `docs/extensions.md`.
+//!
+//! A labstream inlet offers features in the request header
+//! `Labstream-Features`, and a labstream outlet answers the ones that it
+//! accepts. liblsl reads only the header keys that it knows, on both sides
+//! (`src/tcp_server.cpp:605-633`, `src/data_receiver.cpp:215-253`), so a
+//! liblsl peer ignores the header and the connection stays plain LSL.
+//!
+//! Both parsers cut a header line at the first `;` and convert it to
+//! lowercase (`src/tcp_server.cpp:610-613`, `crate::header`). A token is
+//! therefore lowercase, and a parameter is hexadecimal.
+
+/// The header name, as it goes on the wire.
+pub const HEADER: &str = "Labstream-Features";
+
+/// The header name, as [`crate::Headers`] stores it.
+pub const HEADER_KEY: &str = "labstream-features";
+
+/// The name of the sequence number feature. `crate::seq`.
+pub const SEQ: &str = "seq";
+
+/// The features that this library implements, each with its versions.
+pub const SUPPORTED: &[(&str, &[u32])] = &[(SEQ, &[1])];
+
+/// One feature with a version, and an optional parameter.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct Token {
+ /// The feature name: `a-z`, `0-9`, and `-`.
+ pub name: String,
+ /// The version of the feature.
+ pub version: u32,
+ /// A hexadecimal parameter, in lowercase.
+ pub param: Option,
+}
+
+impl Token {
+ /// A token with no parameter.
+ pub fn new(name: &str, version: u32) -> Self {
+ Token {
+ name: name.to_string(),
+ version,
+ param: None,
+ }
+ }
+
+ /// Read one token. The result is `None` if the token does not match the
+ /// syntax.
+ pub fn parse(text: &str) -> Option {
+ let (head, param) = match text.split_once('=') {
+ Some((h, p)) => (h, Some(p)),
+ None => (text, None),
+ };
+ let (name, version) = head.split_once('/')?;
+ let name_ok = !name.is_empty()
+ && name
+ .bytes()
+ .all(|b| b.is_ascii_lowercase() || b.is_ascii_digit() || b == b'-');
+ let version_ok = !version.is_empty() && version.bytes().all(|b| b.is_ascii_digit());
+ if !name_ok || !version_ok {
+ return None;
+ }
+ let param = match param {
+ Some(p)
+ if !p.is_empty() && p.bytes().all(|b| matches!(b, b'0'..=b'9' | b'a'..=b'f')) =>
+ {
+ Some(p.to_string())
+ }
+ Some(_) => return None,
+ None => None,
+ };
+ Some(Token {
+ name: name.to_string(),
+ version: version.parse().ok()?,
+ param,
+ })
+ }
+
+ /// Write the token as it goes on the wire.
+ pub fn to_wire(&self) -> String {
+ match &self.param {
+ Some(p) => format!("{}/{}={}", self.name, self.version, p),
+ None => format!("{}/{}", self.name, self.version),
+ }
+ }
+}
+
+/// Read a header value. A token with a bad form is left out.
+pub fn parse(value: &str) -> Vec {
+ value
+ .split_ascii_whitespace()
+ .filter_map(Token::parse)
+ .collect()
+}
+
+/// Write a whole header line, with its line end.
+pub fn header_line(tokens: &[Token]) -> String {
+ let list: Vec = tokens.iter().map(Token::to_wire).collect();
+ format!("{HEADER}: {}\r\n", list.join(" "))
+}
+
+/// The tokens that this process offers: each supported feature that the
+/// configuration allows, at each supported version.
+pub fn offer(allowed: &[String]) -> Vec {
+ SUPPORTED
+ .iter()
+ .filter(|(name, _)| allowed.iter().any(|a| a == name))
+ .flat_map(|(name, versions)| versions.iter().map(|v| Token::new(name, *v)))
+ .collect()
+}
+
+/// The outlet's answer to an offer.
+///
+/// The answer holds only offered tokens. For each name it holds at most one
+/// version: the highest version that both sides support. A feature that the
+/// configuration does not allow is left out.
+pub fn answer(offered: &[Token], allowed: &[String]) -> Vec {
+ let mut out: Vec = Vec::new();
+ for (name, versions) in SUPPORTED {
+ if !allowed.iter().any(|a| a == name) {
+ continue;
+ }
+ let best = offered
+ .iter()
+ .filter(|t| t.name == *name && versions.contains(&t.version) && t.param.is_none())
+ .max_by_key(|t| t.version);
+ if let Some(t) = best {
+ out.push(t.clone());
+ }
+ }
+ out
+}
+
+/// The features that are on, from what the inlet offered and what the outlet
+/// answered.
+///
+/// An answer token that was not offered is left out. A feature is on only
+/// when both sides named it.
+pub fn agreed(offered: &[Token], answered: &[Token]) -> Vec {
+ let mut out: Vec = Vec::new();
+ for t in answered {
+ let was_offered = offered
+ .iter()
+ .any(|o| o.name == t.name && o.version == t.version);
+ if was_offered && !out.iter().any(|x| x.name == t.name) {
+ out.push(t.clone());
+ }
+ }
+ out
+}
+
+/// True when the list holds the feature at this version.
+pub fn has(tokens: &[Token], name: &str, version: u32) -> bool {
+ tokens
+ .iter()
+ .any(|t| t.name == name && t.version == version)
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ fn all() -> Vec {
+ vec![SEQ.to_string()]
+ }
+
+ #[test]
+ fn a_token_reads_back_as_it_was_written() {
+ for text in ["seq/1", "shm/1=0a1b2c", "x-y2/10"] {
+ assert_eq!(Token::parse(text).unwrap().to_wire(), text);
+ }
+ }
+
+ #[test]
+ fn a_bad_token_is_left_out() {
+ let got = parse("seq/1 SEQ/1 seq/ /1 seq/x shm/1=XYZ shm/1= seq/2");
+ assert_eq!(got, vec![Token::new("seq", 1), Token::new("seq", 2)]);
+ }
+
+ #[test]
+ fn the_header_line_is_lowercase_safe_and_has_no_semicolon() {
+ let line = header_line(&[Token::new("seq", 1)]);
+ assert_eq!(line, "Labstream-Features: seq/1\r\n");
+ // Both parsers cut the line at `;` and convert it to lowercase. The
+ // value must read the same after that.
+ let value = line.split_once(':').unwrap().1.trim();
+ assert!(!value.contains(';'));
+ assert_eq!(parse(&value.to_ascii_lowercase()), parse(value));
+ }
+
+ #[test]
+ fn the_answer_holds_only_offered_and_allowed_features() {
+ let offered = parse("seq/1 seq/7 shm/1=00ff");
+ assert_eq!(answer(&offered, &all()), vec![Token::new("seq", 1)]);
+ assert!(answer(&offered, &[]).is_empty());
+ assert!(answer(&parse("shm/1"), &all()).is_empty());
+ assert!(answer(&parse("seq/9"), &all()).is_empty());
+ }
+
+ #[test]
+ fn a_feature_is_on_only_when_both_sides_name_it() {
+ let offered = offer(&all());
+ assert_eq!(offered, vec![Token::new("seq", 1)]);
+ assert!(has(&agreed(&offered, &parse("seq/1")), SEQ, 1));
+ assert!(agreed(&offered, &parse("seq/2")).is_empty());
+ assert!(agreed(&offered, &[]).is_empty());
+ assert!(agreed(&[], &parse("seq/1")).is_empty());
+ assert_eq!(agreed(&offered, &parse("seq/1 seq/1")).len(), 1);
+ }
+
+ #[test]
+ fn the_configuration_can_turn_every_feature_off() {
+ assert!(offer(&[]).is_empty());
+ }
+}
diff --git a/crates/labstream-proto/src/feed.rs b/crates/labstream-proto/src/feed.rs
index 14a46e7..8c31c9e 100644
--- a/crates/labstream-proto/src/feed.rs
+++ b/crates/labstream-proto/src/feed.rs
@@ -3,6 +3,7 @@
//! The machine takes bytes and returns bytes. It opens no socket and reads no
//! clock, so a test drives every state with a byte slice.
+use crate::features::{self, Token};
use crate::header::{parse_block, Error, Headers, StatusLine};
use crate::negotiate::{BIG, LITTLE};
use labstream_wire::{ByteOrder, Codec, Format, Sample, TEST_PATTERN_OFFSETS};
@@ -99,6 +100,20 @@ impl FeedParams {
s.push_str("\r\n");
s.into_bytes()
}
+
+ /// Write the request with a `Labstream-Features` line, after the fields
+ /// of liblsl. With no tokens, the request is the same as
+ /// [`FeedParams::to_wire`]. `docs/extensions.md`.
+ pub fn to_wire_with(&self, features: &[Token]) -> Vec {
+ let mut bytes = self.to_wire();
+ if !features.is_empty() {
+ // Put the line before the empty line that ends the block.
+ bytes.truncate(bytes.len() - 2);
+ bytes.extend_from_slice(features::header_line(features).as_bytes());
+ bytes.extend_from_slice(b"\r\n");
+ }
+ bytes
+ }
}
/// The parameters that the answer settled.
@@ -135,12 +150,29 @@ pub struct FeedClient {
state: State,
agreement: Option,
codec: Option,
+ /// The features that the request offered.
+ offer: Vec,
+ /// The features that are on, once the headers arrive.
+ features: Vec,
}
impl FeedClient {
/// Build a client and return the bytes to send.
pub fn start(params: FeedParams, format: Format, channels: usize) -> (Self, Vec) {
- let bytes = params.to_wire();
+ Self::start_with(params, format, channels, Vec::new())
+ }
+
+ /// Build a client that offers features, and return the bytes to send.
+ ///
+ /// With no tokens, this is the same as [`FeedClient::start`].
+ /// `docs/extensions.md`.
+ pub fn start_with(
+ params: FeedParams,
+ format: Format,
+ channels: usize,
+ offer: Vec,
+ ) -> (Self, Vec) {
+ let bytes = params.to_wire_with(&offer);
(
FeedClient {
params,
@@ -149,11 +181,19 @@ impl FeedClient {
state: State::AwaitingHeaders,
agreement: None,
codec: None,
+ offer,
+ features: Vec::new(),
},
bytes,
)
}
+ /// The features that are on for this connection. Empty until the headers
+ /// arrive, and empty when the outlet gave no answer for them.
+ pub fn features(&self) -> &[Token] {
+ &self.features
+ }
+
/// The current state.
pub fn state(&self) -> State {
self.state
@@ -201,6 +241,13 @@ impl FeedClient {
};
let agreement = self.read_answer(&headers)?;
+ // An outlet that does not know the header sends no answer for it, so
+ // no feature is on.
+ let answered = headers
+ .get(features::HEADER_KEY)
+ .map(features::parse)
+ .unwrap_or_default();
+ self.features = features::agreed(&self.offer, &answered);
let order = agreement.order;
self.codec = Some(
Codec::new(self.format, self.channels, order)
@@ -353,7 +400,7 @@ pub enum TestPatternError {
mod tests {
use super::*;
use crate::header::parse_block;
- use crate::negotiate::{negotiate, FeedRequest, Outcome, ServerStream};
+ use crate::negotiate::{negotiate, Accepted, FeedRequest, Outcome, ServerStream};
fn handshake(
format: Format,
@@ -418,6 +465,82 @@ mod tests {
assert!(text.ends_with("\r\n\r\n"));
}
+ /// Run the feature exchange through both header parsers, as the outlet
+ /// and the inlet do. `answer_features` is the server side decision.
+ fn feature_handshake(offer: Vec, allowed: &[String]) -> FeedClient {
+ let p = FeedParams::new("uid-1", Format::Float32);
+ let (mut client, request) = FeedClient::start_with(p, Format::Float32, 2, offer);
+ let block_start = request.iter().position(|&b| b == b'\n').unwrap() + 1;
+ let (headers, _) = parse_block(&request[block_start..]).expect("a block");
+ let srv = ServerStream::new("uid-1", Format::Float32, LITTLE, 1000.0);
+ let req = FeedRequest::from_headers(110, "uid-1", &headers, srv.channel_bytes);
+ let accepted = match negotiate(&req, &srv) {
+ Outcome::Accept(a) => a,
+ Outcome::Refuse(s) => panic!("refused: {}", s.code),
+ };
+ let answered = headers
+ .get(features::HEADER_KEY)
+ .map(|v| features::answer(&features::parse(v), allowed));
+ let answer = accepted.to_wire_with(110, "uid-1", answered.as_deref());
+ client.on_headers(answer.as_bytes()).expect("headers");
+ client
+ }
+
+ #[test]
+ fn a_request_with_no_offer_is_the_plain_request() {
+ let p = FeedParams::new("abc", Format::Float32);
+ assert_eq!(p.to_wire_with(&[]), p.to_wire());
+ }
+
+ #[test]
+ fn the_offer_goes_last_in_the_block() {
+ let p = FeedParams::new("abc", Format::Float32);
+ let text = String::from_utf8(p.to_wire_with(&[Token::new("seq", 1)])).unwrap();
+ assert!(text.ends_with("Session-Id: default\r\nLabstream-Features: seq/1\r\n\r\n"));
+ assert!(text.starts_with(&String::from_utf8(p.to_wire()).unwrap()[..40]));
+ }
+
+ #[test]
+ fn two_labstream_peers_agree_on_seq() {
+ let all = vec![features::SEQ.to_string()];
+ let c = feature_handshake(features::offer(&all), &all);
+ assert!(features::has(c.features(), features::SEQ, 1));
+ }
+
+ #[test]
+ fn an_outlet_that_allows_nothing_turns_seq_off() {
+ let all = vec![features::SEQ.to_string()];
+ let c = feature_handshake(features::offer(&all), &[]);
+ assert!(c.features().is_empty());
+ }
+
+ #[test]
+ fn an_answer_with_no_feature_line_turns_seq_off() {
+ // A liblsl outlet and an older labstream outlet answer this way.
+ let all = vec![features::SEQ.to_string()];
+ let p = FeedParams::new("uid-1", Format::Float32);
+ let (mut c, _) = FeedClient::start_with(p, Format::Float32, 2, features::offer(&all));
+ c.on_headers(b"LSL/110 200 OK\r\nUID: uid-1\r\nByte-Order: 1234\r\nSuppress-Subnormals: 0\r\nData-Protocol-Version: 110\r\n\r\n")
+ .expect("headers");
+ assert!(c.features().is_empty());
+ }
+
+ #[test]
+ fn an_answer_with_no_request_line_has_no_feature_line() {
+ let a = Accepted {
+ data_protocol_version: 110,
+ byte_order: LITTLE,
+ reverse_byte_order: false,
+ suppress_subnormals: false,
+ max_buffer_length: 360,
+ max_chunk_length: 0,
+ };
+ assert_eq!(a.to_wire_with(110, "u", None), a.to_wire(110, "u"));
+ assert!(a
+ .to_wire_with(110, "u", Some(&[]))
+ .contains("Labstream-Features: \r\n"));
+ }
+
#[test]
fn a_full_handshake_reaches_the_streaming_state() {
let c = handshake(Format::Float32, 8, LITTLE, 0.0);
diff --git a/crates/labstream-proto/src/lib.rs b/crates/labstream-proto/src/lib.rs
index 3bc9a8d..d579a9e 100644
--- a/crates/labstream-proto/src/lib.rs
+++ b/crates/labstream-proto/src/lib.rs
@@ -24,9 +24,11 @@
pub mod canon;
pub mod discovery;
+pub mod features;
pub mod feed;
pub mod header;
pub mod negotiate;
+pub mod seq;
pub mod timesync;
pub use header::{Error, Headers, StatusAction, StatusLine};
diff --git a/crates/labstream-proto/src/negotiate.rs b/crates/labstream-proto/src/negotiate.rs
index 922f4ca..dbc8b9f 100644
--- a/crates/labstream-proto/src/negotiate.rs
+++ b/crates/labstream-proto/src/negotiate.rs
@@ -176,6 +176,26 @@ impl Accepted {
s.push_str("\r\n");
s
}
+
+ /// Write the answer with a `Labstream-Features` line.
+ ///
+ /// `features` is `None` when the request had no such header. The answer
+ /// is then the same as [`Accepted::to_wire`]. A request with the header
+ /// gets the line, also when no feature is on. `docs/extensions.md`.
+ pub fn to_wire_with(
+ &self,
+ configured_version: i32,
+ uid: &str,
+ features: Option<&[crate::features::Token]>,
+ ) -> String {
+ let mut s = self.to_wire(configured_version, uid);
+ if let Some(tokens) = features {
+ s.truncate(s.len() - 2);
+ s.push_str(&crate::features::header_line(tokens));
+ s.push_str("\r\n");
+ }
+ s
+ }
}
/// True when the format carries a subnormal value.
diff --git a/crates/labstream-proto/src/seq.rs b/crates/labstream-proto/src/seq.rs
new file mode 100644
index 0000000..8957f27
--- /dev/null
+++ b/crates/labstream-proto/src/seq.rs
@@ -0,0 +1,257 @@
+//! The sequence numbers of the `seq/1` feature. `docs/extensions.md`.
+//!
+//! A numbering record can stand between two samples. It gives the number of
+//! the next sample. The outlet writes one record at the start of each
+//! connection, and one more before each sample whose number is not one more
+//! than the number of the sample before it. The inlet counts the numbers
+//! that never arrived.
+
+/// The first byte of a numbering record.
+///
+/// The sample tags are 1 and 2 (`src/sample.h:19-20`, SPEC.md 7.1). This
+/// value is neither, so the first byte tells a record from a sample.
+pub const TAG: u8 = 0xFE;
+
+/// The length of a numbering record in bytes.
+pub const RECORD_LEN: usize = 9;
+
+/// Append a record that gives `number` to the next sample.
+///
+/// The number is always little-endian. The byte order of the connection does
+/// not apply to it.
+pub fn write_record(out: &mut Vec, number: u64) {
+ out.push(TAG);
+ out.extend_from_slice(&number.to_le_bytes());
+}
+
+/// What starts at a position in the sample stream.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum Next {
+ /// A complete record, with its number.
+ Record(u64),
+ /// A record that is cut. The caller reads more bytes.
+ Incomplete,
+ /// No record. The bytes start a sample, or nothing.
+ Sample,
+}
+
+/// Look at the start of `buf` for a record.
+pub fn peek(buf: &[u8]) -> Next {
+ match buf.first() {
+ Some(&TAG) if buf.len() >= RECORD_LEN => {
+ let mut b = [0u8; 8];
+ b.copy_from_slice(&buf[1..RECORD_LEN]);
+ Next::Record(u64::from_le_bytes(b))
+ }
+ Some(&TAG) => Next::Incomplete,
+ _ => Next::Sample,
+ }
+}
+
+/// The count of lost samples on the inlet side.
+///
+/// The counter keeps the number that it expects next. A record above that
+/// number adds the difference to the loss. Each sample moves the expected
+/// number by one.
+#[derive(Debug, Clone, Default, PartialEq, Eq)]
+pub struct Counter {
+ expected: Option,
+ lost: u64,
+ backwards: u64,
+}
+
+impl Counter {
+ /// A counter with no expected number yet.
+ pub fn new() -> Self {
+ Counter::default()
+ }
+
+ /// Read a record.
+ ///
+ /// The first record sets the expected number and counts no loss. A number
+ /// below the expected number counts no loss: it adds one to
+ /// [`Counter::backwards`], and the counter takes the new number.
+ pub fn record(&mut self, number: u64) {
+ if let Some(e) = self.expected {
+ if number > e {
+ self.lost = self.lost.saturating_add(number - e);
+ } else if number < e {
+ self.backwards = self.backwards.saturating_add(1);
+ }
+ }
+ self.expected = Some(number);
+ }
+
+ /// Count one sample.
+ pub fn sample(&mut self) {
+ if let Some(e) = self.expected {
+ self.expected = Some(e.saturating_add(1));
+ }
+ }
+
+ /// Forget the expected number. A new outlet has a new counter.
+ pub fn restart(&mut self) {
+ self.expected = None;
+ }
+
+ /// The samples that never arrived, since the counter was made.
+ pub fn lost(&self) -> u64 {
+ self.lost
+ }
+
+ /// How many records gave a number below the expected one.
+ pub fn backwards(&self) -> u64 {
+ self.backwards
+ }
+
+ /// The number that the counter expects next, if it has one.
+ pub fn expected(&self) -> Option {
+ self.expected
+ }
+}
+
+/// The record decision on the outlet side, for one connection.
+///
+/// The writer calls [`Numbering::before`] with the number of each sample that
+/// it is about to write. The result tells whether a record goes first.
+#[derive(Debug, Clone, Default, PartialEq, Eq)]
+pub struct Numbering {
+ next: Option,
+}
+
+impl Numbering {
+ /// A new connection, which starts with a record.
+ pub fn new() -> Self {
+ Numbering::default()
+ }
+
+ /// Write the record that opens a connection. `number` is the number
+ /// that the next sample will get.
+ ///
+ /// The record goes out at once, before any sample. A gap that happened
+ /// before this connection is then visible to the inlet at once, also on
+ /// a stream that sends no more samples for a long time.
+ pub fn start(&mut self, number: u64, out: &mut Vec) {
+ write_record(out, number);
+ self.next = Some(number);
+ }
+
+ /// Write a record into `out` if the sample with `number` needs one, then
+ /// expect the number after it.
+ pub fn before(&mut self, number: u64, out: &mut Vec) {
+ if self.next != Some(number) {
+ write_record(out, number);
+ }
+ self.next = Some(number.wrapping_add(1));
+ }
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ #[test]
+ fn a_record_reads_back() {
+ for n in [0u64, 1, 255, 1 << 40, u64::MAX] {
+ let mut out = Vec::new();
+ write_record(&mut out, n);
+ assert_eq!(out.len(), RECORD_LEN);
+ assert_eq!(peek(&out), Next::Record(n));
+ }
+ }
+
+ #[test]
+ fn the_number_is_little_endian() {
+ let mut out = Vec::new();
+ write_record(&mut out, 0x0102_0304_0506_0708);
+ assert_eq!(out, [0xFE, 8, 7, 6, 5, 4, 3, 2, 1]);
+ }
+
+ #[test]
+ fn a_cut_record_asks_for_more_bytes() {
+ let mut out = Vec::new();
+ write_record(&mut out, 42);
+ for cut in 1..RECORD_LEN {
+ assert_eq!(peek(&out[..cut]), Next::Incomplete);
+ }
+ assert_eq!(peek(&[]), Next::Sample);
+ assert_eq!(peek(&[1, 0, 0]), Next::Sample);
+ assert_eq!(peek(&[2]), Next::Sample);
+ }
+
+ #[test]
+ fn the_first_record_counts_no_loss() {
+ let mut c = Counter::new();
+ c.record(1000);
+ assert_eq!(c.lost(), 0);
+ assert_eq!(c.expected(), Some(1000));
+ }
+
+ #[test]
+ fn a_gap_counts_the_missing_numbers() {
+ let mut c = Counter::new();
+ c.record(10);
+ c.sample(); // 10
+ c.sample(); // 11
+ c.record(15); // 12, 13, 14 are lost
+ c.sample();
+ assert_eq!(c.lost(), 3);
+ assert_eq!(c.expected(), Some(16));
+ }
+
+ #[test]
+ fn a_number_that_goes_back_counts_no_loss_and_does_not_underflow() {
+ let mut c = Counter::new();
+ c.record(100);
+ c.sample();
+ c.record(5);
+ assert_eq!(c.lost(), 0);
+ assert_eq!(c.backwards(), 1);
+ assert_eq!(c.expected(), Some(5));
+ }
+
+ #[test]
+ fn a_restart_takes_a_new_baseline() {
+ let mut c = Counter::new();
+ c.record(50);
+ c.restart();
+ c.record(0);
+ c.record(3);
+ assert_eq!(c.lost(), 3);
+ assert_eq!(c.backwards(), 0);
+ }
+
+ #[test]
+ fn a_started_connection_needs_no_second_record_for_the_next_number() {
+ let mut w = Numbering::new();
+ let mut out = Vec::new();
+ w.start(30, &mut out);
+ assert_eq!(peek(&out), Next::Record(30));
+ let mut more = Vec::new();
+ w.before(30, &mut more);
+ assert!(more.is_empty(), "the next sample follows the record");
+ w.before(35, &mut more);
+ assert_eq!(peek(&more), Next::Record(35));
+ }
+
+ #[test]
+ fn the_writer_and_the_counter_agree() {
+ // The numbers that a writer sends, with gaps from dropped samples.
+ let numbers = [7u64, 8, 9, 12, 13, 20, 21, 22];
+ let mut w = Numbering::new();
+ let mut c = Counter::new();
+ let mut records = 0;
+ for n in numbers {
+ let mut out = Vec::new();
+ w.before(n, &mut out);
+ if let Next::Record(r) = peek(&out) {
+ records += 1;
+ c.record(r);
+ }
+ c.sample();
+ }
+ assert_eq!(records, 3, "one at the start and one at each gap");
+ assert_eq!(c.lost(), 2 + 6);
+ assert_eq!(c.expected(), Some(23));
+ }
+}
diff --git a/crates/labstream/src/inlet.rs b/crates/labstream/src/inlet.rs
index c9bf730..2a8331a 100644
--- a/crates/labstream/src/inlet.rs
+++ b/crates/labstream/src/inlet.rs
@@ -229,6 +229,20 @@ impl Inlet {
self.inner.samples_dropped()
}
+ /// How many samples never reached this inlet, since it opened.
+ ///
+ /// Two labstream peers number their samples (the `seq/1` feature of
+ /// `docs/extensions.md`). The count shows a sample that the outlet
+ /// dropped because this inlet read too slowly, and the samples that went
+ /// out while the connection was lost. [`Inlet::dropped`] counts the
+ /// samples that this inlet dropped itself. The total loss is the sum.
+ ///
+ /// The value is `None` when the source does not number its samples, for
+ /// example a liblsl outlet. `None` means unknown, not zero.
+ pub fn lost(&self) -> Option {
+ self.inner.samples_lost()
+ }
+
/// True when the source ended and the program read every sample.
///
/// An inlet that recovers reconnects on its own, so this stays false while
diff --git a/docs/extensions.md b/docs/extensions.md
new file mode 100644
index 0000000..e6e10e9
--- /dev/null
+++ b/docs/extensions.md
@@ -0,0 +1,288 @@
+# Proposal: feature negotiation between two labstream peers
+
+**Status:** proposal. The header and the `seq` feature are implemented on
+the branch `feat/seq`. The other features are not implemented. SPEC.md gets
+a section for a feature only after the feature is accepted.
+
+## The purpose
+
+Some improvements need a change to the data channel. Examples are sequence
+numbers that make sample loss visible, and a shared-memory transport for two
+processes on one machine. liblsl does not know these changes.
+
+This page defines how a labstream inlet and a labstream outlet agree to use
+such a feature. The agreement must leave every other pair unchanged:
+
+| Outlet | Inlet | Result |
+|---|---|---|
+| liblsl | liblsl | plain LSL, as today |
+| liblsl | labstream | plain LSL |
+| labstream | liblsl | plain LSL |
+| labstream 0.1.2 or earlier | labstream | plain LSL |
+| labstream | labstream | plain LSL, plus each feature that both ends accept |
+
+## What liblsl does with an extra header
+
+These facts come from `conformance/liblsl/` at `e651023c`.
+
+1. The feed server reads each request header line, and acts only on the keys
+ that it knows. An unknown key has no effect
+ (`src/tcp_server.cpp:605-633`).
+2. The feed client reads each answer header line the same way, and acts only
+ on the keys that it knows (`src/data_receiver.cpp:215-253`).
+3. Both sides cut a header line at the first `;`, and convert the line to
+ lowercase before they compare the key (`src/tcp_server.cpp:610-613`,
+ `src/data_receiver.cpp:220-223`).
+4. Both sides read a header line into a buffer of 16384 bytes
+ (`src/tcp_server.cpp:604`, `src/data_receiver.cpp:193`).
+5. The labstream parser cuts and converts the same way
+ (`crates/labstream-proto/src/header.rs:103-107`).
+
+As a result, a liblsl outlet ignores an extra request header, and a liblsl
+inlet ignores an extra answer header. Item 3 limits the syntax of the header.
+A value must not contain `;`, and a value must not depend on letter case.
+
+## The header
+
+### The request
+
+A labstream inlet adds one header line to its feed request:
+
+```
+Labstream-Features: seq/1 shm/1
+```
+
+The value is a list of tokens with one space between two tokens. Each token
+has this form:
+
+```
+token = name "/" version [ "=" param ]
+name = 1*( a-z / 0-9 / "-" )
+version = 1*( 0-9 )
+param = 1*( 0-9 / a-f )
+```
+
+A parameter is hexadecimal, because the header line loses its letter case.
+The whole line must stay below 16384 bytes. An inlet can offer more than one
+version of a feature, for example `seq/1 seq/2`.
+
+### The answer
+
+A labstream outlet that reads the request header adds one line to its answer:
+
+```
+Labstream-Features: seq/1
+```
+
+The answer holds only tokens from the request. For each name, it holds at
+most one version.
+
+### The rules
+
+1. An inlet sends the request header only when it supports one or more
+ features.
+2. An outlet sends the answer header only when the request held one.
+3. An outlet ignores a token that it does not know, or that does not match
+ the syntax.
+4. An inlet ignores an answer token that it did not offer.
+5. A feature is on only when the inlet offered it and the outlet answered it.
+6. If the answer has no `Labstream-Features` line, no feature is on. A liblsl
+ outlet and an older labstream outlet give this result.
+7. The configuration key `labstream.Features` lists the features that this
+ process can use, for example `{seq}`. The default lists every feature that
+ the library has. An inlet offers only the listed features, and an outlet
+ answers only the listed features. The value `{}` turns every feature off.
+ liblsl does not read this key.
+
+## Where the framing changes
+
+After the answer headers, the outlet sends two test pattern samples
+(SPEC.md 6). These two samples always use the plain framing of SPEC.md 7.
+The inlet compares them exactly as today.
+
+A feature can change the framing only from the first byte after the second
+test pattern sample. Thus the test pattern stays a check of the codec, and a
+fault in a feature cannot hide a fault in the codec.
+
+## The scope of an agreement
+
+An agreement holds for one connection. A recovery opens a new connection with
+a new request, so the set of features can change. An outlet that restarts as
+a liblsl program gives an example.
+
+The inlet must report the features of the current connection, and must show
+when the set changes. This works the same way as the clock reset after a
+recovery. The API names are an open question.
+
+## The first features
+
+Each feature below gets its own section and its own conformance checks
+before any code. The text here gives only the requirements that affect the
+negotiation.
+
+### `seq`: sequence numbers
+
+**Status:** implemented on the branch `feat/seq`
+(`crates/labstream-proto/src/seq.rs`). The token is `seq/1`.
+
+#### The purpose
+
+LSL has no sign of a lost sample (SPEC.md 8.7). An application can only
+guess a loss from a gap in the timestamps. `seq` gives each sample a number,
+so the inlet can count the samples that it did not receive.
+
+#### The numbers
+
+1. The outlet gives each pushed sample the next number of one counter. The
+ counter starts at 0 when the outlet opens.
+2. One counter serves the whole outlet, not one counter for each connection.
+ A sample that the outlet pushes with no consumer also takes a number.
+3. The two real causes of loss are a full consumer queue in the outlet
+ (SPEC.md 8.7) and the gap between a lost connection and the next one. A
+ counter for each connection starts again after a recovery, so it shows
+ neither cause. That is the reason for rule 2.
+
+#### The record
+
+When `seq/1` is on, a numbering record can stand between two samples. It
+has 9 bytes:
+
+```
+u8 tag 0xFE
+u64 number little-endian, the number of the next sample
+```
+
+1. The tag values 1 and 2 start a sample (`src/sample.h:19-20`, SPEC.md
+ 7.1). The tag `0xFE` is not a sample tag, so a reader can tell a record
+ from a sample by its first byte.
+2. The number is always little-endian. The `Byte-Order` of the connection
+ does not apply to it.
+3. On each connection, the first record comes directly after the second test
+ pattern sample. The outlet writes it at once, before any sample, with the
+ number that the next sample will get. Each connection thus starts with an
+ absolute number, and a gap before the connection shows at once, also on
+ a stream that sends no more samples.
+4. After that, the outlet writes a record only before a sample whose number
+ is not one more than the number of the sample before it. A connection
+ with no loss carries one record and no more.
+5. A record is not a sample. It does not count toward `Max-Chunk-Length`.
+6. A record that is cut at the end of a read is not an error. The reader
+ waits for the rest of the bytes, as for a cut sample.
+
+#### The count
+
+The inlet keeps the number that it expects next.
+
+1. The first record after the inlet opens sets the expected number, and
+ counts no loss. The inlet has no number from before that point.
+2. A later record with a number above the expected number adds the
+ difference to the count of lost samples.
+3. A later record with a number below the expected number counts no loss.
+ The inlet adds one to a separate count of numbers that went back, and
+ takes the new number. The arithmetic must not underflow.
+4. Each sample adds one to the expected number.
+5. A recovery to the same outlet (the same `uid`) keeps the expected number.
+ The first record of the new connection then shows the gap. Live test:
+ `a_gap_shows_at_once_on_a_quiet_stream`.
+6. A recovery to a new outlet (a new `uid`) starts again at rule 1, because
+ the new outlet has a new counter. Live test:
+ `a_new_outlet_starts_a_new_count`.
+
+#### What the inlet reports
+
+- `Inlet::samples_lost()` in `labstream-net` and `Inlet::lost()` in
+ `labstream` give the count of lost samples since the inlet opened.
+- The value is `None` when the current connection does not use `seq`. A
+ liblsl outlet gives this result. `None` means "unknown". It does not mean
+ "no loss".
+- Version 1 gives a count only. It does not give the position of each gap.
+ An application that must place a gap still uses the timestamps.
+- The inlet queue also drops the oldest sample when the application reads
+ too slowly. This drop happens after the count, so `seq` does not see it.
+ `Inlet::samples_dropped()` in `labstream-net` and `Inlet::dropped()` in
+ `labstream` report it, as before. The total loss is the sum
+ of the two values.
+
+### `shm`: shared memory on one machine
+
+The hostname does not prove that the two processes share a machine. Two
+machines can have the same name, and a container can have the name of its
+host. Thus `shm` needs one more step after the headers:
+
+1. The inlet offers `shm/1`.
+2. The outlet makes a memory segment. It writes a random value into the
+ segment. It answers `shm/1=`.
+3. The inlet opens the segment and reads the random value.
+4. The inlet writes one line on the TCP connection: `shm-ok ` or
+ `shm-no`.
+5. If the value matches, the outlet sends the samples through the segment.
+ Otherwise, or after 1 s with no line, the outlet sends the samples on TCP.
+
+The outlet does not send data before step 5. The TCP connection stays open
+in both cases. It carries the end of the stream and the recovery.
+
+The segment must allow access only by the user that owns the outlet. The
+wake-up method and the code for each platform are not part of this page.
+
+### A clock model with drift
+
+A fit of offset and drift is a choice of the inlet alone. The outlet answers
+the same time probes as today. Thus this feature needs no negotiation, and
+it does not use this header.
+
+## Alternatives that this proposal rejects
+
+**A higher `Data-Protocol-Version`, for example 120.** liblsl uses the lower
+of the two versions (`src/tcp_server.cpp:641`). Thus a liblsl peer falls back
+correctly. But the version numbers belong to liblsl. A future liblsl release
+can use the same number for a different format, and the two ends then agree
+on different things. A version is also one scale, and the features are
+independent.
+
+**A new request line, for example `LSL:labstream-feed`.** A liblsl server
+sends no answer to a request line that it does not know
+(`src/tcp_server.cpp:502-531`). The inlet then needs a timeout and a second
+connection for each liblsl outlet. That adds a delay to each start and to
+each recovery.
+
+**A field in the stream description.** The description goes to every
+consumer, and LabRecorder writes it into each XDF file. A field there changes
+the stored data, and it does not describe one connection.
+
+## The conformance plan
+
+Each item gives its status on the branch `feat/seq`.
+
+1. **liblsl outlet, raw request.** Send a feed request with the header to the
+ oracle outlet. Make sure that the answer and the data bytes are the same
+ as for the request without the header. **Done:** `oracle/headerprobe.py`
+ passes for liblsl and for labstream `main`. It also reads the first data
+ byte: a sample tag (1 or 2) for each outlet, and the record tag `0xFE`
+ only when the answer holds `seq/1`.
+2. **liblsl inlet.** Make sure that a labstream outlet sends no
+ `Labstream-Features` line, and no record, when the request has none.
+ **Done:** `crates/labstream-net/tests/seq_live.rs`,
+ `a_request_without_the_header_gets_plain_samples`. The interop matrix
+ also runs liblsl inlets against the labstream outlet.
+3. **Released labstream 0.1.2.** Run it as a peer in both directions. It
+ knows nothing of the header, so each run must give plain LSL. **Done:**
+ below `crates/`, `main` differs from the tag `v0.1.2` only in one comment.
+ `oracle/headerprobe.py` on a `main` outlet shows no answer line. Item 2
+ covers a 0.1.2 inlet, which sends no header.
+4. **Two labstream peers.** Run each feature on and off, and each mix of
+ offer and answer. **Done:** the unit tests in `feed.rs` and
+ `features.rs` cover each mix. `oracle/interop.py` and its self test pass
+ with `seq` on, and again with `labstream.Features = {}` in a
+ configuration file. `oracle/headerprobe.py` with the feature off gives an
+ empty answer and no other change.
+5. **Syntax.** Send tokens with uppercase letters, with `;`, and with a bad
+ form. Make sure that the outlet ignores each bad token, and keeps the
+ good ones. **Done:** the unit tests in `features.rs`.
+6. **The full interop matrix.** `oracle/interop.py` must give the same result
+ as before, with the header on. **Done:** each mode gives the same count
+ as on `main`.
+
+## Open questions
+
+- The final name of the header.
+- The API that reports the features of the current connection.
diff --git a/docs/latency.md b/docs/latency.md
new file mode 100644
index 0000000..0f3c576
--- /dev/null
+++ b/docs/latency.md
@@ -0,0 +1,137 @@
+# Latency and CPU
+
+This page gives how to measure the time from a push to a pull, and the
+results of the first measurement. Run the measurement again before you claim
+that a change makes the library faster.
+
+## The instrument
+
+`conformance/oracle/latency.c` is one C program for the C ABI. It runs as an
+outlet or as an inlet. The runner `conformance/oracle/latency.py` links it
+once to each library, then runs an outlet process and an inlet process for
+each cell.
+
+- **The clock.** The program reads its own `CLOCK_MONOTONIC`, not the clock
+ of the library. The outlet gives the push time as the timestamp of each
+ sample. The inlet does no post-processing, and records the pull time minus
+ the timestamp.
+- **The chunk.** All samples of one push call get the push time. The latency
+ of a chunk is thus the latency of its last sample to leave.
+- **The pull.** The inlet calls `lsl_pull_sample_f` with a timeout of 3 s. The
+ call returns when a sample arrives, so no poll interval adds latency.
+- **Loss.** Channel 0 carries the sample number. The inlet counts lost,
+ repeated, and reordered samples.
+- **The library.** Each process reports the file of the library that the
+ loader picked. A stale `RUNPATH` once made a test use the wrong library.
+- **CPU.** Each process reports its user and system time, as a percentage of
+ one core, over the time that it sends or receives.
+- **The schedule.** The outlet waits on an absolute schedule, and reports how
+ late each push is. This lag is not part of the latency.
+
+## The control
+
+The control pair is liblsl to liblsl. With `--control`, the runner also runs
+that pair with timestamps that are 1000 µs early. The table must show a delay
+that is 1000 µs larger. On the run below, the delay showed as 966 µs.
+
+## How to run it
+
+Run these commands from `conformance/`. The oracle build must exist
+(`conformance/oracle/README.md`).
+
+```bash
+oracle/latency.py --control
+```
+
+To compare branches, build the C library of each branch in its own worktree
+and target directory. Then give each directory to the runner:
+
+```bash
+oracle/latency.py --lib oracle=.build/install/lib --lib main=DIR1 --lib fix=DIR2 --no-mixed --control
+```
+
+Do not copy a branch build into `.build/rustlib`. Other scripts read that
+directory.
+
+## The first results
+
+Machine: AMD Ryzen 5 PRO 3500U, 8 threads, Linux 6.16, loopback, no other
+load on purpose. Each cell is the median of 3 runs of 10 s, with the range of
+the 3 runs in brackets. The first second of each run is not measured.
+
+Libraries:
+
+- `oracle`: liblsl at `e651023c`.
+- `main`: labstream `a912cef`.
+- `fix`: branch `fix/network-robustness` at `e01e998` (pull request #9).
+- `quick`: branch `perf/quick-wins` at `d6880e4` (pull request #10).
+
+| outlet -> inlet | load | p50 µs | p99 µs | p99.9 µs | max µs | lost | CPU outlet % | CPU inlet % |
+|---|---|---|---|---|---|---|---|---|
+| oracle -> oracle | 512 Hz x 8, chunk 1 | 102 (93-142) | 327 (201-501) | 419 (231-624) | 2150 | 0 | 5.7 | 3.4 |
+| main -> main | 512 Hz x 8, chunk 1 | 96 (94-96) | 212 (204-217) | 465 (260-1808) | 2932 | 0 | 4.2 | 3.2 |
+| fix -> fix | 512 Hz x 8, chunk 1 | 96 (94-97) | 204 (200-235) | 254 (246-1011) | 3218 | 0 | 4.2 | 3.2 |
+| quick -> quick | 512 Hz x 8, chunk 1 | 94 (92-98) | 204 (194-239) | 419 (308-557) | 2382 | 0 | 4.1 | 3.2 |
+| oracle -> oracle | 512 Hz x 8, chunk 16 | 246 (224-247) | 646 (599-648) | 742 (729-779) | 780 | 0 | 0.7 | 0.4 |
+| main -> main | 512 Hz x 8, chunk 16 | 290 (287-297) | 667 (614-1054) | 1025 (703-2150) | 2151 | 0 | 2.0 | 1.5 |
+| fix -> fix | 512 Hz x 8, chunk 16 | 220 (218-238) | 514 (464-514) | 617 (480-624) | 626 | 0 | 1.1 | 0.5 |
+| quick -> quick | 512 Hz x 8, chunk 16 | 220 (214-236) | 531 (495-536) | 696 (676-754) | 756 | 0 | 1.1 | 0.5 |
+| oracle -> oracle | 4000 Hz x 64, chunk 1 | 71 (70-72) | 116 (114-117) | 152 (152-164) | 2803 | 0 | 30.4 | 18.4 |
+| main -> main | 4000 Hz x 64, chunk 1 | 73 (73-75) | 116 (114-119) | 154 (149-172) | 755 | 0 | 21.2 | 18.4 |
+| fix -> fix | 4000 Hz x 64, chunk 1 | 75 (74-76) | 121 (116-165) | 168 (159-2487) | 5199 | 0 | 21.5 | 18.2 |
+| quick -> quick | 4000 Hz x 64, chunk 1 | 73 (71-74) | 125 (105-145) | 224 (157-1681) | 3985 | 0 | 20.5 | 17.5 |
+| oracle -> oracle | 4000 Hz x 64, chunk 32 | 318 (317-320) | 651 (646-667) | 768 (764-844) | 876 | 0 | 3.3 | 1.7 |
+| main -> main | 4000 Hz x 64, chunk 32 | 382 (381-406) | 795 (756-852) | 1108 (892-1309) | 2916 | 0 | 9.3 | 10.8 |
+| fix -> fix | 4000 Hz x 64, chunk 32 | 343 (310-355) | 664 (626-699) | 810 (796-1063) | 3097 | 0 | 3.1 | 2.2 |
+| quick -> quick | 4000 Hz x 64, chunk 32 | 328 (322-339) | 658 (657-671) | 829 (797-832) | 892 | 0 | 3.2 | 2.2 |
+
+### What the results show
+
+- **A chunk push on `main` costs 3 to 5 times the CPU of liblsl.** At
+ 4000 Hz x 64 channels in chunks of 32, `main` uses 9.3 % and 10.8 %. The
+ `fix` branch uses 3.1 % and 2.2 %, near liblsl. The `fix` branch writes each chunk
+ with one write, and locks the inlet queue once for each read.
+- **A chunk push on `main` is also slower.** The median is 382 µs on `main`,
+ 343 µs on `fix`, and 318 µs on liblsl.
+- **A push of one sample gives the same latency in all four builds.** The
+ median is 70 to 100 µs. At 4000 Hz x 64 channels, the labstream outlet uses
+ about 21 % of one core, and the liblsl outlet uses 30 %.
+- **No build lost a sample.**
+- **The maximum is noise.** A single value of 2 to 5 ms comes from the
+ scheduler of the operating system. The p99.9 column is a better measure of
+ the tail.
+- **The `quick` branch does not change the latency of the data path.** It
+ changes the start of a connection and the end of a dead connection. This
+ benchmark measures neither.
+
+## The order of the runs
+
+The order of the runs can move a result. In one run of `seq` against
+`quick`, the `seq` rows ran last in each group. At 512 Hz x 8 channels,
+`seq` then showed a median of 138 µs against 97 µs. With `seq` first, both
+gave 91 µs, and the p99 values were 188 µs and 190 µs. A difference at a low
+rate is thus not a result until it stays after a change of order.
+
+On the branch `feat/seq`, the `seq/1` feature does not change the latency
+or the CPU at 4000 Hz x 64 channels:
+
+| outlet -> inlet | load | p50 µs | p99 µs | CPU outlet % | CPU inlet % |
+|---|---|---|---|---|---|
+| quick -> quick | 4000 Hz x 64, chunk 1 | 73 (72-73) | 103 (101-104) | 20.7 | 17.5 |
+| seq -> seq | 4000 Hz x 64, chunk 1 | 73 (72-75) | 99 (97-113) | 20.5 | 17.7 |
+| quick -> quick | 4000 Hz x 64, chunk 32 | 356 (348-366) | 711 (677-712) | 3.3 | 2.4 |
+| seq -> seq | 4000 Hz x 64, chunk 32 | 350 (332-352) | 648 (609-654) | 3.2 | 2.3 |
+
+## What this benchmark does not measure
+
+- **Two machines.** All results come from the loopback interface.
+- **A slow or lossy network.** Do not add a `tc netem` rule to the `lo`
+ interface of a shared machine. The rule delays every program on the machine.
+ Use a network namespace instead. Make two namespaces with a `veth` pair,
+ add the `netem` rule inside one of them, and run the outlet and the inlet in
+ different namespaces. Discovery then needs the namespace addresses in
+ `lab.KnownPeers` of the configuration. This procedure was not run yet.
+- **The application.** Phasic and other programs pull in their own loop. Their
+ poll interval adds to these numbers.
+- **The first offset and the recovery.** The live tests in
+ `crates/labstream-net/tests/` measure these.
diff --git a/docs/repository.md b/docs/repository.md
index 7a4ffc4..68e1846 100644
--- a/docs/repository.md
+++ b/docs/repository.md
@@ -291,6 +291,8 @@ release of a new crate therefore goes by hand, with a token.
| `docs/releasing.md` | how to release to crates.io and to GitHub, and how to recover |
| `docs/versioning.md` | what a version number means, and the rule for each change |
| `docs/conformance.md` | what was measured against liblsl, how, and the result |
+| `docs/latency.md` | how to measure the latency and the CPU, and the results |
+| `docs/extensions.md` | a proposal for features between two labstream peers |
| `SPEC.md` | the protocol, with a citation for every claim |
| `CONTRIBUTING.md` | the rules for a change, and the style of the documents |
| `CHANGELOG.md` | what changed in each version |