Design of the “higher level” interface

[Chris00]

IMHO, the main question is how to handle the subclass relationships. The other difficulty is that several functions return pointers to internal data structures, these require only a (non owning) thin wrapper around the pointer with a lifetime to track the dependency. So there are two classes of C++ “values”: owning values and references.

For subclasses, there is a variety of possibilities.

• Traits: this is nice because owning and references can be treated uniformly (impl T and impl T + 'a). The problem is that they have to be implemented for each subclass (one may want to think to a for of transitive system to minimize boilerplate) and they will have to be brought into scope. Constructors cannot be part of the trait (they many not have a uniform interface across subclasses). If several subclasses may populate a single variable, they will ahve to be treated as dyn Trait.
• Deref: the nice thing is that it is applied transitively by the compiler (so if A is a subclass of B and B of C, C methods are accessible from A without having to do anything). Also several subclasses may be converted to the base class and be handled as a reference to the base class. For this, we need two types of values, say T for owning values and AT for references, with T deref to AT. If T is a subclass of U, then the Derefs are as follows: T → AT → AU and U → AU. I have adopted the second approach in my attempt and it works well (although having, say, Mesh and AMesh is a bit ugly) but now is the time to revisit that.

Note that Autocxx implements AsRef (but not AsMut) when it detects a subclass relationship (this doesn't work for abstract classes).

To use Deref for subclasses, given the signature of Deref::deref, references have to be handled as Rust references &'a AT. This may be dangerous if C++ mutates the pointer “under our feet” as it is UB. There is an ongoing “discussion” to have more safety using a CppRef<T> type. It is actually already present in autocxx but not enabled by default.

What do you think?

[mkovaxx]

For context, a small snippet from the top of the current high-level lib.rs:

mfem-rs/crates/mfem/src/lib.rs

Lines 5 to 15 in 2c0964d

	trait AsBase<T> {
	fn as_base(&self) -> &T;
	}
	trait AsBaseMut<T> {
	fn as_base_mut(&mut self) -> std::pin::Pin<&mut T>;
	}
	trait IntoBase<T> {
	fn into_base(self) -> T;
	}

And also a small snippet from the bottom of my (now stale 😅) TODO.md:

mfem-rs/TODO.md

Lines 54 to 60 in 2c0964d

	- [ ] Phase out custom traits
	- [ ] `AsBase` -> `AsRef`
	- [ ] `IntoBase` -> `Into`
	## Stretch Goals
	- [ ] Revisit `SomethingRef` types

The custom traits came into existence because I didn't know about the built-in niceties around Deref and I was in a rush. I had two weeks to both get some code working and prepare to give a talk about it...

That's just a long-winded way to say: I'm totally on board with trying the "Deref Approach" from your suggestions above!

I also encountered the problem of needing both Something and SomethingRef types, and wanted to revisit it (see TODO item):

mfem-rs/crates/mfem/src/lib.rs

Lines 271 to 277 in 2c0964d

	pub struct GridFunction<'fes> {
	inner: UniquePtr<mfem_sys::ffi::GridFunction<'fes>>,
	}
	pub struct GridFunctionRef<'fes, 'a> {
	inner: &'a mfem_sys::ffi::GridFunction<'fes>,
	}

Based on details of the "Deref Approach" that you describe, this seems unavoidable. On the other hand, it doesn't seem too bad, especially if boilerplate code can mostly be eliminated by using macros as you're doing in your prototype.

TBH I have very mixed feelings about macros, having written some horrific stuff... 🤪 I think it's probably better to start by hand-rolling all the code, discovering which patterns are boilerplate-y, and then refactoring with macros when the code has stabilized.

[mkovaxx]

Another thing: I have a strong bias against hand-written unsafe stuff, even if it requires hand-written boilerplate in C++.

For example, I prefer having C++ boilerplate like this:

mfem-rs/crates/mfem-sys/include/wrapper.hpp

Lines 141 to 147 in 2c0964d

	auto LinearForm_as_Vector(LinearForm const& lf) -> Vector const& {
	return lf;
	}
	auto LinearForm_as_mut_Vector(LinearForm& lf) -> Vector& {
	return lf;
	}

Over having Rust boilerplate that uses unsafe like this:

mfem-rs/crates/mfem-sys/examples/ex1.rs

Lines 232 to 238 in ca54baf

	fn LinearForm_as_Vector(x: &LinearForm) -> &Vector {
	unsafe { std::mem::transmute::<&LinearForm, &Vector>(x) }
	}
	fn LinearForm_as_Vector_mut(x: Pin<&mut LinearForm>) -> Pin<&mut Vector> {
	unsafe { std::mem::transmute::<Pin<&mut LinearForm>, Pin<&mut Vector>>(x) }
	}

The reason is that the C++ code is completely safe, in the sense that it is type-checked. If I mess it up, the compiler will catch me. On the other hand, with the Rust code that uses std::mem::transmute, I'm completely on my own. If I make a mistake, I'll get a runtime failure.

If the unsafe Rust boilerplate is coming out of an automated tool like autocxx, that's a different story, and I would trust that more than hand-written unsafe stuff.