Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
18 commits
Select commit Hold shift + click to select a range
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 10 additions & 1 deletion ffi/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -959,7 +959,16 @@ value of a Rust type crosses as one Swift type that holds it exactly, and back u
as an array's items or behind a pointer, which Rust only reads and so copies. Swift's
own, made with `Bytes(data)` or from any sequence of bytes, Rust copies once where it
keeps them. `bytes.data` is a `Data`: Swift's as they are, and Rust's copied, so nothing
writes into a buffer Rust shares.
writes into a buffer Rust shares, and `bytes.withSpan` lends them in place as a
`Span<UInt8>`.
- **Slices** a call borrows, `&[u8]` and `&[T]` of a fixed-width integer or float, are
`borrowing Swift.Span<T>`, which Rust reads in place: an array's `span`, or before
Apple's 26 releases its slice's (`array[...]`), or `Bytes` lent by `withSpan`, whose
closure is synchronous. An `async` call takes `Bytes` copied to a slice that lives
across the `await`, as `let s = Array(bytes)[...]` and then `try await f(s.span)`.
Bytes Rust lends a closure or trait method are a `Span<UInt8>` of Rust's own memory,
which the compiler keeps from outliving the call. A `span` property on `Bytes` waits on Swift's lifetime dependencies, still
experimental, and on `Data` keeping short bytes inline.
Strings are `String`, copied, `char` `Unicode.Scalar`, `usize` `UInt`, `Option<T>` `T?`,
a tuple a Swift tuple, though a tuple of one is its element, `u128` a `U128` of its
`high` and `low` halves until the deployment target allows `UInt128`, and `Duration` the
Expand Down
12 changes: 12 additions & 0 deletions ffi/fixtures/api/examples/transcript.rs
Original file line number Diff line number Diff line change
Expand Up @@ -732,6 +732,18 @@ fn main() {
ledger.seal();
println!("sealed {}", ledger.edit().err().unwrap());
println!("chunks {:?}", api::chunks(b"abcde", 2));
println!(
"chunk lens {} {} {} {}",
api::chunks(b"abcde", 2)
.iter()
.map(|c| format!("{}", api::len(c)))
.collect::<Vec<_>>()
.join(" "),
api::held_count(Some((Counter::new("h", 4),)))
.map_or("none".to_string(), |v| format!("{v} {}", api::len(b"ab"))),
api::fingerprint(&format!("{}", api::len(b"abc"))).is_err(),
api::sum_u32(&[ledger.published(), 1])
);
let counters = api::counters(vec!["x".to_string(), "y".to_string()]);
println!(
"counters {}",
Expand Down
20 changes: 20 additions & 0 deletions ffi/fixtures/api/src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -4179,6 +4179,26 @@ pub fn doubled_i64(items: &[i64]) -> Vec<i64> {
items.iter().map(|v| v.wrapping_mul(2)).collect()
}

/// What `visit` returns for each chunk of `payload` of up to `size` bytes, which is not 0,
/// each lent in place, then for none.
pub fn visit_chunks(payload: &[u8], size: usize, mut visit: impl FnMut(Option<&[u8]>) -> u64) -> Vec<u64> {
let mut seen: Vec<u64> = payload.chunks(size).map(|chunk| visit(Some(chunk))).collect();
seen.push(visit(None));
seen
}

/// A reader of lent bytes: a callback interface, implemented in C.
pub trait Scan {
/// A digest of `payload` and `rest`, if any, each lent for the call.
fn scan(&self, payload: &[u8], rest: Option<&[u8]>) -> u64;
}

/// What `scan` returns for each half of `payload`, each lent in place, then for none.
pub fn scanned(scan: impl Scan, payload: Vec<u8>) -> u64 {
let (head, tail) = payload.split_at(payload.len() / 2);
scan.scan(head, Some(tail)) + scan.scan(&[], None)
}

/// `items` back as Rust took them, boxed.
pub fn boxed_floats(items: Box<[f64]>) -> Box<[f64]> {
items
Expand Down
14 changes: 7 additions & 7 deletions ffi/moq/bench/export.swift
Original file line number Diff line number Diff line change
Expand Up @@ -164,7 +164,7 @@ func throughput(_ track: TrackProducer, _ subscriber: inout TrackSubscriber, _ m
var group = try track.appendGroup(at)
var reader = try await subscriber.recvGroup()!
for _ in 0..<frames {
try group.writeFrame(at, frame)
try frame.withSpan { try group.writeFrame(at, $0) }
sum += Int(try await reader.readFrame()!.payloadGet[0])
}
_ = try group.finish()
Expand Down Expand Up @@ -231,7 +231,7 @@ func round(_ measured: Bool) throws -> ([(String, Span)], Int) {
for _ in 0..<frames {
let at = try Timestamp.fromMicros(micros)
micros += 1
try group.writeFrame(at, frame)
try frame.withSpan { try group.writeFrame(at, $0) }
}
_ = try group.finish()
}
Expand All @@ -244,7 +244,7 @@ func round(_ measured: Bool) throws -> ([(String, Span)], Int) {
micros += 1
var group = try track.appendGroup(at)
for _ in 0..<frames {
try group.writeFrame(at, frame)
try frame.withSpan { try group.writeFrame(at, $0) }
}
_ = try group.finish()
}
Expand All @@ -266,7 +266,7 @@ func round(_ measured: Bool) throws -> ([(String, Span)], Int) {
var group = try track.appendGroup(at)
var reader = try await subscriber.recvGroup()!
for _ in 0..<frames {
try group.writeFrame(at, frame)
try frame.withSpan { try group.writeFrame(at, $0) }
last = try await reader.readFrame()!
}
_ = try group.finish()
Expand All @@ -284,7 +284,7 @@ func round(_ measured: Bool) throws -> ([(String, Span)], Int) {
for _ in 0..<frames {
let pending = Task { _ = try await reader.readFrame()! }
await Task.yield()
try group.writeFrame(at, frame)
try frame.withSpan { try group.writeFrame(at, $0) }
try await pending.value
}
_ = try group.finish()
Expand All @@ -306,7 +306,7 @@ func round(_ measured: Bool) throws -> ([(String, Span)], Int) {
for _ in 0..<frames {
let permit: Void? = await next.next()
precondition(permit != nil)
try group.writeFrame(at, frame)
try frame.withSpan { try group.writeFrame(at, $0) }
}
let consumed: Void? = await next.next()
precondition(consumed != nil)
Expand Down Expand Up @@ -366,7 +366,7 @@ func round(_ measured: Bool) throws -> ([(String, Span)], Int) {
queue.drain()
for f in 0..<frames {
precondition(consumed.value == g * frames + f)
try group.writeFrame(at, frame)
try frame.withSpan { try group.writeFrame(at, $0) }
queue.drain()
precondition(consumed.value == g * frames + f + 1)
}
Expand Down
12 changes: 6 additions & 6 deletions ffi/moq/moq.swift
Original file line number Diff line number Diff line change
Expand Up @@ -243,7 +243,7 @@ func script() throws {
}
q.drain()
expect(frame.isEmpty, "a read waits for a frame")
try writer.writeFrame(Timestamp.unscaled(0), Bytes("hello".utf8))
try Bytes("hello".utf8).withSpan { try writer.writeFrame(Timestamp.unscaled(0), $0) }
expect(q.size == 1, "a frame's arrival wakes the read")
q.drain()
let hello = frame.take()!
Expand All @@ -257,7 +257,7 @@ func script() throws {
let at = try Timestamp.fromMillis(1500)
expect(try at.asSecs() == 1, "1500 ms is 1 s")
do {
try writer.writeFrame(at, Bytes("late".utf8))
try Bytes("late".utf8).withSpan { try writer.writeFrame(at, $0) }
expect(false, "a timed frame on an untimed track is an error")
} catch let e as Moq.Error {
expect(try e.description == "frame timestamp doesn't fit its track", "the late frame's error is Rust's")
Expand All @@ -266,7 +266,7 @@ func script() throws {

// The last frame, bytes that are not UTF-8, then the group's end, which reads as nil.
let world = Bytes(Data([0xff]) + Data("world".utf8))
try writer.writeFrame(Timestamp.unscaled(0), world)
try world.withSpan { try writer.writeFrame(Timestamp.unscaled(0), $0) }
_ = try writer.finish()
try block {
let last = try await first.value.readFrame()
Expand All @@ -293,14 +293,14 @@ func script() throws {
// moq-mux reads an OpusHead into hang's catalog config: 44.1 kHz in, stereo, which the
// catalog lists at the decoder's 48 kHz, keeping the head as its description.
let head = Bytes(Data("OpusHead".utf8) + Data([1, 2, 0x38, 0x01, 0x44, 0xac, 0, 0, 0, 0, 0]))
let audio = try muxCodecOpusConfig(head)
let audio = try head.withSpan { try muxCodecOpusConfig($0) }
expect(try audio.sampleRateGet == 48000, "Opus decodes at 48 kHz")
expect(try audio.channelCountGet == 2, "the head is stereo")
expect(try audio.codecGet == .opus, "the codec is Opus")
expect(try audio.descriptionGet == head, "the head is the description")
// A truncated head is moq-mux's error.
do {
_ = try muxCodecOpusConfig(head.prefix(8))
_ = try head.prefix(8).withSpan { try muxCodecOpusConfig($0) }
expect(false, "a truncated head is an error")
} catch let e as MuxError {
expect(!"\(e)".isEmpty, "a truncated head's error has a message")
Expand Down Expand Up @@ -429,7 +429,7 @@ func script() throws {
let live = try served.route("live", OriginRouteOptions.default())
let liveTrack = try live.broadcast().createTrack("video", nil)
var liveGroup = try liveTrack.appendGroup(Timestamp.unscaled(0))
try liveGroup.writeFrame(Timestamp.unscaled(0), Bytes("hello".utf8))
try Bytes("hello".utf8).withSpan { try liveGroup.writeFrame(Timestamp.unscaled(0), $0) }
_ = try liveGroup.finish()

var serverConfig = TokioServerConfig.default()
Expand Down
53 changes: 50 additions & 3 deletions ffi/runtime/rt.swift
Original file line number Diff line number Diff line change
Expand Up @@ -259,6 +259,11 @@ public struct Bytes: Hashable, Sendable, RandomAccessCollection {
self.init(Data(bytes))
}

/// `span`'s bytes, copied, as a closure keeps bytes Rust lent it.
public init(_ span: borrowing Swift.Span<Swift.UInt8>) {
self.init(span.withUnsafeBufferPointer { Data(buffer: $0) })
}

/// The bytes as a `Data`: Swift's as they are, and Rust's copied.
public var data: Data {
owner == nil ? storage : Data(storage)
Expand All @@ -279,9 +284,13 @@ public struct Bytes: Hashable, Sendable, RandomAccessCollection {
return Bytes(storage: slice, owner: owner.flatMap { $0.holds(slice) ? $0 : nil })
}

/// Run `body` with the bytes in place, which it must not keep.
public func withUnsafeBytes<R>(_ body: (UnsafeRawBufferPointer) throws -> R) rethrows -> R {
try storage.withUnsafeBytes(body)
/// Run `body` with the bytes in place, as a span the compiler keeps it from keeping.
public func withSpan<R: ~Copyable>(_ body: (Swift.Span<Swift.UInt8>) throws -> R) rethrows -> R {
var result: R? = nil
try storage.withUnsafeBytes { raw in
result = try body(Swift.Span(_unsafeBytes: raw))
}
return result.take()!
}

/// Whether `a` and `b` hold the same bytes, wherever each keeps them.
Expand Down Expand Up @@ -505,6 +514,44 @@ extension Native {
return try view(bytes, body)
}

/// `span` as a view C reads during `body`, without a copy.
@inline(__always)
static func view<R: ~Copyable>(_ span: borrowing Swift.Span<Swift.UInt8>, _ body: (Buf) throws -> R) rethrows -> R {
try span.withUnsafeBytes { raw in try body(view(raw)) }
}

@inline(__always)
static func view<R: ~Copyable>(_ span: borrowing Swift.Span<Swift.UInt8>?, _ body: (Buf) throws -> R) rethrows -> R {
switch span {
case .some(let span): return try view(span, body)
case .none: return try body(none)
}
}

/// `span` as the array `make` makes of its items, which C reads during `body` without a
/// copy: never null, so no items read as present.
@inline(__always)
static func view<T, L, R: ~Copyable>(
_ span: borrowing Swift.Span<T>, _ make: (UnsafePointer<T>?, Int, UnsafeMutableRawPointer?) -> L,
_ body: (L) throws -> R
) rethrows -> R {
try span.withUnsafeBufferPointer { items in
let ptr = items.baseAddress ?? UnsafePointer(bitPattern: Swift.MemoryLayout<T>.alignment)!
return try body(make(ptr, items.count, nil))
}
}

@inline(__always)
static func view<T, L, R: ~Copyable>(
_ span: borrowing Swift.Span<T>?, _ make: (UnsafePointer<T>?, Int, UnsafeMutableRawPointer?) -> L,
_ body: (L) throws -> R
) rethrows -> R {
switch span {
case .some(let span): return try view(span, make, body)
case .none: return try body(make(nil, 0, nil))
}
}

/// `text`'s UTF-8 as a view C reads during `body`, without a copy for a native string.
@inline(__always)
static func view<R: ~Copyable>(_ text: Swift.String, _ body: (Buf) throws -> R) rethrows -> R {
Expand Down
64 changes: 58 additions & 6 deletions ffi/src/swift.rs
Original file line number Diff line number Diff line change
Expand Up @@ -20,14 +20,17 @@
//! Bytes are the runtime's `Bytes`: those Rust returned lend its buffer, and pass back to
//! Rust as a second owner of it, so neither way copies them. Swift's own bytes and text
//! pass as views of Swift's memory at a call's top level, which Rust copies once where it
//! keeps them; nested in another value, they are copied once into a buffer Rust takes.
//! keeps them; nested in another value, they are copied once into a buffer Rust takes. A
//! slice Rust borrows, of bytes or a block's numbers, is a `Span` either way: a parameter
//! Rust reads in place, and bytes Rust lends a closure or callback, which Swift's compiler
//! keeps from escaping the call.

use std::collections::{BTreeMap, BTreeSet, HashMap};
use std::fmt::Write;

use crate::abi::{self, Abi, Ty, pascal};
use crate::doc;
use crate::ir::{Access, Closure, Family, Function, Int, Literal, Mutability, On, Param, Receiver, Type};
use crate::ir::{Access, Closure, Collection, Family, Function, Int, Literal, Mutability, On, Param, Receiver, Type};

const RUNTIME: &str = include_str!("../runtime/rt.swift");

Expand Down Expand Up @@ -342,6 +345,29 @@ impl<'a> Gen<'a> {
unique(&self.structs, ty)
}

/// The element of the span Swift borrows a shared slice of bytes or of a block's numbers
/// as, in place, which the compiler keeps from escaping the call.
fn spanned(&self, ty: &Type) -> Option<String> {
match ty {
Type::Ref(Mutability::Not, inner) => match &**inner {
Type::Slice => Some("Swift.UInt8".to_string()),
list @ Type::List(Collection::Slice, elem) if list.block().is_some() => Some(self.sw(elem)),
_ => None,
},
_ => None,
}
}

/// The Swift type of a parameter of type `ty`, which Rust takes or lends: a slice it
/// borrows is a span, and any other type as [`Self::sw`] has it.
fn param(&self, ty: &Type) -> String {
match (ty, self.spanned(unoption(ty))) {
(Type::Option(_), Some(elem)) => format!("Swift.Span<{elem}>?"),
(_, Some(elem)) => format!("Swift.Span<{elem}>"),
(_, None) => self.sw(ty),
}
}

/// The ownership a parameter of type `ty` declares, which Swift requires of a
/// noncopyable one: `&T` borrows it, `&mut T` is `inout`, and a value moves in.
fn ownership(&self, ty: &Type) -> &'static str {
Expand Down Expand Up @@ -414,7 +440,7 @@ impl<'a> Gen<'a> {
Type::Closure(closure_) => {
let (params, ret) = (&closure_.params, &closure_.ok);
let params: Vec<String> = (params.iter())
.map(|p| format!("{}{}", self.ownership(p), self.sw(p)))
.map(|p| format!("{}{}", self.ownership(p), self.param(p)))
.collect();
let throws = match closure_.err {
Some(_) => " throws",
Expand Down Expand Up @@ -694,9 +720,14 @@ impl<'a> Gen<'a> {
}

/// The Swift value of the C value `e` of type `ty`, which C lends a callback or closure
/// for its call: bytes and text copied, and a scalar as it is.
/// for its call: a slice as a span of it in place, other bytes and text copied, and a
/// scalar as it is.
fn lift_lent(&mut self, ty: &Type, e: &str) -> String {
let span =
|e: &str| format!("Swift.Span(_unsafeElements: Swift.UnsafeBufferPointer(start: {e}.ptr, count: {e}.len))");
match ty {
_ if self.spanned(ty).is_some() => span(e),
Type::Option(inner) if self.spanned(inner).is_some() => format!("({e}.ptr == nil ? nil : {})", span(e)),
Type::Str | Type::String => format!("Native.string(lent: {e})"),
Type::Path | Type::PathBuf => format!("Native.path(lent: {e})"),
Type::Slice | Type::Vec | Type::Bytes => format!("Native.bytes(lent: {e})"),
Expand Down Expand Up @@ -1408,7 +1439,7 @@ impl<'a> Gen<'a> {
);
members.push(full(false, &member, method.params.iter().map(|_| "_".to_string())));
let params: Vec<String> = (method.params.iter().zip(locals(&method.params)))
.map(|(p, name)| format!("_ {name}: {}", self.sw(&p.ty)))
.map(|(p, name)| format!("_ {name}: {}", self.param(&p.ty)))
.collect();
let ret = match method.ok {
Type::Unit => String::new(),
Expand Down Expand Up @@ -1551,6 +1582,18 @@ impl<'a> Gen<'a> {
arg.exprs.push(format!("Native.future({e})"));
arg.gives = true;
}
// A span is a view of Swift's memory, which Rust borrows in place.
(ty, _) if self.spanned(unoption(ty)).is_some() => {
let b = format!("b{k}_");
let make = match unoption(ty) {
Type::Ref(_, list) if let Type::List(_, elem) = &**list => {
format!(", {}.init(ptr:len:owner:)", abi.list(elem))
}
_ => String::new(),
};
arg.open = Some((format!("{tr}Native.view({e}{make}) {{ {b} in"), "}".to_string()));
arg.exprs.push(b);
}
(ty, Ty::Buf) if Abi::is_buf(ty) || matches!(ty.base(), Type::Option(inner) if Abi::is_buf(inner)) => {
let b = format!("b{k}_");
arg.open = Some((format!("{tr}Native.take({e}) {{ {b} in"), "}".to_string()));
Expand Down Expand Up @@ -1851,9 +1894,10 @@ impl<'a> Gen<'a> {
(false, Type::Closure(closure_)) if closure_.kept => "@escaping ",
// Rust reads and seeks the reader in place.
(false, Type::Ref(_, inner)) if **inner == Type::Reader => "inout ",
(false, ty) if self.spanned(unoption(ty)).is_some() => "borrowing ",
(false, _) => self.ownership(&param.ty),
};
params.push(format!("_ {name}: {ownership}{}", self.sw(&param.ty)));
params.push(format!("_ {name}: {ownership}{}", self.param(&param.ty)));
let (arg, needs) = self.arg(&param.ty, c, name, k, tr, &what);
arena |= needs;
args.push(arg);
Expand Down Expand Up @@ -2442,6 +2486,14 @@ fn unique(structs: &BTreeSet<usize>, ty: &Type) -> bool {
}
}

/// `ty`, or what it holds if an `Option`.
fn unoption(ty: &Type) -> &Type {
match ty {
Type::Option(inner) => inner,
ty => ty,
}
}

/// Whether `ty` is an `Option<&T>` of one of `structs`.
fn lent_option(structs: &BTreeSet<usize>, ty: &Type) -> bool {
matches!(ty, Type::Option(inner) if matches!(&**inner, Type::Ref(Mutability::Not, object) if unique(structs, object)))
Expand Down
Loading