• Stars
    star
    558
  • Rank 77,128 (Top 2 %)
  • Language
    Rust
  • License
    MIT License
  • Created about 1 year ago
  • Updated 29 days ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Generate C# FFI from Rust for automatically brings native code and C native library to .NET and Unity.

csbindgen

Crates Api Rustdoc

Generate C# FFI from Rust for automatically brings native code and C native library to .NET and Unity.

Automatically generates C# DllImport code from Rust extern "C" fn code. Whereas DllImport defaults to the Windows calling convention and requires a lot of configuration for C calls, csbindgen generates code optimized for "Cdecl" calls. Also .NET and Unity have different callback invocation methods (.NET uses function pointers, while Unity uses MonoPInvokeCallback), but you can output code for either by configuration.

When used with Rust's excellent C integration, you can also bring C libraries into C#.

There are usually many pains involved in using the C Library with C#. Not only is it difficult to create bindings, but cross-platform builds are very difficult. In this day and age, you have to build for multiple platforms and architectures, windows, osx, linux, android, ios, each with x64, x86, arm.

Rust has an excellent toolchain for cross-platform builds, as well as cc crate, cmake crate allow C source code to be integrated into the build. And rust-bindgen, which generates bindings from .h, is highly functional and very stable.

csbindgen can easily bring native C libraries into C# through Rust. csbindgen generates Rust extern code and C# DllImport code to work with C# from code generated from C by bindgen. With cc crate or cmake crate, C code is linked to the single rust native library.

showcase:

Getting Started

Install on Cargo.toml as build-dependencies and set up bindgen::Builder on build.rs.

[lib]
crate-type = ["cdylib"]

[build-dependencies]
csbindgen = "1.7.4"

Rust to C#.

You can bring Rust FFI code to C#.

// lib.rs, simple FFI code
#[no_mangle]
pub extern "C" fn my_add(x: i32, y: i32) -> i32 {
    x + y
}

Setup csbindgen code to build.rs.

fn main() {
    csbindgen::Builder::default()
        .input_extern_file("lib.rs")
        .csharp_dll_name("nativelib")
        .generate_csharp_file("../dotnet/NativeMethods.g.cs")
        .unwrap();
}

It will generate this C# code.

// NativeMethods.g.cs
using System;
using System.Runtime.InteropServices;

namespace CsBindgen
{
    internal static unsafe partial class NativeMethods
    {
        const string __DllName = "nativelib";

        [DllImport(__DllName, EntryPoint = "my_add", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)]
        public static extern int my_add(int x, int y);
    }
}

C (to Rust) to C#

For example, build lz4 compression library.

// using bindgen, generate binding code
bindgen::Builder::default()
    .header("c/lz4/lz4.h")
    .generate().unwrap()
    .write_to_file("lz4.rs").unwrap();

// using cc, build and link c code
cc::Build::new().file("lz4.c").compile("lz4");

// csbindgen code, generate both rust ffi and C# dll import
csbindgen::Builder::default()
    .input_bindgen_file("lz4.rs")            // read from bindgen generated code
    .rust_file_header("use super::lz4::*;")     // import bindgen generated modules(struct/method)
    .csharp_entry_point_prefix("csbindgen_") // adjust same signature of rust method and C# EntryPoint
    .csharp_dll_name("liblz4")
    .generate_to_file("lz4_ffi.rs", "../dotnet/NativeMethods.lz4.g.cs")
    .unwrap();

It will generates like these code.

// lz4_ffi.rs

#[allow(unused)]
use ::std::os::raw::*;

use super::lz4::*;

#[no_mangle]
pub unsafe extern "C" fn csbindgen_LZ4_compress_default(src: *const c_char, dst: *mut c_char, srcSize:  c_int, dstCapacity:  c_int) ->  c_int
{
    LZ4_compress_default(src, dst, srcSize, dstCapacity)
}
// NativeMethods.lz4.g.cs

using System;
using System.Runtime.InteropServices;

namespace CsBindgen
{
    internal static unsafe partial class NativeMethods
    {
        const string __DllName = "liblz4";

        [DllImport(__DllName, EntryPoint = "csbindgen_LZ4_compress_default", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)]
        public static extern int LZ4_compress_default(byte* src, byte* dst, int srcSize, int dstCapacity);
    }
}

Finally import generated module on lib.rs.

// lib.rs, import generated codes.
#[allow(dead_code)]
#[allow(non_snake_case)]
#[allow(non_camel_case_types)]
#[allow(non_upper_case_globals)]
mod lz4;

#[allow(dead_code)]
#[allow(non_snake_case)]
#[allow(non_camel_case_types)]
mod lz4_ffi;

