helgoboss
commented
3 years ago
Obviously Rust can't use C++ classes (well, barring cxx/autocxx) so you have these
.cppand.hppwrappers around classes fromreaper_plugin.hwhich "flatten" them. Is the only thing that is required to make a C ABI compatible wrapper to:
- Make a
constructanddestructmethod to callnewanddelete- Make a "flattened" method for every method on the class, which takes the class instance as the first argument
Yes, bringing everything down to C level and then using the C ABI is enough. That's at least my approach to it and it seems to works reliably (it should, it's not magic). I don't know if this generally recommended. If I would have to do this very often, I would look into automating this and maybe cxx could help there (although I have the impression that it's more tailored to use cases where you have a lot of idiomatic C++ code, which REAPER API code is definitely not - it's more like 90% C and 10% C++). But fortunately REAPER doesn't use virtual methods all over the place so it's not much work to do it manually.
- I noticed that some classes and structs are present in your wrappers, like
PCM_source,PCM_source_transfer_t,REAPER_PeakGet_Interface. Is this because you have no use for them or some other reason?
My general strategy with reaper-rs is to only provide what I also use in my own stuff because I think only actually using a library in a real-world app can uncover potential library design flaws. What a coincidence that you mention above data types. I have been working on them during the last days, still on a branch at the time of this writing (https://github.com/helgoboss/reaper-rs/tree/feature/play-preview) but should go on the main branch today or tomorrow. I use it to implement a quite nice feature for ReaLearn, which I think you will like, too ;)
Your
midi.cppimplementation does not have ctor/dtor methods. Is this because this class only gets returned as a result of calling functions from other classes, indirectly?
Exactly. Only used for references to REAPER-managed data so far. However, the feature/play-preview branch makes some changes to it. E.g. it makes the MidiEvent also usable for Rust-owned data - it's just a wrapper around the non-opaque MIDI_event_t.
My current approach in the branch is to offer for each low-level data structure up to 3 medium-level types (depending on what's necessary):
- A completely owned struct (e.g.
OwnedPcmSource).- Either directly contains the data (for non-opaque C types) or contains a pointer and calls a C destructor on drop (for opaque C types).
- Automatically deferences to the borrowed struct.
- A simple pointer struct.
- Used whenever we only need to pass something around (e.g.
PcmSource) or something can only be passed around anyway because it's opaque (e.g.MediaTrack). - If it's a non-opaque struct, then one might want to dereference the pointer. However, unlike the owned struct, it doesn't automatically dereference to the borrowed struct because for all we know the pointer might be invalid. It can only be done explicitly using an
unsafeblock.
- Used whenever we only need to pass something around (e.g.
- A borrow-only struct (usable only as reference, e.g.
BorrowedPcmSource).- This is used whenever it's clear that we have a valid reference.
All the design rationale beyond that is described in the medium-level crate doc.
- I see that in your
bindings.rs, you have what look like mangled linkage names. I assume this is because you have astruct reaper_functionswhich contains all the function pointers in it, and you're building this struct in C/C++ and linking against it?
Those mangled names are irrelevant in this scenario. On Unix/macOS I'm not sure but on Windows I am because the bindings are always generated on Linux and generating them on Windows would generate other linkage names. I just use the signatures in the bindings.rs file. I parse them (using syn crate) and generate the reaper.rs file from it. It's all generated using multiple phases where the first one uses bindgen (see build.rs).
And if that's the case, that would mean these are empty function pointers until runtime, when they're loaded with
rec->GetFunc()?extern "C" { #[link_name = "\u{1}_ZN16reaper_functions19AddMediaItemToTrackE"] pub static mut AddMediaItemToTrack: ::std::option::Option< unsafe extern "C" fn(tr: *mut root::MediaTrack) -> *mut root::MediaItem, >; }
Exactly.
To the last point I thought maybe this could be the better way to go but wasn't sure about it (linking against
externexports which don't have a value until runtime, and even then areMaybe's).
Normal reaper_plugin_functions.h usage involves creation of hundrends of static function pointers which eventually get filled at runtime. Initially I wanted to go that way but because I like things to be scoped and local (and Rust also likes it) I decided to bundle all those function pointer fields in a Rust struct instead and provide an easy way to make that Rust struct static (make_available_globally()).
What I am doing in D-Lang is basically reflection over members of the struct and calling
rec.GetFunc()on them and casting the result to the type of the function pointer itself:tmp = cast(typeof(tmp)) rec.GetFunc(name); // Expands to: reaper.Reaper.AddCustomizableMenu = cast(typeof(reaper.Reaper.AddCustomizableMenu)) rec.GetFunc(AddCustomizableMenu);// D has "extern(C)" and "extern(C++)" for calling convention/ABI so the classes bit is straightforward extern (C++) class ProjectStateContext { public ~this() {} public abstract void AddLine(const(char)* fmt, ...); public abstract int GetLine(char* buf, int buflen); // ... } // "__gshared" is like Rc<Cell<T>> or Arc<Mutex<T>> __gshared struct Reaper { static: void function(void*, size_t, size_t, int function(const(void)*, const(void)*), void*) __mergesort; bool function(const(char)*, const(char)*, const(char)*, bool) AddCustomizableMenu; // ... } void load_reaper_api(reaper.reaper_plugin_info_t* rec) { foreach (name; __traits(allMembers, reaper.Reaper)) { mixin(`alias tmp = reaper.Reaper.`, name); mixin(q{ tmp = cast(typeof(tmp)) rec.GetFunc(name); if (tmp is null) throw new Exception("Failed to load REAPER function: " ~ name); }); } } extern (C) export int ReaperPluginEntry(HINSTANCE hInstance, reaper.reaper_plugin_info_t* rec) { if (!rec || !rec.GetFunc) return 0; load_reaper_api(rec); reaper.Reaper.ShowConsoleMsg("Hello world"); return 1; }
I don't know D-Lang unfortunately. In Rust there's no reflection. Also, I wanted everything to be as fast as the original and don't add any overhead (or only marginal one), so I avoid allocation and dynamic dispatch wherever possible. Some parts of the API are used in real-time threads and there everything must be fast.
I am interested in learning how to make C ABI wrappers and thought I might study + use your example here to write and publish a C ABI compatible
reaper_plugin.h+reaper_plugin_functions.h(so that I can use it with codegenerators, which most definitely do not like C++)
That's interesting! Having a totally flat version of the REAPER API sounds good.
All of that said, I'm not an expert in FFI. I just thought a lot about it, read a lot about Rust FFI, fell into traps multiple times and came up with this way of doing things.
GavinRay97
Hey Benjamin, sorry to file this under issues (could've mailed you) but thought maybe other people might have similar questions in the future.
I used the code and comments in
reaper-rs, and the REAPER native SDK to learn C, C++, and how interop/FFI work over the last 2 months.(Learned by the REAPER C++ API to other languages -- currently have translated 100% of classes/structs/functions to D-Lang, and have working examples of writing REAPER extensions in C#, Nim, and Python too).
There were a few questions I had, if you would be kind enough to answer.
.cppand.hppwrappers around classes fromreaper_plugin.hwhich "flatten" them. Is the only thing that is required to make a C ABI compatible wrapper to:constructanddestructmethod to callnewanddeletePCM_source,PCM_source_transfer_t,REAPER_PeakGet_Interface. Is this because you have no use for them or some other reason?midi.cppimplementation does not have ctor/dtor methods. Is this because this class only gets returned as a result of calling functions from other classes, indirectly?bindings.rs, you have what look like mangled linkage names. I assume this is because you have astruct reaper_functionswhich contains all the function pointers in it, and you're building this struct in C/C++ and linking against it? And if that's the case, that would mean these are empty function pointers until runtime, when they're loaded withrec->GetFunc()?To the last point I thought maybe this could be the better way to go but wasn't sure about it (linking against
externexports which don't have a value until runtime, and even then areMaybe's).What I am doing in D-Lang is basically reflection over members of the struct and calling
rec.GetFunc()on them and casting the result to the type of the function pointer itself:I am interested in learning how to make C ABI wrappers and thought I might study + use your example here to write and publish a C ABI compatible
reaper_plugin.h+reaper_plugin_functions.h(so that I can use it with codegenerators, which most definitely do not like C++)Thank you =D