Implementing C helper functions for Rust UserData #545

bobbens · 2025-03-16T10:26:46Z

bobbens
Mar 16, 2025

I'm porting a large C codebase, and need to provide a C API for lua_tofoo, luaL_checkfoo, luaL_pushfoo, and lua_isfoo for a userdata type foo that is in Rust. I've just implemented by working C code using the ffi interface of mlua, but it's not matching the UserData. My main question is what is going to be the UserData's name registered in the metatable, and if the following code is the best way to handle this?

static VEC2_METATABLE: &[u8; 5] = b"vec2\0";

#[unsafe(no_mangle)]
pub unsafe extern "C" fn lua_tovector( L: *mut mlua::lua_State, ind: c_int ) -> *mut Vec2 {
    unsafe {
        ffi::lua_touserdata( L, ind ) as *mut Vec2
    }
}

#[unsafe(no_mangle)]
pub unsafe extern "C" fn luaL_checkvector( L: *mut mlua::lua_State, ind: c_int ) -> *mut Vec2 {
    unsafe {
        match lua_isvector( L, ind ) {
            0 => {
                ffi::luaL_typerror( L, ind, VEC2_METATABLE.as_ptr() as *const c_char );
                std::ptr::null_mut()
            },
            _ => lua_tovector( L, ind ),
        }
    }
}

#[unsafe(no_mangle)]
pub unsafe extern "C" fn lua_pushvector( L: *mut mlua::lua_State, vec: Vec2 ) -> *mut Vec2 {
    let size = std::mem::size_of::<Vec2>();
    unsafe {
        let v: *mut Vec2 = ffi::lua_newuserdata( L, size ) as *mut Vec2;
        std::ptr::copy_nonoverlapping( &vec as *const Vec2, v, size );
        ffi::luaL_getmetatable( L, VEC2_METATABLE.as_ptr() as *const c_char );
        ffi::lua_setmetatable( L, -2 );
        v
    }
}

#[unsafe(no_mangle)]
pub unsafe extern "C" fn lua_isvector( L: *mut mlua::lua_State, ind: c_int ) -> c_int {
    unsafe {
        if ffi::lua_getmetatable( L, ind ) == 0 {
            return 0;
        }
        ffi::lua_getfield( L, ffi::LUA_REGISTRYINDEX, VEC2_METATABLE.as_ptr() as *const c_char );
        let ret = match ffi::lua_rawequal( L, -1, -2 ) { /* Check metatable. */
            0 => 0,
            _ => 1,
        };
        ffi::lua_pop( L, 2 ); /* remove both metatables */
        ret
    }
}

I'm registering the module with:

globals.set("vec2", lua.create_proxy::<Vec2>()?)?;

It seems like the mlua userdata is dealing with this differently from the C API so it fails to detect the userdata as the correct type.

Answered by khvzak

Mar 17, 2025

Check my example, it works:

struct Vec2(f32, f32);

let lua = Lua::new();

let push_vector = lua.create_function(|lua, (x, y): (f32, f32)| {
    let vec = Vec2(x, y);
    lua.create_any_userdata(vec)
})?;
lua.set_named_registry_value("push_vector", push_vector)?;

let get_vector = lua.create_function(|_, mut ud: UserDataRefMut<Vec2>| {
    let vec: *mut Vec2 = &mut *ud;
    Ok(Value::LightUserData(LightUserData(vec as *mut c_void)))
})?;
lua.set_named_registry_value("get_vector", get_vector)?;

unsafe extern "C" fn lua_isvector(L: *mut lua_State, idx: c_int) -> c_int {
    !lua_tovector(L, idx).is_null() as c_int
}