Builder options(configure template)

Builder options: Rust to C#

Rust to C#, use the input_extern_file -> setup options -> generate_csharp_file.

csbindgen::Builder::default()
    .input_extern_file("src/lib.rs")        // required
    .csharp_dll_name("mynativelib")         // required
    .csharp_class_name("NativeMethods")     // optional, default: NativeMethods
    .csharp_namespace("CsBindgen")          // optional, default: CsBindgen
    .csharp_class_accessibility("internal") // optional, default: internal
    .csharp_entry_point_prefix("")          // optional, default: ""
    .csharp_method_prefix("")               // optional, default: ""
    .csharp_use_function_pointer(true)      // optional, default: true
    .csharp_disable_emit_dll_name(false)    // optional, default: false
    .csharp_imported_namespaces("MyLib")    // optional, default: empty
    .csharp_generate_const (false)          // optional, default: false
    .csharp_dll_name_if("UNITY_IOS && !UNITY_EDITOR", "__Internal") // optional, default: ""
    .generate_csharp_file("../dotnet-sandbox/NativeMethods.cs")     // required
    .unwrap();

csharp_* configuration will be embedded in the placeholder of the output file.

using System;
using System.Runtime.InteropServices;
using {csharp_imported_namespaces};

namespace {csharp_namespace}
{
    {csharp_class_accessibility} static unsafe partial class {csharp_class_name}
    {
#if {csharp_dll_name_if(if_symbol,...)}
        const string __DllName = "{csharp_dll_name_if(...,if_dll_name)}";
#else
        const string __DllName = "{csharp_dll_name}";
#endif
    }

    {csharp_generate_const}

    [DllImport(__DllName, EntryPoint = "{csharp_entry_point_prefix}LZ4_versionNumber", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)]
    public static extern int {csharp_method_prefix}LZ4_versionNumber();
}

csharp_dll_name_if is optional. If specified, #if allows two DllName to be specified, which is useful if the name must be __Internal at iOS build.

csharp_disable_emit_dll_name is optional, if set to true then don't emit const string __DllName. It is useful for generate same class-name from different builder.

csharp_generate_const is optional, if set to true then generate C# const field from Rust const.

input_extern_file and input_bindgen_file allow mulitple call, if you need to add dependent struct, use this.

csbindgen::Builder::default()
    .input_extern_file("src/lib.rs")
    .input_extern_file("src/struct_modules.rs")
    .generate_csharp_file("../dotnet-sandbox/NativeMethods.cs");

also csharp_imported_namespaces can call multiple times.

Unity Callback

csharp_use_function_pointer configures how generate function pointer. The default is to generate a delegate*, but Unity does not support it; setting it to false will generate a Func/Action that can be used with MonoPInvokeCallback.

// true(default) generates delegate*
[DllImport(__DllName, EntryPoint = "callback_test", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)]
public static extern int callback_test(delegate* unmanaged[Cdecl]<int, int> cb);

// You can define like this callback method.
[UnmanagedCallersOnly(CallConvs = new[] { typeof(CallConvCdecl) })]
static int Method(int x) => x * x;

// And use it.
callback_test(&Method);

// ---

// false will generates {method_name}_{parameter_name}_delegate, it is useful for Unity
[UnmanagedFunctionPointer(CallingConvention.Cdecl)]
public delegate int callback_test_cb_delegate(int a);

[DllImport(__DllName, EntryPoint = "callback_test", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)]
public static extern int callback_test(callback_test_cb_delegate cb);

// Unity can define callback method as MonoPInvokeCallback
[MonoPInvokeCallback(typeof(NativeMethods.callback_test_cb_delegate))]
static int Method(int x) => x * x;

// And use it.
callback_test(Method);

Builder options: C (to Rust) to C#

input_bindgen_file -> setup options -> generate_to_file to use C to C# workflow.

csbindgen::Builder::default()
    .input_bindgen_file("src/lz4.rs")             // required
    .method_filter(|x| { x.starts_with("LZ4") } ) // optional, default: |x| !x.starts_with('_')
    .rust_method_prefix("csbindgen_")             // optional, default: "csbindgen_"
    .rust_file_header("use super::lz4::*;")       // optional, default: ""
    .rust_method_type_path("lz4")                 // optional, default: ""
    .csharp_dll_name("lz4")                       // required
    .csharp_class_name("NativeMethods")           // optional, default: NativeMethods
    .csharp_namespace("CsBindgen")                // optional, default: CsBindgen
    .csharp_class_accessibility("internal")       // optional, default: internal
    .csharp_entry_point_prefix("csbindgen_")      // required, you must set same as rust_method_prefix
    .csharp_method_prefix("")                     // optional, default: ""
    .csharp_use_function_pointer(true)            // optional, default: true
    .csharp_imported_namespaces("MyLib")          // optional, default: empty
    .csharp_generate_const (false)                // optional, default: false
    .csharp_dll_name_if("UNITY_IOS && !UNITY_EDITOR", "__Internal") // optional, default: ""
    .generate_to_file("src/lz4_ffi.rs", "../dotnet-sandbox/lz4_bindgen.cs") // required
    .unwrap();

