The polyglot bindings generator for your library (C#, C, Python, …) 🐙

In order to use extern functions in burst, structs have to be passed by reference. If I try changing all my slices to be &mut slices, the extern functions are generated nicely with out SliceMut but I lose the other functions that are normally generated with them. (The ones with the pinning of arrays and conversion to SliceMut. If I want those helper functions for both Slice and &mut Slice does this mean that I need to add a pattern for handling the &mut version of a Slice the same way that the Slice is handled to the C# generator? As an aside I would also like the ability to generate slices from native arrays. I see that you've already got some Unity specific flagging, would you be interested in PRs to add some more Unity specific interoperability to the generated c# behind those flags?

Thank you for this awesome library!

It was really easy to get started with the provided examples, but I'm having hard time to return String (AsciiPointer) more than once from Rust to CS via the Service pattern.

With the following snippet I managed to return the string once, but the second call is causing the program to crash:

use crate::result::{Error, FFIError};
use interoptopus::{ffi_service, ffi_service_ctor, ffi_service_method, ffi_type};
use interoptopus::patterns::string::AsciiPointer;
use std::ffi::CString;

#[ffi_type(opaque)]
#[derive(Default)]
pub struct Sample {
    pub number: usize,
    name: CString,
}


#[ffi_service(error = "FFIError", prefix = "sample_")]
impl Sample {
    #[ffi_service_ctor]
    pub fn new_with(number: u32) -> Result<Self, Error> {
        Ok(Self {
            number: number as usize,
            name: CString::new(format!("HELLO_{}", number)).unwrap(),
        })
    }

    #[ffi_service_method(direct)]
    #[allow(non_snake_case)]
    pub fn Name(&self) -> AsciiPointer {
        // FIXME: Name can only be called once. second invocation causes crash.
        AsciiPointer::from_cstr(&self.name)
    }
}

interoptopus::inventory!(
    my_inventory, 
    [], 
    [], 
    [], 
    [Sample]);

My theory is that the Sample.CString gets freed after AsciiPointer::from_cstr is returned. I tried to solve this by introducing new lifetime for name, but didn't succeed: always ended up having obscure error coming from the ffi_service macro.

Any suggestion / help would be greatly appreciated!

I am using Interoptopus to generate C# bindings for Unity. This is my Generator:

    Generator::new(config, rust_lib::my_inventory())
        //.add_overload_writer(DotNet::new())
        .add_overload_writer(Unity::new())
        .write_file("bindings/csharp/Interop.cs")?;

I am trying to pass a mutable slice from C# to Rust and write into it like so:

#[ffi_function]
#[no_mangle]
pub extern "C" fn mutate_slice_u32(slice: &mut FFISliceMut<u32>) {
    let data = vec![1, 2, 3, 4, 5];
    for (idx, el) in data.iter().enumerate() {
        slice[idx] = *el;
    }
}

The relevant generated binding looks like this:

        [DllImport(NativeLib, CallingConvention = CallingConvention.Cdecl, EntryPoint = "mutate_slice_u32")]
        public static extern void mutate_slice_u32(ref SliceMutu32 slice);

        #if UNITY_2018_1_OR_NEWER
        public static void mutate_slice_u32(NativeArray<uint> slice)
        {
            var slice_slice = new SliceMutu32(slice);
            mutate_slice_u32(ref slice_slice);;
        }
        #endif

Issue is I am getting an error in Unity saying: Assets/Plugins/Interop.cs(53,35): error CS1729: 'SliceMutu32' does not contain a constructor that takes 1 arguments

Am I doing anything especially crazy here?

Added a function to remove items from an inventory which are present in any of a collection of other inventories, and return the result as a new inventory. I'm using this in a project where I want to generate multiple bindings files which expose different levels of access (private functions and public SDK functions). As the private consuming project needs to incorporate both bindings, I need to remove duplicate symbols.

I feel like there's no good way to access all of (instead of indexer (which copies data anyway)) the slice data in c# right now without copying it.

I propose adding a method to the c# generated version of FFISlice and FFISliceMut that has a ReadOnlySpan and Span respectively.

For example:

///A pointer to an array of data someone else owns which may be modified.
[Serializable]
[StructLayout(LayoutKind.Sequential)]
public partial struct SliceMutf32
{
    ///Pointer to start of mutable data.
    IntPtr data;
    ///Number of elements.
    ulong len;
}

public partial struct SliceMutf32
{
    public Span<float> AsSpan()
    {
        unsafe
        {
            return new Span<float>((float*)data, (int)len);
        }
    }
}

Not sure how you'd do it without unsafe though.

Should probably also make it optional, since Span is part of System.Memory which isn't included in the standard framework on all .net versions.

I've been looking around for this option and I don't think it exists. I'm basically looking to use types in function signatures like Vec3 or Mat4 which I already have full implementations of on the target language. I want the named types emitted in function signatures, but I don't want them declared on their own. I'm happy to take a look at implementing this, I think it would make the most sense as an attribute on ffi-type

Added ability to customise the config to select the naming style used for C types, enum variants, constants and function arguments.

I've added a dependency to the "heck" crate to perform the case conversion. If there is an objection to this I can implement the conversion methods natively in the library.

Would be useful to have an option in C# code generation config to customize access modifiers on generated classes/structs. In my usage of interoptopus, I'm creating a friendlier C# wrapper around a native DLL so would prefer not to expose the generated classes in the wrapper library interface. Currently I'm doing a regex find and replace on the file after generation to change the accessors to 'internal'.

Fix for #41. I initially tried to implement as a primitive, however unfortunately because c_char is just an alias for i8 in rust, this wasn't possible with the current way interoptopus implements primitives as by the time the type info gets to the backend, it appears as an i8.

My approach is to create a new pattern, FFICChar which explicitly represents a char in C. This is allows the backends to then handle this correctly. I've also added special handling for the Read/ReadWrite pointers to this type for C# because it's far more useful to express this as an IntPtr rather than a ref to an sbyte.

Not sure if i'm doing something wrong, but i'm fairly sure i'm not...

If you have an FFISlice parameter in a function it seems to point to garbage data or something on the rust side. But moving the same function to a service makes it work like expected.

I made a project as an example:

https://github.com/Skippeh/interoptopus_slice_issue

Outputs:

It seems to behave the same on 0.13.15. Haven't tried earlier versions.

I have only tried C# but i think the problem is in the rust code.

Hi, first of all thanks for the great library! I am able to return a AsciiPointer from a method of my service, but when I try to return a AsciiPointer nested in a struct I get a runtime error:

System.Runtime.InteropServices.MarshalDirectiveException: Method's type signature is not PInvoke compatible.
   at My.Company.Interop.counter_service_nested_string(IntPtr context)
   at My.Company.CounterService.NestedString() in C:\Users\nico\tmp\lib_test\bindgen\generated\Interop.cs:line 288
   at ConsoleApplication42.Program.Main(String[] args) in C:\Users\nico\source\tmp\ConsoleApplication42\ConsoleApplication42\Program.cs:line 51

edit: example is here: https://github.com/njust/interoptopus_test/blob/master/lib_test/src/lib.rs

Somewhat experimental idea, needs validation, also see #68:

Names tbd:

• A generic FFIPointer<T, SingleElementOrMultiple, RustRW, FFIRW> indicating how that pointer is being used (type T of target, single or multiple elements, and who reads and writes; bonus points if we can make T so that it also accepts and enum of type alternatives although I wouldn't know how to do that)
• various aliases to common FFIPointer<A, B, C, D> combinations.
• The generic FFIPointer would fallback to *T or *c_void in backends for now or could be used for other optimizations (e.g., deciding if an #[In, out] should be applied.
• bonus-bonus points if MultipleElements can also encode variable or constant many elements.

This pointer could also subsume Callbacks with the help of const generics, e.g., Callback<Name="Bla"> once &str are available.

Main questions to resolve are:

• Can this be implemented?
• Will this make writing APIs more ergonomic (e.g., better C# bindings w.r.t IntPtr, #[In/Out], ...)?
• Will this be cleaner or more messy than having multiple independent types (e.g., w.r.t. our maintenance)?

Added an ArrayPointer pattern. This is a lighter-weight alternative to the FFISlice pattern which allows expression of a pointer to an array of a type. This allows backends to generate more relevant bindings. Crucially, it forces the C# backend to declare the parameter as an IntPtr rather than a ref T (which makes little sense for an array of values).

The following changes I'd like to land in 0.15, help wanted

• [ ] Infer prefix in #[ffi_service] and make it optional
• [ ] Add sample how to use feature flags to disable Interoptopus unless generating bindings
• [ ] Improve the surrogate type situation, e.g., by instead relying on transmutable surrogates. Needs some thought.
• [ ] Maybe struct methods #29 (depends on how much work they are)
• [ ] Maybe implement #27, or rule out why they are a bad idea
• [ ] Make sure void service methods don't need annotations

To my pleasant surprise, I discovered that the AsciiPointer pattern plainly uses Rust CString, which is UTF-8 instead of ASCII. This is not an issue when transferring strings into Rust, as ASCII is a subset of UTF-8, so Rust will happily handle both. However, it might surprise users when accepting strings from Rust, when the Rust code accidentally outputs unicode characters (there's currently no check on this).

There seem to be two solutions to me: either perform a check in the Rust-implementation of AsciiPointer to make sure the string actually is ASCII, or, for me preferable, just support the unicode. For C both are null-terminated byte-strings anyway, so it just needs a clear warning sign for developers. For C# I've made a few small changes to the backend to explicitly marshal strings as UTF-8 which seems to work quite nicely (see https://github.com/seaeagle1/interoptopus/tree/utf8 ). I don't know much Python, but I'm sure it's also able to handle unicode strings.

If you look at the generated IEnumerable code, it generates a plain yield return enumerator. That means there's an allocation on every GetEnumerator call - which is normally avoided by providing a concrete StructEnumerator GetEnumerator() overload. The code seems to do a lot of redundant work (exception is checked on the indexer hot path, so indexer will never be inlined).

Would it make a bit more sense to return a ReadOnlySpan<T> view over the data? That would also give a bit of flexibility to the caller at no performance expense. That would also remove the inheritance information from the struct,s.

Dataful enums are a powerful feature of rust's type system, and unfortunately this means they are difficult to represent elegantly in many other languages. However, at minimum dataful enums in rust can be represented as a tagged union in C, and in languages with structural inheritance, this could be translated to a class or record type hierarchy. Adding support for dataful enums, even rudimentary support only mapping them to tagged unions in the target languages, would be a very valuable feature for rust interoperability.

As an example of a simple dataful enum on rust side:

#[repr(u32,C)]
pub enum Value {
    VByte(u8),
    VFloat(f32),
}

And its equivalent on the C# side, including the facility to perform basic matching on the variant:

public struct Value
{
    private enum Tag
    {
        VByte,
        VFloat,
    }

    [FieldOffset(0)] private Tag tag;
    [FieldOffset(4)] private Byte byte_data;
    [FieldOffset(4)] private Single float_data;

    public void Match(Action<byte> byte_f, Action<Single> float_f)
    {
        Match<object>(b =>
        {
            byte_f(b); return null;
        },
        f =>
        {
            float_f(f); return null;
        });
    }
    public R Match<R>(Func<byte, R> byte_f, Func<Single, R> float_f)
    {
        switch (tag)
        {
            case Tag.VByte:
                return byte_f(byte_data);
            case Tag.VFloat:
                return float_f(float_data);
            default:
                throw new ArgumentOutOfRangeException();
        }
    }
}

Optionally, this tagged union could be converted to a class hierarchy, if this is deemed valuable:

public abstract class ValueClass
{
    public static ValueClass From(Value v)
    {
        return v.Match<ValueClass>(
            b => new ByteValue(b),
            f => new FloatValue(f)
        );
    }
    public class ByteValue : ValueClass
    {
        public Byte b;

        public ByteValue(byte b)
        {
            this.b = b;
        }
    }
    public class FloatValue : ValueClass
    {
        public Single f;

        public FloatValue(float f)
        {
            this.f = f;
        }
    }
}