unsafe extern "C" fn lua_pushvector(L: *mut lua_State, x: f32, y: f32) {
…

View full answer

khvzak · 2025-03-16T20:47:17Z

khvzak
Mar 16, 2025
Maintainer

It seems like the mlua userdata is dealing with this differently from the C API so it fails to detect the userdata as the correct type.

mlua by-design support only userdata that were made using mlua (high level) api, to ensure data types safety.
Apart from that, UserData instances are wrapped in a special way to maintain Rust safety guarantees (e.g. only one mutable borrow at a time).

Probably the easiest way would be making lua_isvector (and others) as a thin wrapper that calls high level Rust functions.
Sort of:

let is_vector = lua.create_function(|_, ud| Ok(ud.is::<Vec2>()))?;
lua.set_named_registry_value("is_vector", is_vector)?;

#[unsafe(no_mangle)]
pub unsafe extern "C" fn lua_isvector( L: *mut mlua::lua_State, ind: c_int ) -> c_int {
    lua_getfield(L, LUA_REGISTRYINDEX, c"is_vector");
    lua_pushvalue(L, ind);
    lua_call(L, 1, 1)
}

3 replies

bobbens Mar 17, 2025
Author

Thanks for the prompt response!

It seems like the mlua userdata is dealing with this differently from the C API so it fails to detect the userdata as the correct type.

mlua by-design support only userdata that were made using mlua (high level) api, to ensure data types safety. Apart from that, UserData instances are wrapped in a special way to maintain Rust safety guarantees (e.g. only one mutable borrow at a time).

Probably the easiest way would be making lua_isvector (and others) as a thin wrapper that calls high level Rust functions. Sort of:
let is_vector = lua.create_function(|_, ud| Ok(ud.is::<Vec2>()))?;
lua.set_named_registry_value("is_vector", is_vector)?;

#[unsafe(no_mangle)]
pub unsafe extern "C" fn lua_isvector( L: *mut mlua::lua_State, ind: c_int ) -> c_int {
    lua_getfield(L, LUA_REGISTRYINDEX, c"is_vector");
    lua_pushvalue(L, ind);
    lua_call(L, 1, 1)
}

Thanks for the hints. I got to:

    let is_vector = lua.create_function(|_, val: mlua::Value| -> mlua::Result<bool> {
        match val {
            mlua::Value::UserData(ud) => Ok(ud.is::<Vec2>()),
            _ => Ok(false)
        }
    })?;
    lua.set_named_registry_value("is_vector", is_vector)?;

    let push_vector = lua.create_function(|_, (x,y): (f64,f64)| -> mlua::Result<Vec2> {
        Ok(Vec2::new( x, y))
    })?;
    lua.set_named_registry_value("push_vector", push_vector)?;

#[unsafe(no_mangle)]
pub unsafe extern "C" fn lua_tovector( L: *mut mlua::lua_State, ind: c_int ) -> *mut Vec2 {
    unsafe {
        ffi::lua_touserdata( L, ind ) as *mut Vec2
    }
}

#[unsafe(no_mangle)]
pub unsafe extern "C" fn luaL_checkvector( L: *mut mlua::lua_State, ind: c_int ) -> *mut Vec2 {
    unsafe {
        match lua_isvector( L, ind ) {
            0 => {
                ffi::luaL_typerror( L, ind, c"vec2".as_ptr() );
                std::ptr::null_mut()
            },
            _ => lua_tovector( L, ind ),
        }
    }
}

#[unsafe(no_mangle)]
pub unsafe extern "C" fn lua_pushvector( L: *mut mlua::lua_State, vec: naevc::vec2 ) -> *mut Vec2 {
    unsafe {
        ffi::lua_getfield(L, ffi::LUA_REGISTRYINDEX, c"push_vector".as_ptr() );
        ffi::lua_pushnumber( L, vec.x );
        ffi::lua_pushnumber( L, vec.y );
        ffi::lua_call(L, 2, 1);
        std::ptr::null_mut() as *mut Vec2
    }
}

#[unsafe(no_mangle)]
pub unsafe extern "C" fn lua_isvector( L: *mut mlua::lua_State, ind: c_int ) -> c_int {
    unsafe {
        ffi::lua_getfield(L, ffi::LUA_REGISTRYINDEX, c"is_vector".as_ptr() );
        ffi::lua_pushvalue(L, ind);
        ffi::lua_call(L, 1, 1);
        let ret = ffi::lua_toboolean(L,-1);
        ffi::lua_pop(L,1);
        ret
    }
}

The lua_tovector isn't working. I assume I would have to cast to mlua::UserData or something like that? (have to refactor other things so I haven't been able to fully test yet)
There is also no more general memory copying solution instead of creating a new struct and initializing via rust?