It will be embedded in the placeholder of the output file.

#[allow(unused)]
use ::std::os::raw::*;

{rust_file_header}

#[no_mangle]
pub unsafe extern "C" fn {rust_method_prefix}LZ4_versionNumber() ->  c_int
{
    {rust_method_type_path}::LZ4_versionNumber()
}

csharp_* option template is same as Rust to C#, see above documentation.

Adjust rust_file_header for match your module configuration, recommend to use ::*, also using rust_method_type_path that add explicitly resolve path.

method_filter allows you to specify which methods to exclude; if unspecified, methods prefixed with _ are excluded by default. C libraries are usually published with a specific prefix. For example, LZ4 is LZ4, ZStandard is ZSTD_, quiche is quiche_, Bullet Physics SDK is b3.

rust_method_prefix and csharp_method_prefix or csharp_entry_point_prefix must be adjusted to match the method name to be called.

Library Loading

If the file path to be loaded needs to be changed depending on the operating system, the following load code can be used.

internal static unsafe partial class NativeMethods
{
    // https://docs.microsoft.com/en-us/dotnet/standard/native-interop/cross-platform
    // Library path will search
    // win => __DllName, __DllName.dll
    // linux, osx => __DllName.so, __DllName.dylib

    static NativeMethods()
    {
        NativeLibrary.SetDllImportResolver(typeof(NativeMethods).Assembly, DllImportResolver);
    }

    static IntPtr DllImportResolver(string libraryName, Assembly assembly, DllImportSearchPath? searchPath)
    {
        if (libraryName == __DllName)
        {
            var path = "runtimes/";
            var extension = "";

            if (RuntimeInformation.IsOSPlatform(OSPlatform.Windows))
            {
                path += "win-";
                extension = ".dll";
            }
            else if (RuntimeInformation.IsOSPlatform(OSPlatform.OSX))
            {
                path += "osx-";
                extension = ".dylib";
            }
            else
            {
                path += "linux-";
                extension = ".so";
            }

            if (RuntimeInformation.OSArchitecture == Architecture.X86)
            {
                path += "x86";
            }
            else if (RuntimeInformation.OSArchitecture == Architecture.X64)
            {
                path += "x64";
            }
            else if (RuntimeInformation.OSArchitecture == Architecture.Arm64)
            {
                path += "arm64";
            }

            path += "/native/" + __DllName + extension;

            return NativeLibrary.Load(Path.Combine(AppContext.BaseDirectory, path), assembly, searchPath);
        }

        return IntPtr.Zero;
    }
}

If Unity, configure Platform settings in each native library's inspector.

Grouping Extension Methods

In an object-oriented style, it is common to create methods that take a pointer to a state (this) as their first argument. With csbindgen, you can group these methods using extension methods by specifying a Source Generator on the C# side.

Install csbindgen from NuGet, and specify [GroupedNativeMethods] for the partial class of the generated extension methods.

PM> Install-Package csbindgen

// create new file and write same type-name with same namespace
namespace CsBindgen
{
    // append `GroupedNativeMethods` attribute
    [GroupedNativeMethods()]
    internal static unsafe partial class NativeMethods
    {
    }
}
// original methods
[DllImport(__DllName, EntryPoint = "counter_context_insert", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)]
public static extern void counter_context_insert(counter_context* context, int value);

// generated methods
public static void Insert(this ref global::CsBindgen.counter_context @context, int @value)

// ----

counter_context* context = NativeMethods.create_counter_context();

// standard style
NativeMethods.counter_context_insert(context, 10);

// generated style
context->Insert(10);

GroupedNativeMethods has four configuration parameters.

public GroupedNativeMethodsAttribute(
    string removePrefix = "",
    string removeSuffix = "",
    bool removeUntilTypeName = true,
    bool fixMethodName = true)

removeUntilTypeName will remove until find type-name in method-name. For example foo_counter_context_insert(countext_context* foo) -> Insert. As a result, it is recommended to use a naming convention where the same type name is placed immediately before the verb.

