minimizing overhead for accessing rust structs from lua

[brentp]

are there any best-practices for minimizing overhead for calling back into a rust library from lua(u)? I have a setup that will be making 100's of millions of small calls.
I'm currently using UserData fields.add_field_method_get to expose the rust struct. Is there anything else to try? It's probably fast enough as-is, but I'm interested in eeking out any performance.
Thanks for the very nice library!

[khvzak]

Try to avoid setting fields on UserData object. The fastest way is UserData with methods only.
When you define field getters or setters, mlua sets __index to a function that on every call looks into right field/method to call.
When userdata has only methods, __index is set to method table which is optimized in Luau in particular.

[brentp]

oh, indeed that's much faster on my quick test. It gave a 4X speed improvement.

Now a naive question, with that change, the syntax for my user expressions go from:
return read.bq > 1
to :
read:bq() > 1
is there anyway to keep the former property syntax with the performance of a method?

I am guessing not from looking at docs here but wanted to be sure.

[brentp]

Actually, I notice if I have a single method vs a single field, the performance difference is negligible. I assume the difference is more when there are more fields vs more methods?

Comparing a single field to ~15 field, I see a dramatic performance improvement when only a single field is specified (using same expression on only that single field).

[khvzak]

I assume the difference is more when there are more fields vs more methods?

It should not really matter, the complexity is O(1), fields and methods are stored in a hashmap.
However Luau at compile time can predict hashmap slot when userdata has only methods. Whereas with fields(+ methods) lookup is always dynamic.

is there anyway to keep the former property syntax with the performance of a method?

You can try to set __index metamethod for your case:

fn add_fields<'lua, F: LuaUserDataFields<'lua, Self>>(fields: &mut F) {
    fields.add_meta_field_with("__index", |lua| {
        lua.create_function(
            |lua, (this, key): (mlua::UserDataRef<Self>, mlua::String)| match key.as_bytes() {
                b"field" => Ok(this.field),
                _ => Err(mlua::Error::RuntimeError("no such field".to_string())),
            },
        )
    })
}

[brentp]

I assume the difference is more when there are more fields vs more methods?

It should not really matter, the complexity is O(1), fields and methods are stored in a hashmap. However Luau at compile time can predict hashmap slot when userdata has only methods. Whereas with fields(+ methods) lookup is always dynamic.

Ok. I also am surprised this makes so much difference, but indeed the dynamic lookup is much slower when I have 15 fields vs 1 field in luau.

is there anyway to keep the former property syntax with the performance of a method?

You can try to set __index metamethod for your case:

Thanks, I will try this. It appears that UserDataRef is not yet in a tagged version.

[brentp]

I tried switching to all methods, but don't see a performance improvement. I am using this code:
https://github.com/brentp/pbr/blob/35853668a47ddda8b38e5c5fdd709c8a76bd9a73/src/main.rs#L53-L120

and then this code gets executed millions of times: https://github.com/brentp/pbr/blob/35853668a47ddda8b38e5c5fdd709c8a76bd9a73/src/main.rs#L125-L135

If I understand correctly, create_nonstatic_userdata will be linear in number of fields + methods so that is likely the performance change that I saw when reducing number of fields or methods: https://github.com/khvzak/mlua/blob/d5483988d2c81f9850f0854cc58783b64d727855/src/scope.rs#L391-L398

Now, I guess that I am doing something uneccessary here: https://github.com/brentp/pbr/blob/35853668a47ddda8b38e5c5fdd709c8a76bd9a73/src/main.rs#L125-L135
?
The underlying types (from an external lib) do not implement Send/Sync which is why I used create_nonstatic_userdata and why it appears that metamethod + create_function won't work as create_function requires a static lifetime as well.

Do you see anything obvious that I can try for performance given those constraints?

thanks again!

[khvzak]

Unfortunately, everything is very different with non-static userdata. The problem with it -- each instance has own metatable that re-created every time when you create a userdata object. It's very expensive! Whereas static userdata shares a single metatable attached per type.

To optimize this, you can use new mlua feature available from v0.9 (beta) to create non-static userdata objects &T where T: 'static.

Code like

struct Pile<'a>(&'a PileupPosition);
impl<'a> UserData for Pile<'a> {
    fn add_fields<'lua, F: mlua::UserDataFields<'lua, Self>>(fields: &mut F) {
        ...
    }
}

can be rewritten to:

lua.register_userdata_type::<PileupPosition>(|reg| {
    reg.add_field_method_get("depth", |_, this| Ok(this.0.depth));
});

// Then to create `&PileupPosition` userdata:
self.lua.scope(|scope| {
    let ud = scope.create_userdata_ref(&my_object)?;
})

As you can see, no need to create a new wrapper type.

For more complex objects, like

struct MyRecord<'a>(&'a Record, &'a Alignment<'a>);

probably would be better to decompose it to two different objects using the api above, and in Lua script you can always expose a a table with __index, where every method belong to Record or Alignment.

local my_record = setmetatable({rec, alignment}, {__index = function(self, key) ... end})

[brentp]

excellent! thanks very much for looking into my code! I will give this a try.
I'm not clear why a 2-tuple (MyRecord) is different from a 1-tuple (Pile) but I'll play around and maybe it will become clear.

[khvzak]

Seems this trick would not work for Alignment<'a>

[brentp]

I tried userdata_ref with only the Record struct (no Alignment) here
but it still seems a static lifetime is required as I see:

error[E0521]: borrowed data escapes outside of method
  --> src/main.rs:82:22
   |
