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

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 20 additions & 5 deletions ffi/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -438,6 +438,11 @@ Linux's exports, as the merge queue runs on, since a header names its targets.
built with the header. A binding checks the two match before any other call, so a header
and a library from different builds refuse to mix.
- **Panics** abort, as an `extern "C"` function's do.
- **Must-use returns**: a function returning a handle, a buffer, a waker, a value holding
any of those or a `Vec`, such as a record with a `String` field, a poll, or a fallible
call's `bool` is `<PREFIX>_MUST_USE`, C23's and C++17's `[[nodiscard]]`, or
GCC's and Clang's `warn_unused_result` before C23, since dropping it leaks or loses an
error. Docs are `/** */`, which Doxygen reads.
- **Android**: the build script links the library with 16 KB pages, which Google Play
requires of a 64-bit library from 2027-02-01 and an NDK before r28 does not do itself. A
panic or a failed check that aborts goes to logcat as `rust2-ffi` and to bionic's abort
Expand Down Expand Up @@ -547,8 +552,14 @@ packages place it in.
from. From C++20, either converts to `std::span<const std::uint8_t>`. A `view` or span
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<T>` is a `std::vector`, passed in place
when of a fixed-width integer other than `u8` (bytes) or `u128` or of a float. One whose
refuses for a view or `str()` of a temporary `buf`, and from Clang 23 `-Wlifetime-safety`
for one kept past its `buf` across statements: `buf` is a `[[gsl::Owner]]`, and `view`,
`slice`, and `items` are `[[gsl::Pointer]]`s. A `Vec<T>` is a `std::vector`. A list
parameter of a fixed-width integer other than `u8` (bytes) or `u128` or of a float, as
`&[f32]` or `Vec<u64>`, is a `slice<T>`, which Rust reads in place and copies only if it
keeps it: a pointer and a count, or any contiguous range of `T`, such as a
`std::vector`, a `std::array`, a C array, a braced list, or from C++20 a
`std::span<const T>`, which it converts back to. 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<buf>`, but not a range of temporaries. A `std::vector` moved in
Expand All @@ -557,7 +568,9 @@ packages place it in.
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`, an IP
address an `ip_addr`, and a `u128` a `u128`, each the C struct. `Option<T>` is `std::optional<T>`, a tuple `std::tuple`, and `Result<T, E>` a `result<T, E>`, whose `value()` aborts on an
error. A `[u8; N]` is a `std::array<std::uint8_t, N>`.
error. A `[u8; N]` is a `std::array<std::uint8_t, N>`. A `result`, `future`, `task`, or
`buf` is `[[nodiscard]]`, as Rust's `Result` and futures are `#[must_use]`: dropping
one unread loses an error, cancels a call, or reads bytes for nothing.
- **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
thread, one call at a time. One lent for a call Rust calls only during the call; one Rust
Expand All @@ -579,8 +592,10 @@ packages place it in.
loses nothing. `poll(waker)` polls once; `std::move(f).get()` blocks the thread;
`std::move(f).then(exec, callback)` polls on an executor and calls back there, returning
a `task` that cancels when destroyed, after which the callback has finished or never
runs and the executor is never called again; and from C++20, `co_await std::move(f).via(exec)` resumes the coroutine on the
executor. An executor is any callable taking a `void()` job to run once, later, on any
runs and the executor is never called again: a `task` dropped before its executor starts
the job never runs, though one dropped at once may lose that race to an executor on
another thread; and from C++20, `co_await std::move(f).via(exec)` resumes the coroutine
on the executor. An executor is any callable taking a `void()` job to run once, later, on any
thread: never inline, since a wake may come from inside Rust. Each wake that lands while
the future polls polls it again, and a future has one poller at a time, since awaiting
it moves it.
Expand Down
2 changes: 1 addition & 1 deletion ffi/moq/moq.c
Original file line number Diff line number Diff line change
Expand Up @@ -432,7 +432,7 @@ int main(void) {
CHECK(guarded != NULL && moq_hang_catalog_Stats_eq(guarded, want, NULL));
moq_hang_catalog_Stats_free(guarded);
moq_status held = 0;
moq_mux_catalog_Producer_Extra_mutate(catalog, lists_stats, &listed_stats, &mux_err, &held);
CHECK(!moq_mux_catalog_Producer_Extra_mutate(catalog, lists_stats, &listed_stats, &mux_err, &held));
CHECK(held == MOQ_STATUS_BORROWED);
moq_mux_catalog_Guard_Extra_stats_set(guard, NULL, NULL);
CHECK(moq_mux_catalog_Guard_Extra_commit(guard, &mux_err, NULL));
Expand Down
86 changes: 69 additions & 17 deletions ffi/runtime/rt.hpp
Original file line number Diff line number Diff line change
Expand Up @@ -3,18 +3,23 @@
// namespace, after `detail` names the export's C types. It throws nothing and reads no
// type information, so it builds with exceptions and RTTI off.

// Clang's checks of ownership, which a caller enables with `-Wconsumed -Wdangling`: an
// object is used after a move, or a view outlives the bytes it reads. Other compilers see
// nothing. A method callable "unknown" takes a reference parameter's object, whose state
// Clang does not track.
// Clang's checks of ownership, which a caller enables with `-Wconsumed -Wdangling`, and
// from Clang 23 `-Wlifetime-safety`: an object is used after a move, or a view outlives
// the bytes it reads, within a statement or across them. Other compilers see nothing. A
// method callable "unknown" takes a reference parameter's object, whose state Clang does
// not track. An owner holds what a pointer views.
#if defined(__clang__)
#define RUST2_FFI_OWNER(T) [[gsl::Owner(T)]]
#define RUST2_FFI_POINTER(T) [[gsl::Pointer(T)]]
#define RUST2_FFI_LIFETIMEBOUND [[clang::lifetimebound]]
#define RUST2_FFI_CONSUMABLE [[clang::consumable(unconsumed)]]
#define RUST2_FFI_CALLABLE [[clang::callable_when("unconsumed", "unknown")]]
#define RUST2_FFI_CONSUMES [[clang::callable_when("unconsumed", "unknown"), clang::set_typestate(consumed)]]
#define RUST2_FFI_UNCONSUMED [[clang::return_typestate(unconsumed)]]
#define RUST2_FFI_MOVED_FROM [[clang::return_typestate(consumed)]]
#else
#define RUST2_FFI_OWNER(T)
#define RUST2_FFI_POINTER(T)
#define RUST2_FFI_LIFETIMEBOUND
#define RUST2_FFI_CONSUMABLE
#define RUST2_FFI_CALLABLE
Expand Down Expand Up @@ -282,7 +287,7 @@ class borrow {

// Bytes lent to a call: text or binary, read during the call and never kept. A contiguous
// range, so from C++20 it converts to `std::span<const std::uint8_t>`, and back.
class view {
class RUST2_FFI_POINTER(::std::uint8_t) view {
const ::std::uint8_t *data_;
::std::size_t size_;

Expand Down Expand Up @@ -318,10 +323,55 @@ class view {
friend struct detail::access;
};

// Numbers lent to a call in place: a pointer and a count, or any contiguous range of `T`,
// such as a `std::vector<T>`, a `std::array<T, N>`, a C array, a braced list, or from
// C++20 a `std::span<const T>`, which it converts back to.
#if defined(__GNUC__) && !defined(__clang__)
#pragma GCC diagnostic push
#pragma GCC diagnostic ignored "-Winit-list-lifetime"
#endif
template <class T>
class RUST2_FFI_POINTER(T) slice {
const T *data_;
::std::size_t size_;

public:
slice() noexcept : data_(nullptr), size_(0) {}
slice(const T *data, ::std::size_t size) noexcept : data_(data), size_(size) {}
template <::std::size_t N>
slice(const T (&array RUST2_FFI_LIFETIMEBOUND)[N]) noexcept : data_(array), size_(N) {}
// A list's array lives until the call's full-expression ends, which GCC cannot see.
slice(::std::initializer_list<T> list RUST2_FFI_LIFETIMEBOUND) noexcept : data_(list.begin()), size_(list.size()) {}
template <class R,
class = ::std::enable_if_t<::std::is_same_v<
::std::remove_cv_t<::std::remove_pointer_t<decltype(::std::declval<const R &>().data())>>, T>>,
class = decltype(::std::declval<const R &>().size())>
slice(const R &range RUST2_FFI_LIFETIMEBOUND) noexcept : data_(range.data()), size_(range.size()) {}

const T *data() const noexcept {
return data_;
}
::std::size_t size() const noexcept {
return size_;
}
bool empty() const noexcept {
return size_ == 0;
}
const T *begin() const noexcept {
return data_;
}
const T *end() const noexcept {
return data_ + size_;
}
};
#if defined(__GNUC__) && !defined(__clang__)
#pragma GCC diagnostic pop
#endif

// Owned bytes: returned by Rust without a copy, or copied from C++. They outlive the object
// they came from; a view or span of them lives only as long as they do. A copy of Rust's
// shares its bytes, and one moved into a call's `input` goes back to Rust without a copy.
class buf {
class [[nodiscard]] RUST2_FFI_OWNER(::std::uint8_t) buf {
// Rust's when `owner` is set, else C++'s, allocated with `new[]` unless empty.
detail::c_buf raw_;

Expand Down Expand Up @@ -443,7 +493,7 @@ inline constexpr bool lasting = ::std::is_reference_v<Item> || ::std::is_same_v<
// or any other range whose items convert to `T`, such as the `std::vector<buf>` a call
// returned or a `std::vector<std::string>`, converted item by item.
template <class T>
class items {
class RUST2_FFI_POINTER(T) items {
::std::vector<T> converted_;
const T *data_;
::std::size_t size_;
Expand Down Expand Up @@ -533,7 +583,7 @@ class taken {

// What a fallible call returns: its value, or the error that stopped it.
template <class T, class E>
class result {
class [[nodiscard]] result {
::std::variant<T, E> value_;

template <::std::size_t I, class A>
Expand Down Expand Up @@ -603,7 +653,7 @@ class result {
};

template <class E>
class result<void, E> {
class [[nodiscard]] result<void, E> {
::std::optional<E> error_;

public:
Expand Down Expand Up @@ -752,8 +802,10 @@ void spawn(task &slot, typename Op::raw *raw, Exec exec, F f);

// A future running on an executor until it calls back with the output. Destroying it
// cancels the future: once that returns, the callback has finished or never runs, and the
// executor is never called again, so it may go too.
class task {
// executor is never called again, so it may go too. A task dropped before its executor
// starts the job never runs; one dropped at once may still lose that race to an executor
// on another thread.
class [[nodiscard]] task {
detail::task_node *node_ = nullptr;

void reset() noexcept {
Expand Down Expand Up @@ -784,7 +836,7 @@ class task {
// it before it finishes cancels it, which loses nothing, since a value leaves Rust only in
// the poll that finishes it.
template <class Op>
class future {
class [[nodiscard]] future {
typename Op::raw *raw_;
// The waker Rust holds from the last poll, which it reuses when given it again.
detail::node *last_ = nullptr;
Expand Down Expand Up @@ -1000,11 +1052,11 @@ class arena {
}
};

// The numbers of `items` as the C array `C`, in place: never null, so an empty one is
// told apart from a missing one.
template <class C, class T>
C block(const ::std::vector<T> &items) {
static const T empty{};
// The numbers of `items`, a `slice` or a `std::vector`, as the C array `C`, in place: never
// null, so an empty one is told apart from a missing one.
template <class C, class R>
C block(const R &items) {
static const ::std::remove_cv_t<::std::remove_pointer_t<decltype(items.data())>> empty{};
return C{items.empty() ? &empty : items.data(), items.size(), nullptr};
}

Expand Down
27 changes: 27 additions & 0 deletions ffi/src/abi.rs
Original file line number Diff line number Diff line change
Expand Up @@ -957,6 +957,33 @@ impl<'a> Abi<'a> {
}
}

/// Whether a value of `ty` holds memory Rust allocated.
pub(crate) fn owns(&self, ty: &Type) -> bool {
self.holds(ty, false)
}

/// Whether C's copy of a returned `ty` holds memory Rust allocated: a reference
/// returns as an owned copy of what it borrows.
pub(crate) fn returns_owned(&self, ty: &Type) -> bool {
self.holds(ty, true)
}

fn holds(&self, ty: &Type, refs: bool) -> bool {
match ty {
_ if Abi::is_buf(ty) => true,
Type::Object(_) | Type::List(..) => true,
Type::Ref(_, inner) if refs => self.holds(inner, refs),
Type::Option(inner) | Type::Box(inner) => self.holds(inner, refs),
Type::Tuple(elements) => elements.iter().any(|ty| self.holds(ty, refs)),
Type::Record(i) => self.api.records[*i].fields.iter().any(|f| self.holds(&f.ty, refs)),
Type::Enum(i) => self.api.enums[*i]
.variants
.iter()
.any(|v| v.fields.iter().any(|f| self.holds(&f.ty, refs))),
_ => false,
}
}

/// Whether `ty` crosses as a `<prefix>_buf`.
pub(crate) fn is_buf(ty: &Type) -> bool {
matches!(
Expand Down
Loading