Type Marshalling

Rust types will map these C# types.

Rust C#
c_char byte
c_schar sbyte
c_uchar byte
c_short short
c_ushort ushort
c_int int
c_uint uint
c_long CLong
c_ulong CULong
c_longlong long
c_ulonglong ulong
c_float float
c_double double
c_void void
CString sbyte
i8 sbyte
i16 short
i32 int
i64 long
i128 Int128
isize nint
u8 byte
u16 ushort
u32 uint
u64 ulong
u128 UInt128
usize nuint
f32 float
f64 double
bool [MarshalAs(UnmanagedType.U1)]bool
char uint
() void
#[repr(C)]Struct [StructLayout(LayoutKind.Sequential)]Struct
#[repr(C)]Union [StructLayout(LayoutKind.Explicit)]Struct
#[repr(u*/i*)]Enum Enum
bitflags! [Flags]Enum
extern "C" fn delegate* unmanaged[Cdecl]<> or Func<>/Action<>
Option<extern "C" fn> delegate* unmanaged[Cdecl]<> or Func<>/Action<>
*mut T T*
*const T T*
*mut *mut T T**
*const *const T T**
*mut *const T T**
*const *mut T T**

csbindgen is designed to return primitives that do not cause marshalling. It is better to convert from pointers to Span yourself than to do the conversion implicitly and in a black box. This is a recent trend, such as the addition of DisableRuntimeMarshalling from .NET 7.

c_long and c_ulong will convert to CLong, CULong struct after .NET 6. If you want to convert in Unity, you will need Shim.

// Currently Unity is .NET Standard 2.1 so does not exist CLong and CULong
namespace System.Runtime.InteropServices
{
    internal struct CLong
    {
        public int Value; // #if Windows = int, Unix x32 = int, Unix x64 = long
    }

    internal struct CULong
    {
        public uint Value; // #if Windows = uint, Unix x32 = uint, Unix x64 = ulong
    }
}

Struct

csbindgen supports Struct, you can define #[repr(C)] struct on method parameter or return value.

// If you define this struct...
#[repr(C)]
pub struct MyVector3 {
    pub x: f32,
    pub y: f32,
    pub z: f32,
}

#[no_mangle]
pub extern "C" fn pass_vector3(v3: MyVector3) {
    println!("{}, {}, {}", v3.x, v3.y, v3.z);
}
// csbindgen generates this C# struct
[StructLayout(LayoutKind.Sequential)]
internal unsafe partial struct MyVector3
{
    public float x;
    public float y;
    public float z;
}

Also supports tuple struct, it will generate Item* fields in C#.

#[repr(C)]
pub struct MyIntVec3(i32, i32, i32);
[StructLayout(LayoutKind.Sequential)]
internal unsafe partial struct MyIntVec3
{
    public int Item1;
    public int Item2;
    public int Item3;
}

It also supports unit struct, but there is no C# struct that is synonymous with Rust's unit struct (0 byte), so it cannot be materialized. Instead of using void*, it is recommended to use typed pointers.

// 0-byte
#[repr(C)]
pub struct CounterContext;
// 1-byte
[StructLayout(LayoutKind.Sequential)]
internal unsafe partial struct CounterContext
{
}
// recommend to use as pointer, in C#, holds CounterContext*
#[no_mangle]
pub extern "C" fn create_counter_context() -> *mut CounterContext {
    let ctx = Box::new(InternalCounterContext {
        set: HashSet::new(),
    });
    Box::into_raw(ctx) as *mut CounterContext
}

#[no_mangle]
pub unsafe extern "C" fn counter_context_insert(context: *mut CounterContext, value: i32) {
    let mut counter = Box::from_raw(context as *mut InternalCounterContext);
    counter.set.insert(value);
    Box::into_raw(counter);
}

#[no_mangle]
pub unsafe extern "C" fn destroy_counter_context(context: *mut CounterContext) {
    _ = Box::from_raw(context as *mut InternalCounterContext);
}

Union

Union will generate [FieldOffset(0)] struct.

#[repr(C)]
pub union MyUnion {
    pub foo: i32,
    pub bar: i64,
}

#[no_mangle]
pub extern "C" fn return_union() -> MyUnion {
    MyUnion { bar: 53 }
}
[StructLayout(LayoutKind.Explicit)]
internal unsafe partial struct MyUnion
{
    [FieldOffset(0)]
    public int foo;
    [FieldOffset(0)]
    public long bar;
}

Enum

#[repr(i*)] or #[repr(u*)] defined Enum is supported.

