1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
|
# rlua -- High level bindings between Rust and Lua
[](https://travis-ci.org/chucklefish/rlua)
[](https://crates.io/crates/rlua)
[](https://docs.rs/rlua)
[Guided Tour](examples/guided_tour.rs)
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](https://github.com/jeremyong/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](https://github.com/rust-lang/rust/issues/48251) 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.
|
