delta/mlua
1
0
Fork 0
Code Issues Pull requests Packages Projects Releases Wiki Activity

update README

Browse source
This commit is contained in:
kyren 2017-05-25 00:56:23 -04:00
parent acd0611692
commit 9fef45272f
1 changed files with 15 additions and 11 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

26
README.md
View file

@ -2,9 +2,9 @@
[![Build Status](https://travis-ci.org/chucklefish/rlua.svg?branch=master)](https://travis-ci.org/chucklefish/rlua) [![Build Status](https://travis-ci.org/chucklefish/rlua.svg?branch=master)](https://travis-ci.org/chucklefish/rlua)
This library is a WIP high level interface between Rust and Lua. Its major goal This library is a WIP high level interface between Rust and Lua. Its major
is to expose as flexible of an API between Rust and Lua as possible, while also goal is to expose as easy to use, practical, and flexible of an API between
being completely safe. 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 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 exploration of a different part of the design space. The main high level
@ -29,13 +29,10 @@ IS slightly slower than the approach that hlua takes of only manipulating the
lua stack, but this, combined with internal mutability, allows for a much more lua stack, but this, combined with internal mutability, allows for a much more
flexible API. flexible API.
Currently exposes a *somewhat* complete Lua API covering values and tables and This API is actually heavily inspired by the lua API that I previously wrote
functions and userdata, but does not yet cover coroutines. This API is actually for Starbound, and will become feature complete with that API over time. Some
heavily inspired by the lua API that I previously wrote for Starbound, and will capabilities that API has that are on the roadmap:
become feature complete with that API over time. Some capabilities that API has
that are on the roadmap:
* Proper coroutine support
* Lua profiling support * Lua profiling support
* Execution limits like total instruction limits or lua <-> rust recursion * Execution limits like total instruction limits or lua <-> rust recursion
limits limits
@ -63,10 +60,15 @@ in rustc. For example:
that would do the wrapping. that would do the wrapping.
* Once tuple based variadic generics land, the plan is to completely * Once tuple based variadic generics land, the plan is to completely
eliminate the hlist macros in favor of simple tuples. eliminate the hlist macros in favor of simple tuples.
See [this reddit discussion](http://www.reddit.com/r/rust/comments/5yujt6/) for See [this reddit discussion](http://www.reddit.com/r/rust/comments/5yujt6/) for
details of the current lifetime problem with callback wrapping. details of the current lifetime problem with callback wrapping.
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 or lack thereof ## API Stability or lack thereof
This library is very much Work In Progress, so there may be a lot of API churn. This library is very much Work In Progress, so there may be a lot of API churn.
@ -89,7 +91,9 @@ situations such as:
* Leaving the correct elements on the lua stack and in the correct order, * Leaving the correct elements on the lua stack and in the correct order,
and panicking if these invariants are not met (due to internal bugs). and panicking if these invariants are not met (due to internal bugs).
* Correctly guarding the metatables of userdata so that scripts cannot, for * Correctly guarding the metatables of userdata so that scripts cannot, for
example, swap the `__gc` methods around and cause UB. example, swap the `__gc` methods of userdata and cause UB.
* Correctly handling complex recursive callback scenarios where control goes
from rust to lua back to rust back to lua and so forth.
The library currently *attempts* to handle each of these situations, but there The library currently *attempts* to handle each of these situations, but there
are so many ways to cause unsafety with Lua that it just needs more testing. are so many ways to cause unsafety with Lua that it just needs more testing.