#[repr(u8)]
pub enum ByteEnum {
    A = 1,
    B = 2,
    C = 10,
}
internal enum ByteTest : byte
{
    A = 1,
    B = 2,
    C = 10,
}

bitflags Enum

csbindgen supports bitflags crate.

bitflags! {
    #[repr(C)]
    #[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
    struct EnumFlags: u32 {
        const A = 0b00000001;
        const B = 0b00000010;
        const C = 0b00000100;
        const ABC = Self::A.bits() | Self::B.bits() | Self::C.bits();
    }
}
[Flags]
internal enum EnumFlags : uint
{
    A = 0b00000001,
    B = 0b00000010,
    C = 0b00000100,
    ABC = A | B | C,
}

Function

You can receive, return function to/from C#.

#[no_mangle]
pub extern "C" fn csharp_to_rust(cb: extern "C" fn(x: i32, y: i32) -> i32) {
    let sum = cb(10, 20); // invoke C# method
    println!("{sum}");
}

#[no_mangle]
pub extern "C" fn rust_to_csharp() -> extern fn(x: i32, y: i32) -> i32 {
    sum // return rust method
}

extern "C" fn sum(x:i32, y:i32) -> i32 {
    x + y
}

In default, csbindgen generates extern "C" fn as delegate* unmanaged[Cdecl]<>.

[DllImport(__DllName, EntryPoint = "csharp_to_rust", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)]
public static extern void csharp_to_rust(delegate* unmanaged[Cdecl]<int, int, int> cb);

[DllImport(__DllName, EntryPoint = "rust_to_csharp", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)]
public static extern delegate* unmanaged[Cdecl]<int, int, int> rust_to_csharp();

It can use in C# like this.

// C# -> Rust, pass static UnmanagedCallersOnly method with `&`
[UnmanagedCallersOnly(CallConvs = new[] { typeof(CallConvCdecl) })]
static int Sum(int x, int y) => x + y;

NativeMethods.csharp_to_rust(&Sum);

// Rust -> C#, get typed delegate*
var f = NativeMethods.rust_to_csharp();

var v = f(20, 30);
Console.WriteLine(v); // 50

Unity can not use C# 9.0 function pointer, csbindgen has to use MonoPInvokeCallback options. see: Unity Callback section.

Rust FFI suppots Option<fn>, it can receive null pointer.

#[no_mangle]
pub extern "C" fn nullable_callback_test(cb: Option<extern "C" fn(a: i32) -> i32>) -> i32 {
    match cb {
        Some(f) => f(100),
        None => -1,
    }
}
var v = NativeMethods.nullable_callback_test(null); // -1

Pointer

Allocated Rust memory in heap can send to C# via pointer and Box::into_raw and Box::from_raw.

#[no_mangle]
pub extern "C" fn create_context() -> *mut Context {
    let ctx = Box::new(Context { foo: true });
    Box::into_raw(ctx)
}

#[no_mangle]
pub extern "C" fn delete_context(context: *mut Context) {
    unsafe { Box::from_raw(context) };
}

#[repr(C)]
pub struct Context {
    pub foo: bool,
    pub bar: i32,
    pub baz: u64
}
var context = NativeMethods.create_context();

// do anything...

NativeMethods.delete_context(context);

You can also pass memory allocated by C# to Rust (use fixed or GCHandle.Alloc(Pinned)). The important thing is that memory allocated in Rust must release in Rust and memory allocated in C# must release in C#.

If you want to pass a non FFI Safe struct, cast it to *mut c_void. Then C# will treat it as a void*. csbindgen does not support Opaque Type. Additionally, by returning a unit struct instead of c_void, you can create a typed handler.

#[no_mangle]
pub extern "C" fn create_counter_context() -> *mut CounterContext {
    let ctx = Box::new(InternalCounterContext {
        set: HashSet::new(),
    });
    Box::into_raw(ctx) as *mut c_void
}

#[no_mangle]
pub unsafe extern "C" fn insert_counter_context(context: *mut CounterContext, value: i32) {
    let mut counter = Box::from_raw(context as *mut InternalCounterContext);
    counter.set.insert(value);
    Box::into_raw(counter);
}

#[no_mangle]
pub unsafe extern "C" fn delete_counter_context(context: *mut CounterContext) {
    let counter = Box::from_raw(context as *mut InternalCounterContext);
    for value in counter.set.iter() {
        println!("counter value: {}", value)
    }
}

#[repr(C)]
pub struct CounterContext;

// no repr(C)
pub struct InternalCounterContext {
    pub set: HashSet<i32>,
}
var ctx = NativeMethods.create_counter_context();
    
