diff --git a/ffi/README.md b/ffi/README.md index 041f10992..45c782460 100644 --- a/ffi/README.md +++ b/ffi/README.md @@ -423,8 +423,15 @@ packages place it in. lives only as long as the bytes it views, and a `view` lent to a callback only for the call; reading one past that is C++'s own undefined behavior, which Clang's `-Wdangling` refuses for a view or `str()` of a temporary `buf`. A `Vec` is a `std::vector`, passed in place - when of a fixed-width integer other than `u8` (bytes) or `u128` or of a float, of `view`s for bytes passed in, a socket address `socket_addr`, the C struct, and a `u128` - `u128`, the C struct. `Option` is `std::optional`, a tuple `std::tuple`, and `Result` a `result`, whose `value()` aborts on an + when of a fixed-width integer other than `u8` (bytes) or `u128` or of a float. One whose + items hold bytes is taken as `items` of `view`s, which points into a `std::vector` of them + in place and converts any other range whose items convert and outlive the call, such as a + returned `std::vector`, but not a range of temporaries. A `std::vector` moved in + converts with each item moved, so a returned one passes back even when its items hold a + `Copy` object C++ cannot copy. One whose items also move a + handle is taken as `taken`, a `std::vector` of them moved in as it is, or any other such + range moved in, each handle moved out of it. A socket address is a `socket_addr` and a + `u128` a `u128`, each the C struct. `Option` is `std::optional`, a tuple `std::tuple`, and `Result` a `result`, whose `value()` aborts on an error. A `[u8; N]` is a `std::array`. - **Traits** are abstract classes, passed as a `std::unique_ptr` that Rust deletes. - **Closures** are any callable, taken by a template parameter, which Rust calls from any @@ -510,7 +517,7 @@ out, with only its other fields encoded. target's range, `Option` `T?`, a tuple `Pair` or `Triple`, or else a generated `Tuple`, and also `Tuple2` or `Tuple3` when it holds a numeric array or a float anywhere, records included, since `Pair` and `Triple` cannot - compare them as Rust does (so a `BTreeMap` is a `List>`), though a tuple of one returned whole is its element, `u128` `java.math.BigInteger`, which throws `IllegalArgumentException` passed in out of its range, `Duration` `kotlin.time.Duration`, and an `Err` a thrown `Exception` + compare them as Rust does (so a `BTreeMap` is a `List>`), `u128` `java.math.BigInteger`, which throws `IllegalArgumentException` passed in out of its range, `Duration` `kotlin.time.Duration`, and an `Err` a thrown `Exception` holding it, whose message is its `Display`. A `[u8; N]` is a generated `ArrayU8x`, which copies the `ByteArray` it is made of and throws `IllegalArgumentException` unless it holds exactly `N` bytes. diff --git a/ffi/fixtures/api/examples/transcript.rs b/ffi/fixtures/api/examples/transcript.rs index c10132fd2..34183ea08 100644 --- a/ffi/fixtures/api/examples/transcript.rs +++ b/ffi/fixtures/api/examples/transcript.rs @@ -116,6 +116,8 @@ fn main() { ("low".to_string(), Counter::new("l", 1)), ("high".to_string(), Counter::new("h", 9)), ]); + // The counters a board returns build another, each handle moved back in. + let board = api::Board::new(board.into_counters()); let ranked: Vec = (board.ranked()) .map(|(name, counter)| format!("{name} {} {}", counter.name(), counter.get())) .collect(); diff --git a/ffi/fixtures/api/src/lib.rs b/ffi/fixtures/api/src/lib.rs index f7e2ed8a9..f5315426e 100644 --- a/ffi/fixtures/api/src/lib.rs +++ b/ffi/fixtures/api/src/lib.rs @@ -343,6 +343,11 @@ impl Board { } } + /// Each name and its counter in name order, each handle moved out of the board. + pub fn into_counters(self) -> Vec<(String, Counter)> { + self.counters.into_iter().collect() + } + /// Each name and its counter, highest first, as hang's `ranked`: each pair borrowed, /// so each crosses as a clone. pub fn ranked(&self) -> impl Iterator { @@ -781,6 +786,11 @@ impl Ticket { } } +/// Each name and its ticket, as given, so a binding passes back what it returned. +pub fn tickets(entries: Vec<(String, Ticket)>) -> Vec<(String, Ticket)> { + entries +} + /// The ticket `swap` returns for `ticket`. pub fn reissue(ticket: Ticket, swap: impl Fn(Ticket) -> Ticket) -> Ticket { swap(ticket) diff --git a/ffi/runtime/rt.hpp b/ffi/runtime/rt.hpp index 3b00b84c7..58e8e8764 100644 --- a/ffi/runtime/rt.hpp +++ b/ffi/runtime/rt.hpp @@ -431,6 +431,106 @@ class input { friend struct detail::access; }; +namespace detail { +// Whether each item of the range `R` lives as long as `R` does, so a `T` made of it may view +// its bytes: a reference into `R`, or a `T` itself, but no other temporary, such as the +// `std::string` a C++20 transform may yield, which dies before the call reads it. +template ()))> +inline constexpr bool lasting = ::std::is_reference_v || ::std::is_same_v<::std::decay_t, T>; +} // namespace detail + +// Items lent to a call whose items hold bytes, such as `view`s: a `std::vector` in place, +// or any other range whose items convert to `T`, such as the `std::vector` a call +// returned or a `std::vector`, converted item by item. +template +class items { + ::std::vector converted_; + const T *data_; + ::std::size_t size_; + +public: + items(const ::std::vector &vector RUST2_FFI_LIFETIMEBOUND) noexcept : data_(vector.data()), size_(vector.size()) {} + // Copied, since a list's array may not outlive the call's first full-expression. + items(::std::initializer_list list) : converted_(list), data_(converted_.data()), size_(converted_.size()) {} + template , ::std::vector> && + !::std::is_same_v<::std::decay_t, items> && detail::lasting && + ::std::is_convertible_v())), T>>> + items(const R &range RUST2_FFI_LIFETIMEBOUND) { + // A loop, since a C++20 range's end may be a sentinel of another type than its begin. + for (auto &&item : range) { + converted_.emplace_back(item); + } + data_ = converted_.data(); + size_ = converted_.size(); + } + // A vector moved in, each item moved: a returned `std::vector>` whose + // `H` is a `Copy` object with no C++ copy. Only an owning vector, since a moved view's + // items belong to the caller. + template && ::std::is_convertible_v>> + items(::std::vector &&vector RUST2_FFI_LIFETIMEBOUND) { + converted_.reserve(vector.size()); + for (auto &item : vector) { + converted_.emplace_back(::std::move(item)); + } + data_ = converted_.data(); + size_ = converted_.size(); + } + // A copy would point into the original's converted items. + items(const items &) = delete; + items &operator=(const items &) = delete; + // A moved vector keeps its array, so the pointer stays valid. + items(items &&other) noexcept = default; + + const T *begin() const noexcept { + return data_; + } + const T *end() const noexcept { + return data_ + size_; + } + ::std::size_t size() const noexcept { + return size_; + } + bool empty() const noexcept { + return size_ == 0; + } +}; + +// Items moved into a call whose items hold both bytes, as `view`s, and handles it takes: a +// `std::vector` as it is, or any other range moved in whose items convert to `T`, such as +// the `std::vector>` a call returned, each handle moved out of it. Its +// views point into the range's bytes, which live until the call's full-expression ends. +template +class taken { + ::std::vector items_; + +public: + taken() noexcept = default; + taken(::std::vector &&vector) noexcept : items_(::std::move(vector)) {} + // A range moved in, never one lent: its handles move out. + template && !::std::is_same_v> && + !::std::is_same_v && detail::lasting && + ::std::is_convertible_v()))), T>>> + taken(R &&range RUST2_FFI_LIFETIMEBOUND) { + for (auto &&item : range) { + items_.emplace_back(::std::move(item)); + } + } + + T *begin() noexcept { + return items_.data(); + } + T *end() noexcept { + return items_.data() + items_.size(); + } + ::std::size_t size() const noexcept { + return items_.size(); + } + bool empty() const noexcept { + return items_.empty(); + } +}; + // What a fallible call returns: its value, or the error that stopped it. template class result { diff --git a/ffi/src/abi.rs b/ffi/src/abi.rs index 6760ec7c3..fe3b4d0be 100644 --- a/ffi/src/abi.rs +++ b/ffi/src/abi.rs @@ -928,6 +928,8 @@ impl<'a> Abi<'a> { "buf_clone", "poll", "view", + "items", + "taken", "borrow", "result", "task", diff --git a/ffi/src/cpp.rs b/ffi/src/cpp.rs index 8d8dabf9f..551ba6fd5 100644 --- a/ffi/src/cpp.rs +++ b/ffi/src/cpp.rs @@ -246,12 +246,19 @@ impl<'a> Header<'a> { } } - /// The C++ vector a `Vec` parameter of type `ty` takes: of views, for bytes. + /// The C++ type a `Vec` parameter of type `ty` takes: a vector, or, when its items hold + /// views, the runtime's `items` lent or `taken` when they move handles, each of which + /// also takes a returned vector of `buf`s as it is. fn items(&self, ty: &Type) -> String { let Type::List(_, inner) = ty else { unreachable!("{ty:?} is no Vec") }; - format!("::std::vector<{}>", self.held(inner)) + let held = self.held(inner); + match (held == self.owned(inner), moves(self.abi, inner)) { + (true, _) => format!("::std::vector<{held}>"), + (false, true) => format!("::{}::taken<{held}>", self.ns), + (false, false) => format!("::{}::items<{held}>", self.ns), + } } /// The C++ type a parameter's `Vec`, `Option`, or tuple holds a `ty` as: bytes as a view. @@ -507,6 +514,7 @@ impl<'a> Header<'a> { "cstdio", "cstdlib", "cstring", + "initializer_list", "ios", "memory", "mutex", diff --git a/ffi/src/kotlin.rs b/ffi/src/kotlin.rs index fd7ed0c72..7895ec1ac 100644 --- a/ffi/src/kotlin.rs +++ b/ffi/src/kotlin.rs @@ -2098,13 +2098,20 @@ impl<'a> Gen<'a> { let rust_args: Vec = args.iter().flat_map(|a| a.rust_args.clone()).collect(); let after: Vec = args.iter().flat_map(|a| a.after.clone()).collect(); - // A tuple of one returned whole is its element, written through its one out pointer; - // one behind a reference or `Box` is returned as a struct, so stays a tuple. + // A tuple of one returned whole crosses as its element, written through its one out + // pointer, and is wrapped back into the tuple class its parameters take; one behind a + // reference or `Box` is returned as a struct, so crosses as a tuple. + let single = match &function.ok { + Type::Tuple(elements) if elements.len() == 1 => Some(self.tuple_class(elements)), + _ => None, + }; let ok = match &function.ok { Type::Tuple(elements) if elements.len() == 1 => strip_refs(&elements[0]), ok => strip_refs(ok), }; - let ret_kt = self.kt(&ok); + let ret_kt = self.kt(&strip_refs(&function.ok)); + // What crosses: a tuple of one's element, before it is wrapped. + let ok_kt = self.kt(&ok); let err = function.err.as_ref().map(strip_refs); let exception = err.as_ref().map(|e| self.exception(e)); // A record returned directly crosses as its scalars, set into slots the call takes, @@ -2215,7 +2222,7 @@ impl<'a> Gen<'a> { value = if ok == Type::Unit { format!("{awaited}.let {{ Unit }}") } else { - format!("({awaited}) as {ret_kt}") + format!("({awaited}) as {ok_kt}") }; } else if written.is_empty() && matches!(&function.ok, Type::Tuple(elements) if elements.len() > 1 && elements.iter().map(|ty| match abi.ty(ty) { Ty::Int(Int::I64 | Int::U64 | Int::Isize | Int::Usize) | Ty::F64 | Ty::Handle { .. } => 2, _ => 1 }).sum::() + usize::from(err.is_some()) <= 255 && elements.iter().all(|ty| matches!(abi.ty(ty), Ty::Bool | Ty::Int(_) | Ty::F32 | Ty::F64 | Ty::Char | Ty::Enum(_) | Ty::Handle { .. }))) @@ -2299,7 +2306,7 @@ impl<'a> Gen<'a> { } else { self.refused_first(&bare, format!("try {{ {raw} }} finally {{ {} }}", after.join("; "))) }; - value = format!("({raw}) as {ret_kt}"); + value = format!("({raw}) as {ok_kt}"); } else if let Some(c_ok) = direct(&outs, &written, &function.ok, function.err.as_ref()) { // A result of a scalar, a handle, or nothing returns its value directly, raising // its error as a `Native.Failed` Kotlin catches. @@ -2414,7 +2421,7 @@ impl<'a> Gen<'a> { }; value = match ok { Type::Unit => format!("{raw}.let {{ Unit }}"), - _ => format!("({raw}) as {ret_kt}"), + _ => format!("({raw}) as {ok_kt}"), }; } else if let Some(flat) = flat { let mut params: Vec<(&str, &str)> = native_params.iter().map(|(j, k)| (*j, k.as_str())).collect(); @@ -2490,7 +2497,7 @@ impl<'a> Gen<'a> { } else { self.refused_first(&bare, format!("try {{ {raw} }} finally {{ {} }}", after.join("; "))) }; - value = format!("({raw}) as {ret_kt}"); + value = format!("({raw}) as {ok_kt}"); } else { let c_ret = export.call.ret.clone(); // A block returns as the primitive array of its width, copied in one call. @@ -2524,6 +2531,10 @@ impl<'a> Gen<'a> { }; } + let value = match &single { + Some(class) => format!("{class}({value})"), + None => value, + }; // Wrap the value in each argument's holds, innermost last. let mut code = value; for arg in args.iter().rev() { @@ -2568,7 +2579,7 @@ impl<'a> Gen<'a> { None => "", }; let ret = match ok { - Type::Unit => String::new(), + Type::Unit if single.is_none() => String::new(), _ => format!(": {ret_kt}"), }; let property = matches!( diff --git a/ffi/tests/api.cpp b/ffi/tests/api.cpp index d3536345c..9e711afb0 100644 --- a/ffi/tests/api.cpp +++ b/ffi/tests/api.cpp @@ -25,6 +25,9 @@ #ifdef __cpp_lib_span #include #endif +#ifdef __cpp_lib_ranges +#include +#endif #include "api.hpp" @@ -336,6 +339,8 @@ int script() { meters.emplace_back("low", api::Counter::new_("l", 1)); meters.emplace_back("high", api::Counter::new_("h", 9)); auto board = api::Board::new_(std::move(meters)); + // The counters a board returns build another, each handle moved back in. + board = api::Board::new_(std::move(board).into_counters()); std::printf("ranked"); auto ranked = board.ranked(); for (std::size_t i = 0; i < ranked.size(); i++) { @@ -1198,6 +1203,29 @@ int script() { std::printf("reissued %u %u, cloned %u\n", static_cast(given), static_cast(held), static_cast(api::Ticket::clones())); } + { + // `Copy` objects with no C++ copy, beside bytes: a returned vector moves back in, + // stored or not, each ticket moved and each name viewed in place. + std::vector> lent; + lent.emplace_back("a", api::Ticket::new_(1)); + auto returned = api::tickets(lent); + auto again = api::tickets(api::tickets(std::move(returned))); + if (again.size() != 1 || std::get<0>(again[0]).str() != "a" || std::get<1>(again[0]).number() != 1) { + std::fprintf(stderr, "returned tickets passed back wrong\n"); + std::abort(); + } + } +#ifdef __cpp_lib_ranges + { + // A range whose end is a sentinel of another type than its begin. + std::vector letters{"p", "q", "r"}; + auto taken = api::counters(letters | std::views::take_while([](const std::string &n) { return n != "r"; })); + if (taken.size() != 2 || taken[1].name().str() != "q") { + std::fprintf(stderr, "a sentinel range passed wrong\n"); + std::abort(); + } + } +#endif // A kept closure, called on another thread after the call that took it returned. std::printf("spawned %u\n", static_cast(api::Spawned::new_([] { return 7; }).join())); // A kept closure: called again at the instant it asks for, then once its waiter wakes. diff --git a/ffi/tests/api.kt b/ffi/tests/api.kt index 5f5a2390e..910d68e8b 100644 --- a/ffi/tests/api.kt +++ b/ffi/tests/api.kt @@ -95,7 +95,7 @@ fun script() { val (below, above) = Counter.new("s", 7u).split(5u) println("split ${below.name()} ${below.get()} ${above.name()} ${above.get()}") - val only = only(Counter.new("o", 3u)) + val (only) = only(Counter.new("o", 3u)) println("only ${only.name()} ${only.get()}") val (w8, w16, w32, w64) = widths(98305u) println("widths $w8 $w16 $w32 $w64") diff --git a/ffi/tests/api_strict.cpp b/ffi/tests/api_strict.cpp index 3e119e0b2..88f178dfa 100644 --- a/ffi/tests/api_strict.cpp +++ b/ffi/tests/api_strict.cpp @@ -1,9 +1,14 @@ // What Clang refuses under `-Wconsumed -Wdangling -Werror`: each case, built alone as // `-DCASE=n`, breaks a contract `tests/api.cpp` otherwise reaches only at run time, or not // at all. With no case it builds clean. +#include +#include #include +#include #include +#include #include +#include #include "api.hpp" @@ -53,5 +58,41 @@ void broken() { std::string_view text = api::Counter::new_("c", 0).name().str(); (void)name; (void)text; +#elif CASE == 8 + // Text a range yields as temporaries, as a C++20 transform may: each dies before the call. + struct texts { + struct iterator { + using iterator_category = std::input_iterator_tag; + using value_type = std::string; + using difference_type = std::ptrdiff_t; + using pointer = void; + using reference = std::string; + int i; + std::string operator*() const { + return std::string(32, 'x'); + } + iterator &operator++() { + ++i; + return *this; + } + bool operator==(const iterator &other) const { + return i == other.i; + } + bool operator!=(const iterator &other) const { + return i != other.i; + } + }; + iterator begin() const { + return {0}; + } + iterator end() const { + return {1}; + } + }; + api::counters(texts{}); +#elif CASE == 9 + // Handles lent rather than moved in: the call would empty the caller's vector unasked. + std::vector> counters; + api::Board::new_(counters); #endif } diff --git a/ffi/tests/fixtures.rs b/ffi/tests/fixtures.rs index 3e09d14e2..5e890928f 100644 --- a/ffi/tests/fixtures.rs +++ b/ffi/tests/fixtures.rs @@ -505,6 +505,11 @@ fn cpp_strict(api: &Api) { (5, "'this' argument to member function 'into_label' is an lvalue"), (6, "no matching member function for call to 'emplace'"), (7, "temporary whose address is used as value of local variable 'name'"), + (8, "no viable conversion from 'texts'"), + ( + 9, + "no viable conversion from 'std::vector>'", + ), ] { let output = clang(&tests.join("api_strict.cpp"), case); assert!(!output.status.success(), "case {case} built"); diff --git a/ffi/tests/fixtures/shapes.rs b/ffi/tests/fixtures/shapes.rs index a8d6478d6..28b9359b9 100644 --- a/ffi/tests/fixtures/shapes.rs +++ b/ffi/tests/fixtures/shapes.rs @@ -866,37 +866,12 @@ fn duration(shape: &Shape) -> bool { within(shape, &|s| matches!(s, Shape::Duration)) } -/// A `Vec` or `Bytes`: a `Vec` of `u8` ints is one, as Rust types it alike. -fn is_bytes(shape: &Shape) -> bool { - match shape { - Shape::Bytes | Shape::Buf => true, - Shape::Vec(inner) => matches!(**inner, Shape::Int("u8")), - _ => false, - } -} - fn ipv6(shape: &Shape) -> bool { within(shape, &|s| { matches!(s, Shape::SocketAddr("SocketAddr" | "SocketAddrV6")) }) } -/// A collection whose items are bytes or tuples holding them, which C++ takes as views. -fn viewed_items(shape: &Shape) -> bool { - let buf = |s: &Shape| matches!(s, Shape::String | Shape::PathBuf) || is_bytes(s); - let item = |s: &Shape| buf(s) || matches!(s, Shape::Tuple(elements) if elements.iter().any(buf)); - within(shape, &|s| match s { - Shape::Vec(inner) | Shape::Set(inner) => item(inner), - Shape::Map(key, value) => buf(key) || buf(value), - _ => false, - }) -} - -/// A tuple of one element, which Kotlin returns as its element but takes whole. -fn single(shape: &Shape) -> bool { - matches!(shape, Shape::Tuple(elements) if elements.len() == 1) -} - /// A round trip a binding gets wrong today. struct Known { language: &'static str, @@ -936,24 +911,12 @@ const KNOWN: &[Known] = &[ skips: ipv6, quest: "/quest/m1/ffi-export/lossless.md", }, - Known { - language: "kotlin", - what: "a returned tuple of one passed back", - skips: single, - quest: "/quest/m1/ffi-export/round-trips.md", - }, Known { language: "go", what: "an IPv6 flow label", skips: ipv6, quest: "/quest/m1/ffi-export/lossless.md", }, - Known { - language: "cpp", - what: "a returned collection of bytes passed back", - skips: viewed_items, - quest: "/quest/m1/ffi-export/round-trips.md", - }, ]; /// A function the C header declares: each parameter's type and name. diff --git a/quest/m1/ffi-export/round-trips.md b/quest/m1/ffi-export/round-trips.md deleted file mode 100644 index 9112b66bf..000000000 --- a/quest/m1/ffi-export/round-trips.md +++ /dev/null @@ -1,26 +0,0 @@ -# [S] Every binding takes back what it returns - -## Goal - -A value a [rust2-ffi](/ffi/README.md) binding returns passes back into a parameter of the -same Rust type as it is, with no conversion by the caller. Two bindings break this today, -each a `KNOWN` entry in [the shape tests](/ffi/tests/fixtures/shapes.rs) that this quest -deletes: - -- C++ returns a collection of bytes, such as `Vec` or `BTreeMap>`, - as a `std::vector` of `buf`s, but takes it as a `const std::vector` of `view`s, which a - vector of `buf`s does not convert to. -- Kotlin returns a tuple of one, `(T,)`, as its `T`, but takes it as `Tuple1`. - -## Plan - -Found by the shape tests' nightly sample on 2026-11-13. - -- C++: take a collection whose items hold bytes as any range whose items convert to a - `view`, as `view` already takes any contiguous range of bytes, so a returned vector of - `buf`s, and the caller's vector of `std::string`s, pass as they are. -- Kotlin: return a tuple of one as `Tuple1`, as it takes one, rather than unwrapping it. - Swift has no tuple of one, so its unwrapping stays. - -Public API: C++'s parameter types for collections of bytes, which take more than before; -Kotlin's return type of a function returning a tuple of one (breaking).