michael/mlua
michael
/
mlua
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
373 Commits 1 Branch 0 Tags 2.7 MiB
Rust 100%
Go to file
kyren 601e9f4cac A lot of performance changes. 
Okay, so this is kind of a mega-commit of a lot of performance related changes
to rlua, some of which are pretty complicated.

There are some small improvements here and there, but most of the benefits of
this change are from a few big changes.  The simplest big change is that there
is now `protect_lua` as well as `protect_lua_call`, which allows skipping a
lightuserdata parameter and some stack manipulation in some cases.  Second
simplest is the change to use Vec instead of VecDeque for MultiValue, and to
have MultiValue be used as a sort of "backwards-only" Vec so that ToLuaMulti /
FromLuaMulti still work correctly.

The most complex change, though, is a change to the way LuaRef works, so that
LuaRef can optionally point into the Lua stack instead of only registry values.
At state creation a set number of stack slots is reserved for the first N LuaRef
types (currently 16), and space for these are also allocated separately
allocated at callback time.  There is a huge breaking change here, which is that
now any LuaRef types MUST only be used with the Lua on which they were created,
and CANNOT be used with any other Lua callback instance.  This mostly will
affect people using LuaRef types from inside a scope callback, but hopefully in
those cases `Function::bind` will be a suitable replacement.  On the plus side,
the rules for LuaRef types are easier to state now.

There is probably more easy-ish perf on the table here, but here's the
preliminary results, based on my very limited benchmarks:

create table            time:   [314.13 ns 315.71 ns 317.44 ns]
                        change: [-36.154% -35.670% -35.205%] (p = 0.00 < 0.05)
create array 10         time:   [2.9731 us 2.9816 us 2.9901 us]
                        change: [-16.996% -16.600% -16.196%] (p = 0.00 < 0.05)
                        Performance has improved.
create string table 10  time:   [5.6904 us 5.7164 us 5.7411 us]
                        change: [-53.536% -53.309% -53.079%] (p = 0.00 < 0.05)
                        Performance has improved.
call add function 3 10  time:   [5.1134 us 5.1222 us 5.1320 us]
                        change: [-4.1095% -3.6910% -3.1781%] (p = 0.00 < 0.05)
                        Performance has improved.
call callback add 2 10  time:   [5.4408 us 5.4480 us 5.4560 us]
                        change: [-6.4203% -5.7780% -5.0013%] (p = 0.00 < 0.05)
                        Performance has improved.
call callback append 10 time:   [9.8243 us 9.8410 us 9.8586 us]
                        change: [-26.937% -26.702% -26.469%] (p = 0.00 < 0.05)
                        Performance has improved.
create registry 10      time:   [3.7005 us 3.7089 us 3.7174 us]
                        change: [-8.4965% -8.1042% -7.6926%] (p = 0.00 < 0.05)
                        Performance has improved.

I think that a lot of these benchmarks are too "easy", and most API usage is
going to be more like the 'create string table 10' benchmark, where there are a
lot of handles and tables and strings, so I think that 25%-50% improvement is a
good guess for most use cases.
 		2018-03-11 23:20:10 -04:00
benches Additional benchmarks 2018-03-11 17:50:17 -04:00
examples Change changelog, readme, examples, Cargo.toml for 0.12 release 2018-02-10 19:04:18 -05:00
lua Revert "Temporary fix for #71. Remove when rust #48251 is fixed in stable." 2018-03-06 07:03:58 -05:00
src A lot of performance changes. 2018-03-11 23:20:10 -04:00
tests Letting scope handles escape the scope was unsafe 2018-02-19 17:40:48 -05:00
.gitignore Initial import 2017-05-21 19:50:59 -04:00
.travis.yml fix duplicated matrix entry for .travis.yml 2018-02-10 00:35:12 -05:00
CHANGELOG.md Update changelog / cargo.toml in prep for 0.13 2018-02-28 14:44:16 -05:00
Cargo.toml Use criterion for benchmarking, add some simple benchmarks 2018-03-10 10:31:57 -05:00
LICENSE More sensible license, show that copyright is to Chucklefish LTD 2017-05-21 22:58:47 -04:00
README.md Change strategies for handling the Lua stack during panics 2018-03-08 10:59:50 -05:00
build.rs Use criterion for benchmarking, add some simple benchmarks 2018-03-10 10:31:57 -05:00

README.md

rlua -- High level bindings between Rust and Lua

Build Status Latest Version API Documentation

Guided Tour

This library is a high level interface between Rust and Lua. Its major goal is to expose as easy to use, practical, and flexible of an API between Rust and Lua as possible, while also being completely safe.

rlua is designed around "registry handles" to values inside the Lua state. This means that when you get a type like rlua::Table or rlua::Function in Rust, what you actually hold is an integer key into the Lua registry. This is different from the bare Lua C API, where you create tables / functions on the Lua stack and must be aware of their stack location. This is also similar to how other Lua bindings systems like Selene for C++ work, but it means that using rlua may be slightly slower than what you could conceivably write using the C API. The reasons for this design are safety and flexibility, and to prevent the user of rlua from having to be aware of the Lua stack at all.