NativeMethods.insert_counter_context(ctx, 10);
NativeMethods.insert_counter_context(ctx, 20);

NativeMethods.delete_counter_context(ctx);

In this case, recommed to use with Grouping Extension Methods.

If you want to pass null-pointer, in rust side, convert to Option by as_ref().

#[no_mangle]
pub unsafe extern "C" fn null_pointer_test(p: *const u8) {
    let ptr = unsafe { p.as_ref() };
    match ptr {
        Some(p2) => print!("pointer address: {}", *p2),
        None => println!("null pointer!"),
    };
}
// in C#, invoke by null.
NativeMethods.null_pointer_test(null);

String and Array(Span)

Rust's String, Array(Vec) and C#'s String, Array is different thing. Since it cannot be shared, pass it with a pointer and handle it with slice(Span) or materialize it if necessary.

CString is null-terminated string. It can send by *mut c_char and received as byte* in C#.

#[no_mangle]
pub extern "C" fn alloc_c_string() -> *mut c_char {
    let str = CString::new("foo bar baz").unwrap();
    str.into_raw()
}

#[no_mangle]
pub unsafe extern "C" fn free_c_string(str: *mut c_char) {
    unsafe { CString::from_raw(str) };
}
// null-terminated `byte*` or sbyte* can materialize by new String()
var cString = NativeMethods.alloc_c_string();
var str = new String((sbyte*)cString);
NativeMethods.free_c_string(cString);

Rust's String is UTF-8(Vec<u8>) but C# String is UTF-16. Andalso, Vec<> can not send to C# so require to convert pointer and control memory manually. Here is the buffer manager for FFI.

#[repr(C)]
pub struct ByteBuffer {
    ptr: *mut u8,
    length: i32,
    capacity: i32,
}

impl ByteBuffer {
    pub fn len(&self) -> usize {
        self.length
            .try_into()
            .expect("buffer length negative or overflowed")
    }

    pub fn from_vec(bytes: Vec<u8>) -> Self {
        let length = i32::try_from(bytes.len()).expect("buffer length cannot fit into a i32.");
        let capacity =
            i32::try_from(bytes.capacity()).expect("buffer capacity cannot fit into a i32.");

        // keep memory until call delete
        let mut v = std::mem::ManuallyDrop::new(bytes);

        Self {
            ptr: v.as_mut_ptr(),
            length,
            capacity,
        }
    }

    pub fn from_vec_struct<T: Sized>(bytes: Vec<T>) -> Self {
        let element_size = std::mem::size_of::<T>() as i32;

        let length = (bytes.len() as i32) * element_size;
        let capacity = (bytes.capacity() as i32) * element_size;

        let mut v = std::mem::ManuallyDrop::new(bytes);

        Self {
            ptr: v.as_mut_ptr() as *mut u8,
            length,
            capacity,
        }
    }

    pub fn destroy_into_vec(self) -> Vec<u8> {
        if self.ptr.is_null() {
            vec![]
        } else {
            let capacity: usize = self
                .capacity
                .try_into()
                .expect("buffer capacity negative or overflowed");
            let length: usize = self
                .length
                .try_into()
                .expect("buffer length negative or overflowed");

            unsafe { Vec::from_raw_parts(self.ptr, length, capacity) }
        }
    }

    pub fn destroy_into_vec_struct<T: Sized>(self) -> Vec<T> {
        if self.ptr.is_null() {
            vec![]
        } else {
            let element_size = std::mem::size_of::<T>() as i32;
            let length = (self.length * element_size) as usize;
            let capacity = (self.capacity * element_size) as usize;

            unsafe { Vec::from_raw_parts(self.ptr as *mut T, length, capacity) }
        }
    }

    pub fn destroy(self) {
        drop(self.destroy_into_vec());
    }
}
// C# side span utility
partial struct ByteBuffer
{
    public unsafe Span<byte> AsSpan()
    {
        return new Span<byte>(ptr, length);
    }

    public unsafe Span<T> AsSpan<T>()
    {
        return MemoryMarshal.CreateSpan(ref Unsafe.AsRef<T>(ptr), length / Unsafe.SizeOf<T>());
    }
}

With ByteBuffer, you can send Vec<> to C#. the pattern for String, Vec<u8>, Vec<i32>, Rust -> C# is as follows.

#[no_mangle]
pub extern "C" fn alloc_u8_string() -> *mut ByteBuffer {
    let str = format!("foo bar baz");
    let buf = ByteBuffer::from_vec(str.into_bytes());
    Box::into_raw(Box::new(buf))
}