khvzak Mar 17, 2025
Maintainer

Check my example, it works:

struct Vec2(f32, f32);

let lua = Lua::new();

let push_vector = lua.create_function(|lua, (x, y): (f32, f32)| {
    let vec = Vec2(x, y);
    lua.create_any_userdata(vec)
})?;
lua.set_named_registry_value("push_vector", push_vector)?;

let get_vector = lua.create_function(|_, mut ud: UserDataRefMut<Vec2>| {
    let vec: *mut Vec2 = &mut *ud;
    Ok(Value::LightUserData(LightUserData(vec as *mut c_void)))
})?;
lua.set_named_registry_value("get_vector", get_vector)?;

unsafe extern "C" fn lua_isvector(L: *mut lua_State, idx: c_int) -> c_int {
    !lua_tovector(L, idx).is_null() as c_int
}

unsafe extern "C" fn lua_pushvector(L: *mut lua_State, x: f32, y: f32) {
    ffi::lua_getfield(L, ffi::LUA_REGISTRYINDEX, c"push_vector".as_ptr());
    ffi::lua_pushnumber(L, x as f64);
    ffi::lua_pushnumber(L, y as f64);
    ffi::lua_call(L, 2, 1);
}

unsafe extern "C" fn lua_tovector(L: *mut lua_State, idx: c_int) -> *mut Vec2 {
    let idx = lua_absindex(L, idx);
    ffi::lua_getfield(L, ffi::LUA_REGISTRYINDEX, c"get_vector".as_ptr());
    ffi::lua_pushvalue(L, idx);
    let vec = match ffi::lua_pcall(L, 1, 1, 0) {
        ffi::LUA_OK => ffi::lua_touserdata(L, -1) as *mut Vec2,
        _ => std::ptr::null_mut(),
    };
    ffi::lua_pop(L, 1);
    vec
}

unsafe {
    lua.exec_raw::<()>((), |state| {
        lua_pushvector(state, 1.0, 2.0);
        println!("is vector: {}", lua_isvector(state, -1));
        let vec2 = lua_tovector(state, -1);
        if !vec2.is_null() {
            println!("vector: ({}, {})", (*vec2).0, (*vec2).1);
        }
    })?;
}

Answer selected by bobbens

bobbens Apr 24, 2025
Author

Works like a charm, thanks again!

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

Implementing C helper functions for Rust UserData #545

Uh oh!

{{title}}

Uh oh!

Replies: 1 comment 3 replies

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{editor}}'s edit

{{editor}}'s edit

Uh oh!

Uh oh!

{{title}}

Uh oh!

Select a reply

Uh oh!

Uh oh!

Implementing C helper functions for Rust UserData #545

Uh oh!

bobbens Mar 16, 2025

Replies: 1 comment · 3 replies

Uh oh!

khvzak Mar 16, 2025 Maintainer

Uh oh!

bobbens Mar 17, 2025 Author

Uh oh!

Uh oh!

khvzak Mar 17, 2025 Maintainer

Uh oh!

bobbens Apr 24, 2025 Author

bobbens
Mar 16, 2025

Replies: 1 comment 3 replies

khvzak
Mar 16, 2025
Maintainer

bobbens Mar 17, 2025
Author

khvzak Mar 17, 2025
Maintainer

bobbens Apr 24, 2025
Author