There are currently a few missing pieces of this API:

  • Security limits on Lua code such as total instruction limits / memory limits and control over which potentially dangerous libraries (e.g. io) are available to scripts.
  • Lua profiling support
  • "Context" or "Sandboxing" support. There should be the ability to set the _ENV upvalue of a loaded chunk to a table other than _G, so that you can have different environments for different loaded chunks.
  • Benchmarks, and quantifying performance differences with what you would might write in C.

Additionally, there are ways I would like to change this API, once support lands in rustc. For example:

  • Currently, variadics are handled entirely with tuples and traits implemented by macro for tuples up to size 12, it would be great if this was replaced with real variadic generics when this is available in Rust.

It is also worth it to list some non-goals for the project:

  • Be a perfect zero cost wrapper over the Lua C API
  • Allow the user to do absolutely everything that the Lua C API might allow

API stability

This library is very much Work In Progress, so there is a some API churn. Currently, it follows a pre-1.0 semver, so all API changes should be accompanied by 0.x version bumps.

Safety and panics

The goal of this library is complete safety, it should not be possible to cause undefined behavior whatsoever with the API, even in edge cases. There is, however, QUITE a lot of unsafe code in this crate, and I would call the current safety level of the crate "Work In Progress". Still, I am not currently aware of any way to cause UB, and UB is considered the most serious kind of bug, so if you find the ability to cause UB with this API at all, please file a bug report.

Another goal of this library is complete protection from panics and aborts. Currently, it should not be possible for a script to trigger a panic or abort (with some important caveats described below). Similarly to the safety goal, there ARE several internal panics and even aborts in rlua source, but they should not be possible to trigger, and if you trigger them this should be considered a bug.

There are some caveats to the panic / abort guarantee, however:

  • rlua reserves the right to panic on API usage errors. Currently, the only time this will happen is when passed a registry handle type from a different main Lua state.
  • Currently, there are no memory or execution limits on scripts, so untrusted scripts can always at minimum infinite loop or allocate arbitrary amounts of memory.
  • The internal Lua allocator is set to use realloc from libc, but it is wrapped in such a way that OOM errors are guaranteed to abort. This is not currently such a huge deal outside of untrusted scripts, as this matches the behavior of Rust itself. Doing this allows the internals of rlua to, in certain cases, call 'm' Lua C API functions with the garbage collector disabled and know that these cannot error. Eventually, rlua will support memory limits on scripts, and those memory limits will cause regular memory errors rather than OOM aborts.
  • rustc version 1.24.0 on Windows contains a bug which affects rlua error handling, turning any Lua script error into an abort. If you are using Rust 1.24.0 on windows, please upgrade to 1.24.1.

Yet another goal of the library is to, in all cases, safely handle panics generated by Rust callbacks. Panic unwinds in Rust callbacks should currently be handled correctly -- the unwind is caught and carried across the Lua API boundary as a regular Lua error in a way that prevents Lua from catching it. This is done by overriding the normal Lua 'pcall' and 'xpcall' with custom versions that cannot catch errors that are actually from Rust panics, and by handling panic errors on the receiving Rust side by resuming the panic.

rlua should also be panic safe in another way as well, which is that any Lua instances or handles should remain usable after a user triggered panic, and such panics should not break internal invariants or leak Lua stack space. This is mostly important to safely use rlua types in Drop impls, as you should not be using panics for general error handling.

In summary, here is a list of rlua behaviors that should be considered a bug. If you encounter them, a bug report would be very welcome:

  • If you can cause UB at all with rlua without typing the word "unsafe", this is absolutely 100% a bug.
  • If your code panics / aborts with a message that contains the string "rlua internal error", this is a bug.
  • The above is true even for the internal panic about running out of stack space! There are a few ways to generate normal script errors by running out of stack, but if you encounter a panic based on running out of stack, this is a bug.
  • If you load the "debug" library (which requires typing "unsafe"), every safety / panic / abort guarantee goes out the window. The debug library can be used to do extremely scary things. If you use the debug library and encounter a bug, it may still very well be a bug, but try to find a reproduction that does not involve the debug library first.
  • When the internal version of Lua is built using the gcc crate, and cfg!(debug_assertions) is true, Lua is built with the LUA_USE_APICHECK define set. Any abort caused by this internal Lua API checking is absolutely a bug, particularly because without LUA_USE_APICHECK it would generally be unsafe.
  • Lua C API errors are handled by lonjmp. ALL instances where the Lua C API would longjmp should be protected from Rust, except in internal callbacks where this is intentional. If you detect that rlua is triggering a longjmp over your Rust stack frames, this is a bug!
  • If you can somehow handle a panic in a Rust callback from Lua, this is a bug.
  • If you detect that, after catching a panic, a Lua or handle method is triggering other bugs or there is a Lua stack space leak, this is a bug. rlua instances are supposed to remain fully usable in the face of user triggered panics. This guarantee does NOT extend to panics marked with "rlua internal error" simply because that is already indicative of a separate bug, but it may be true in many cases anyway.