#[no_mangle]
pub unsafe extern "C" fn free_u8_string(buffer: *mut ByteBuffer) {
    let buf = Box::from_raw(buffer);
    // drop inner buffer, if you need String, use String::from_utf8_unchecked(buf.destroy_into_vec()) instead.
    buf.destroy();
}

#[no_mangle]
pub extern "C" fn alloc_u8_buffer() -> *mut ByteBuffer {
    let vec: Vec<u8> = vec![1, 10, 100];
    let buf = ByteBuffer::from_vec(vec);
    Box::into_raw(Box::new(buf))
}

#[no_mangle]
pub unsafe extern "C" fn free_u8_buffer(buffer: *mut ByteBuffer) {
    let buf = Box::from_raw(buffer);
    // drop inner buffer, if you need Vec<u8>, use buf.destroy_into_vec() instead.
    buf.destroy();
}

#[no_mangle]
pub extern "C" fn alloc_i32_buffer() -> *mut ByteBuffer {
    let vec: Vec<i32> = vec![1, 10, 100, 1000, 10000];
    let buf = ByteBuffer::from_vec_struct(vec);
    Box::into_raw(Box::new(buf))
}

#[no_mangle]
pub unsafe extern "C" fn free_i32_buffer(buffer: *mut ByteBuffer) {
    let buf = Box::from_raw(buffer);
    // drop inner buffer, if you need Vec<i32>, use buf.destroy_into_vec_struct::<i32>() instead.
    buf.destroy();
}
var u8String = NativeMethods.alloc_u8_string();
var u8Buffer = NativeMethods.alloc_u8_buffer();
var i32Buffer = NativeMethods.alloc_i32_buffer();
try
{
    var str = Encoding.UTF8.GetString(u8String->AsSpan());
    Console.WriteLine(str);

    Console.WriteLine("----");

    var buffer = u8Buffer->AsSpan();
    foreach (var item in buffer)
    {
        Console.WriteLine(item);
    }

    Console.WriteLine("----");

    var i32Span = i32Buffer->AsSpan<int>();
    foreach (var item in i32Span)
    {
        Console.WriteLine(item);
    }
}
finally
{
    NativeMethods.free_u8_string(u8String);
    NativeMethods.free_u8_buffer(u8Buffer);
    NativeMethods.free_i32_buffer(i32Buffer);
}

C# to Rust would be a bit simpler to send, just pass byte* and length. In Rust, use std::slice::from_raw_parts to create slice.

#[no_mangle]
pub unsafe extern "C" fn csharp_to_rust_string(utf16_str: *const u16, utf16_len: i32) {
    let slice = std::slice::from_raw_parts(utf16_str, utf16_len as usize);
    let str = String::from_utf16(slice).unwrap();
    println!("{}", str);
}

#[no_mangle]
pub unsafe extern "C" fn csharp_to_rust_utf8(utf8_str: *const u8, utf8_len: i32) {
    let slice = std::slice::from_raw_parts(utf8_str, utf8_len as usize);
    let str = String::from_utf8_unchecked(slice.to_vec());
    println!("{}", str);
}


#[no_mangle]
pub unsafe extern "C" fn csharp_to_rust_bytes(bytes: *const u8, len: i32) {
    let slice = std::slice::from_raw_parts(bytes, len as usize);
    let vec = slice.to_vec();
    println!("{:?}", vec);
}
var str = "foobarbaz:あいうえお"; // ENG:JPN(Unicode, testing for UTF16)
fixed (char* p = str)
{
    NativeMethods.csharp_to_rust_string((ushort*)p, str.Length);
}

var str2 = Encoding.UTF8.GetBytes("あいうえお:foobarbaz");
fixed (byte* p = str2)
{
    NativeMethods.csharp_to_rust_utf8(p, str2.Length);
}

var bytes = new byte[] { 1, 10, 100, 255 };
fixed (byte* p = bytes)
{
    NativeMethods.csharp_to_rust_bytes(p, bytes.Length);
}

Again, the important thing is that memory allocated in Rust must release in Rust and memory allocated in C# must release in C#.

Build Tracing

csbindgen silently skips over any method with a non-generatable type. If you build with cargo build -vv, you will get thse message if not geneated.

  • csbindgen can't handle this parameter type so ignore generate, method_name: {} parameter_name: {}
  • csbindgen can't handle this return type so ignore generate, method_name: {}

Non-Generatable method: C variadic/variable arguments method

csbindgen doesn't handle C's variadic arguments, which causes undefined behaviors, because this feature is not stable both in C# and Rust. There is a __arglist keyword for C's variadic arguments in C#. __arglist has many problems except Windows environment. There is an issue about C's variadic arguments in Rust.

License