78 |     fn filter_read(&self, read: &Record, _alignment: Option<&Alignment>) -> bool {
   |                           ----  - let's call the lifetime of this reference `'1`
   |                           |
   |                           `read` is a reference that is only valid in the method body
...
82 |             let ud = scope.create_userdata_ref(&rec)?;
   |                      ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
   |                      |
   |                      `read` escapes the method body here
   |                      argument requires that `'1` must outlive `'static`

note: erroneous constant used
  --> src/main.rs:92:27
   |
92 |                 eprintln!("Error evaluating expression: {}", e);
   |                           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

For more information about this error, try `rustc --explain E0521`.
error: could not compile `pbr` (bin "pbr" test) due to previous error

Unless there's an obvious way to fix this I will try again to use your other suggestion:

fn add_fields<'lua, F: LuaUserDataFields<'lua, Self>>(fields: &mut F) {
    fields.add_meta_field_with("__index", |lua| {
        lua.create_function(
            |lua, (this, key): (mlua::UserDataRef<Self>, mlua::String)| match key.as_bytes() {
                b"field" => Ok(this.field),
                _ => Err(mlua::Error::RuntimeError("no such field".to_string())),
            },
        )
    })
}

since that will limit the number of fields that need to be copied for non_static_userdata.

[brentp]

But it remains, that I can't get it to work with a simple wrapped type like:

struct MyRecord<'a>(&'a Record, usize);

[khvzak]

You can add this value to user value after creation:

ud.set_named_user_value("constant", 123);

and then have a method to retrieve it back:

fields.add_field_function_get("constant", |_, this| this.get_named_user_value("constant"));

[brentp]

Got it. That works!

Now, how can I access that value from other methods, e.g. I now have:

     reg.add_function("qpos", |_, this: mlua::AnyUserData| {
                let r: Result<usize, LuaError> = this.get_named_user_value("qpos");
                r
            });

and want to enable:

            reg.add_field_method_get("bq", |_, this| {
                let qpos = ????;
                let qual = this.qual()[qpos];
                Ok(qual)
            });

I can't attach it to the rust struct and I don't see how to get it from the args to add_field_method_get. Do you see a way to do this?
Once I can do this, I think I'll be able to stop needing you to write my code line by line. :-(

[khvzak]

You need to switch to reg.add_field_function_get:

            reg.add_field_function_get("bq", |_, this| {
                let qpos = this.get_named_user_value("qpos")?;
                let this = this.borrow::<T>()?;
                let qual = this.qual()[qpos];
                Ok(qual)
            });

AnyUserData is universal accessor to underlying Rust type.
All method functions family under the hood borrows AnyUserData to pass &T.

[brentp]

Thank you very much!

[brentp]

If I have something like this (with __index):
will it degrade the performance in luau?

fn register_variant(lua: &Lua) -> mlua::Result<()> {
    lua.register_userdata_type::<Variant>(|reg| {
        reg.add_meta_function(
            MetaMethod::Index,
            |_lua, (_, name): (AnyUserData, String)| {
                let msg = format!("field '{}' variant.{} not found", name, name);
                Err::<LuaValue<'_>, mlua::Error>(mlua::Error::RuntimeError(msg))
            },
        );
      ... // other reg.add_field_method_get definitions
}

I just want to give an error if the user access an unset field (rather than returning nil).

[khvzak]

will it degrade the performance in luau

Unfortunately yes, see https://luau-lang.org/performance#fast-method-calls

For performance reasons it’s strongly recommended to avoid __index functions as well as deep __index chains; an ideal object in Luau is a table with a metatable that points to itself through __index.

However it might be not critical at all for your case (I would recommend to run benchmarks to check real difference)

[brentp]

ok. Thanks @khvzak . I benchmarked it and the difference is minimal for a typical use-case so I'll leave it for now.

Another question. I have this:

        reg.add_field_method_get("id", |lua: &Lua, this: &Variant| {
            let id = this.0.id();
            Ok(Value::String(unsafe {
                lua.create_string(String::from_utf8_unchecked(id.to_vec()))?
            }))
        });
        reg.add_field_method_set(
            "id",
            |_lua: &Lua, this: &mut Variant, val: String| match this.0.set_id(val.as_bytes()) {
                Err(e) => Err(mlua::Error::ExternalError(Arc::new(e))),
                Ok(_) => Ok(()),
            },
        );

and I can read variant.id in lua code, but when I call the setter: variant.id = "some value" then it gives

CallbackError { traceback: "stack traceback:\n\t[C]: in ?\n\t[string \"__mlua_newindex\"]:8: in ?\n\t[string \"variant.id = 'xxx'; return variant.id == 'rs2124717267'\"]:1: in ?", cause: BadArgument { to: Some("Variant.id"), pos: 1, name: Some("self"), cause: UserDataBorrowMutError } }

Any pointers here? I am using:

      let ud = scope.create_any_userdata_ref(variant)?;
      globals.set("variant", ud)?;

[brentp]

here is a full example: https://github.com/brentp/help-repositories/blob/1a6a22ff264e2042794f539cd9527b71b12c9188/src/main.rs#L48-L57

it seems to find the getters before __index, but not the setters before __newindex.

[khvzak]

You created a readonly reference to userdata object:

let ud = scope.create_any_userdata_ref(&record)?;

It cannot be modified (the code UserDataBorrowMutError implicitly tells about this). To fix it, you need to create readwrite (mutable) reference, using:

let ud = scope.create_any_userdata_ref_mut(&mut record)?;

Then it should work

[brentp]

yes. thank you!

[brentp]

I know things have changed in v0.10+, is lua.register_userdata_type::<T>(...) still a way to get the best performance?

[khvzak]

In most cases yes, if you have any specific code example, I can answer more precisely.
Also if you need max performance, do not use send feature.