michael/mlua
michael
/
mlua
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Update README for 0.9

This commit is contained in:
kyren 2017-08-02 17:04:44 -04:00
parent b03397137b
commit cac4141871
1 changed files with 47 additions and 40 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

87
README.md
View File

@ -11,10 +11,11 @@ to expose as easy to use, practical, and flexible of an API between Rust and Lua
as possible, while also being completely safe.
There are other high level Lua bindings systems for rust, and this crate is an
exploration of a different part of the design space. The main high level
interface to Lua right now is [hlua](https://github.com/tomaka/hlua/) which you
should definitely check out and use if it suits your needs. This crate has the
following differences with hlua:
exploration of a different part of the design space. The other high level
interface to Lua that I am aware of right now
is [hlua](https://github.com/tomaka/hlua/) which you should definitely check out
and use if it suits your needs. This crate has the following differences with
hlua:
* Handles to Lua values use the Lua registry, not the stack
* Handles to Lua values are all internally mutable
@ -45,19 +46,15 @@ There are currently a few notable missing pieces of this API:
* More fleshed out Lua API, there is some missing nice to have functionality
not exposed like storing values in the registry, and manipulating `LuaTable`
metatables.
* Better API documentation and more examples.
* Generally paying attention to performance and having benchmarks.
* 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:
* Once ATCs land, there should be a way to wrap callbacks based on argument
and return signature, rather than calling Lua::pack / Lua::unpack inside the
callback. Until then, it is impossible to name the type of the function
that would do the wrapping (See
[this reddit discussion](http://www.reddit.com/r/rust/comments/5yujt6/))
* Once variadic generics land in some form (tuple based variadic generics?),
the plan is to completely eliminate the hlist macros.
* 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:
@ -67,24 +64,23 @@ It is also worth it to list some non-goals for the project:
## API stability or lack thereof
This library is very much Work In Progress, so there is a lot of API churn. I
think the library MIGHT be stable and usable enough to realistically use in a
real project, but I cannot yet provide a stable API. I currently follow
believe the library should be stable and usable enough to realistically use in a
real project, but the API has probably not settled down yet. I currently follow
"pre-1.0 semver" (if such a thing exists), but there have been a large number of
API version bumps, and there will probably continue to be. If you have a
dependency on rlua, you might want to consider adding a 0.x version bound.
API version bumps, and there will may continue to be. If you have a dependency
on rlua, you might want to consider adding a 0.x version bound.
## Safety and panics
My *goal* 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". If you find the ability to cause UB with this API
*at all*, please file a bug report.
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". If you find the ability to cause
UB with this API *at all*, please file a bug report.
There are, however, a few ways to cause *panics* and even *aborts* with this
API. I'm going to describe a lot of the finer points of panic handling in the
library here, but again this should all be taken currently to be "Work In
Progress".
API. Usually these panics or aborts are alternatives to what would otherwise be
unsafety.
Panic / abort considerations when using this API:
@ -92,28 +88,39 @@ Panic / abort considerations when using this API:
Lua stack is cleared and the `Lua` instance should continue to be usable.
* Panic unwinds in Rust callbacks should currently be handled correctly, the
unwind is caught and carried across the Lua API boundary, and Lua code
cannot catch rust panics.
cannot catch rust panics. This is done by overriding the normal Lua 'pcall'
and 'xpcall' with custom versions that cannot catch rust panics being piped
through the normal Lua error system.
* There are a few panics marked "internal error" that should be impossible to
trigger. If you encounter one of these this is a bug.
* When the internal version of Lua is built using the `gcc` crate (the
default), `LUA_USE_APICHECK` is enabled. Any abort caused by this internal
Lua API checking should be considered a bug.
* The library internally calls lua_checkstack to ensure that there is
sufficient stack space, and if the stack cannot be sufficiently grown this
is a panic. There should not be a way to cause this using the API, if you
encounter this, it is a bug.
* Currently the Lua allocator is the default C alloctor, and allocation
failures may cause an *abort*. This API only attempts to handle errors in
Lua functions that can cause an error either directly or by running
arbitrary Lua code, not functions that can cause memory errors. This may
either cause an abort inside Lua itself, or from rust if the error happens
in a protected call. If there is a memory error received from a protected
call, we cannot assume anything about the state of rust code because there
might have been a longjmp at any arbitrary point, so we are forced to abort.
* Similarly to the above, if there is an internal error in a __gc metamethod,
this may cause an abort. This can be triggered in this API by panicking
during drop of a custom userdata type, but this already can cause aborts in
normal Rust anyway.
* This API attempts only to handle errors in Lua C API functions that can
cause an error either directly or by running arbitrary Lua code directly,
not functions that can cause memory errors (marked as 'm' in the Lua C API
docs). This means that we must take care to ensure that gc or memory errors
cannot occur, because this would unsafely longjmp potentially across rust
frames. The allocator provided to lua is libc::malloc with an extra guard
to ensure that OOM errors are immediate aborts, because otherwise this would
be unsafe. Similarly, 'setmetatable' is wrapped so that any `__gc`
metamethod specified in lua scripts will *abort* if the metamethod causes an
error rather than longjmp like a normal error would. Lua objects can also
be resurrected with user provided `__gc` metamethods
(See [here](https://www.lua.org/manual/5.3/manual.html#2.5.1) for details),
and this includes userdata, so it is possible to trigger a panic from lua by
resurrecting a userdata and re-using it after it has been garbage collected.
It is an eventual goal of the library to ensure that lua scripts cannot
cause panics or aborts, but currently this is not true and this is a known
limitation. Lua scripts should NOT be able to cause unsafety, though, this
is always considered a bug.
* There are currently no recursion limits on callbacks. This could cause one
of two problems, either the API will run out of stack space and cause a
panic in Rust, or more likely it will cause an internal `LUA_USE_APICHECK`
abort, from exceeding LUAI_MAXCCALLS.
* There are no checks on argument sizes, and I think you can cause an abort by
providing a large enough `LuaVariadic`.
* There are currently no checks on argument sizes, and I think you may be able
to cause an abort by providing a large enough `LuaVariadic`.