This library is licensed under the MIT License.

More Repositories

1

UniTask

Provides an efficient allocation free async/await integration for Unity.
C#
7,314
star
2

MagicOnion

Unified Realtime/API framework for .NET platform and Unity.
C#
3,611
star
3

MemoryPack

Zero encoding extreme performance binary serializer for C# and Unity.
C#
2,807
star
4

ZString

Zero Allocation StringBuilder for .NET and Unity.
C#
1,860
star
5

MasterMemory

Embedded Typed Readonly In-Memory Document Database for .NET and Unity.
C#
1,410
star
6

R3

The new future of dotnet/reactive and UniRx.
C#
1,332
star
7

MessagePipe

High performance in-memory/distributed messaging pipeline for .NET and Unity.
C#
1,258
star
8

ConsoleAppFramework

Micro-framework for console applications to building CLI tools/Daemon/Batch for .NET, C#.
C#
1,201
star
9

ZLogger

Zero Allocation Text/Structured Logger for .NET with StringInterpolation and Source Generator, built on top of a Microsoft.Extensions.Logging.
C#
1,081
star
10

Ulid

Fast .NET C# Implementation of ULID for .NET and Unity.
C#
831
star
11

SimdLinq

Drop-in replacement of LINQ aggregation operations extremely faster with SIMD.
C#
726
star
12

ObservableCollections

High performance observable collections and synchronized views, for WPF, Blazor, Unity.
C#
419
star
13

ProcessX

Simplify call an external process with the async streams in C# 8.0.
C#
410
star
14

UnitGenerator

C# Source Generator to create value-object, inspired by units of measure.
C#
309
star
15

YetAnotherHttpHandler

YetAnotherHttpHandler brings the power of HTTP/2 (and gRPC) to Unity and .NET Standard.
C#
290
star
16

AlterNats

An alternative high performance NATS client for .NET.
C#
279
star
17

RuntimeUnitTestToolkit

CLI/GUI Frontend of Unity Test Runner to test on any platform.
C#
268
star
18

NativeMemoryArray

Utilized native-memory backed array for .NET and Unity - over the 2GB limitation and support the modern API(IBufferWriter, ReadOnlySequence, scatter/gather I/O, etc...).
C#
246
star
19

PrivateProxy

Source Generator and .NET 8 UnsafeAccessor based high-performance strongly-typed private accessor for unit testing and runtime.
C#
234
star
20

StructureOfArraysGenerator

Structure of arrays source generator to make CPU Cache and SIMD friendly data structure for high-performance code in .NET and Unity.
C#
229
star
21

MagicPhysX

.NET PhysX 5 binding to all platforms(win, osx, linux) for 3D engine, deep learning, dedicated server of gaming.
Rust
221
star
22

LogicLooper

A library for building server application using loop-action programming model on .NET.
C#
211
star
23

DFrame

Distributed load testing framework for .NET and Unity.
C#
206
star
24

Utf8StreamReader

Utf8 based StreamReader for high performance text processing.
C#
194
star
25

LitJWT

Lightweight, Fast JWT(JSON Web Token) implementation for .NET.
C#
190
star
26

KcpTransport

KcpTransport is a Pure C# implementation of RUDP for high-performance real-time network communication
C#
183
star
27

Utf8StringInterpolation

Successor of ZString; UTF8 based zero allocation high-peformance String Interpolation and StringBuilder.
C#
140
star
28

CsprojModifier

CsprojModifier performs additional processing when Unity Editor generates the .csproj.
C#
135
star
29

ValueTaskSupplement

Append supplemental methods(WhenAny, WhenAll, Lazy) to ValueTask.
C#
126
star
30

Kokuban

Simplifies styling strings in the terminal for .NET application.
C#
121
star
31

Claudia

Unofficial Anthropic Claude API client for .NET.
C#
118
star
32

SlnMerge

SlnMerge merges the solution files when generating solution file by Unity Editor.
C#
111
star
33

GrpcWebSocketBridge

Yet Another gRPC over HTTP/1 using WebSocket implementation, primarily targets .NET platform.
C#
71
star
34

WebSerializer

Convert Object into QueryString/FormUrlEncodedContent for C# HttpClient REST Request.
C#
60
star
35

RandomFixtureKit

Fill random/edge-case value to target type for unit testing, supports both .NET Standard and Unity.
C#
43
star
36

Actions

30
star
37

DocfxTemplate

Patchworked DocFX v2 template for Cysharp
JavaScript
6
star
38

com.unity.ide.visualstudio-backport

Backport of com.unity.ide.visualstudio to before Unity 2019.4.21
C#
1
star