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

Update documentation

Browse source
This commit is contained in:
Alex Orlenko 2020-05-14 02:12:22 +01:00
parent 79bfb112aa
commit 687ecc9247
8 changed files with 92 additions and 21 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
src/function.rs
View file

@ -94,6 +94,8 @@ impl<'lua> Function<'lua> {
///
/// Internaly it wraps the function to an [`AsyncThread`].
///
/// Requires `feature = "async"`
///
/// # Examples
///
/// ```

6
src/lib.rs
View file

@ -30,6 +30,12 @@
//! Lua code with async capabilities can be executed by [`call_async`] family of functions or polling
//! [`AsyncThread`] using any runtime (eg. Tokio).
//!
//! Requires `feature = "async"`.
//!
//! # `Send` requirement
//! By default `mlua` is `!Send`. This can be changed by enabling `feature = "send"` that adds `Send` requirement
//! to `Function`s and [`UserData`].
//!
//! [Lua programming language]: https://www.lua.org/
//! [`Lua`]: struct.Lua.html
//! [executing]: struct.Lua.html#method.exec

26
src/lua.rs
View file

@ -76,7 +76,8 @@ struct MemoryInfo {
/// [lua_doc]: https://www.lua.org/manual/5.4/manual.html#2.5
pub enum GCMode {
Incremental,
#[cfg(feature = "lua54")]
/// Requires `feature = "lua54"`
#[cfg(any(feature = "lua54", doc))]
Generational,
}
@ -85,6 +86,7 @@ pub(crate) struct AsyncPollPending;
#[cfg(feature = "async")]
pub(crate) static WAKER_REGISTRY_KEY: u8 = 0;
/// Requires `feature = "send"`
#[cfg(feature = "send")]
unsafe impl Send for Lua {}
@ -396,7 +398,9 @@ impl Lua {
/// Returns previous limit (zero means no limit).
///
/// Does not work on module mode where Lua state is managed externally.
#[cfg(any(feature = "lua54", feature = "lua53", feature = "lua52"))]
///
/// Requires `feature = "lua54/lua53/lua52"`
#[cfg(any(feature = "lua54", feature = "lua53", feature = "lua52", doc))]
pub fn set_memory_limit(&self, memory_limit: usize) -> Result<usize> {
let mut extra = mlua_expect!(self.extra.lock(), "extra is poisoned");
if extra.mem_info.is_null() {
@ -410,7 +414,9 @@ impl Lua {
}
/// Returns true if the garbage collector is currently running automatically.
#[cfg(any(feature = "lua54", feature = "lua53", feature = "lua52"))]
///
/// Requires `feature = "lua54/lua53/lua52"`
#[cfg(any(feature = "lua54", feature = "lua53", feature = "lua52", doc))]
pub fn gc_is_running(&self) -> bool {
unsafe { ffi::lua_gc(self.main_state, ffi::LUA_GCISRUNNING, 0) != 0 }
}
@ -527,8 +533,10 @@ impl Lua {
/// Returns the previous mode. More information about the generational GC
/// can be found in the Lua 5.4 [documentation][lua_doc].
///
/// Requires `feature = "lua54"`
///
/// [lua_doc]: https://www.lua.org/manual/5.4/manual.html#2.5.2
#[cfg(feature = "lua54")]
#[cfg(any(feature = "lua54", doc))]
pub fn gc_gen(&self, minor_multiplier: c_int, major_multiplier: c_int) -> GCMode {
let prev_mode = unsafe {
ffi::lua_gc(
@ -769,6 +777,8 @@ impl Lua {
///
/// The family of `call_async()` functions takes care about creating [`Thread`].
///
/// Requires `feature = "async"`
///
/// # Examples
///
/// Non blocking sleep:
@ -895,6 +905,8 @@ impl Lua {
/// An asynchronous version of [`scope`] that allows to create scoped async functions and
/// execute them.
///
/// Requires `feature = "async"`
///
/// [`scope`]: #method.scope
#[cfg(feature = "async")]
pub fn async_scope<'lua, 'scope, R, F, FR>(
@ -1707,6 +1719,8 @@ impl<'lua, 'a> Chunk<'lua, 'a> {
///
/// See [`Chunk::exec`] for more details.
///
/// Requires `feature = "async"`
///
/// [`Chunk::exec`]: struct.Chunk.html#method.exec
#[cfg(feature = "async")]
pub fn exec_async<'fut>(self) -> LocalBoxFuture<'fut, Result<()>>
@ -1740,6 +1754,8 @@ impl<'lua, 'a> Chunk<'lua, 'a> {
///
/// See [`Chunk::eval`] for more details.
///
/// Requires `feature = "async"`
///
/// [`Chunk::eval`]: struct.Chunk.html#method.eval
#[cfg(feature = "async")]
pub fn eval_async<'fut, R>(self) -> LocalBoxFuture<'fut, Result<R>>
@ -1769,6 +1785,8 @@ impl<'lua, 'a> Chunk<'lua, 'a> {
///
/// See [`Chunk::call`] for more details.
///
/// Requires `feature = "async"`
///
/// [`Chunk::call`]: struct.Chunk.html#method.call
#[cfg(feature = "async")]
pub fn call_async<'fut, A, R>(self, args: A) -> LocalBoxFuture<'fut, Result<R>>

2
src/scope.rs
View file

@ -106,6 +106,8 @@ impl<'lua, 'scope> Scope<'lua, 'scope> {
/// This is a version of [`Lua::create_async_function`] that creates a callback which expires on
/// scope drop. See [`Lua::scope`] and [`Lua::async_scope`] for more details.
///
/// Requires `feature = "async"`
///
/// [`Lua::create_async_function`]: struct.Lua.html#method.create_async_function
/// [`Lua::scope`]: struct.Lua.html#method.scope
/// [`Lua::async_scope`]: struct.Lua.html#method.async_scope

38
src/stdlib.rs
View file

@ -1,33 +1,55 @@
use std::ops::{BitAnd, BitAndAssign, BitOr, BitOrAssign, BitXor, BitXorAssign};
use std::u32;
/// Flags describing the set of lua modules to load.
/// Flags describing the set of lua standard libraries to load.
#[derive(Copy, Clone, Debug, Eq, Ord, PartialEq, PartialOrd)]
pub struct StdLib(u32);
impl StdLib {
#[cfg(any(feature = "lua54", feature = "lua53", feature = "lua52"))]
/// [`coroutine`](https://www.lua.org/manual/5.3/manual.html#6.2) library
///
/// Requires `feature = "lua54/lua53/lua52"`
#[cfg(any(feature = "lua54", feature = "lua53", feature = "lua52", doc))]
pub const COROUTINE: StdLib = StdLib(1);
/// [`table`](https://www.lua.org/manual/5.3/manual.html#6.6) library
pub const TABLE: StdLib = StdLib(1 << 1);
/// [`io`](https://www.lua.org/manual/5.3/manual.html#6.8) library
pub const IO: StdLib = StdLib(1 << 2);
/// [`os`](https://www.lua.org/manual/5.3/manual.html#6.9) library
pub const OS: StdLib = StdLib(1 << 3);
/// [`string`](https://www.lua.org/manual/5.3/manual.html#6.4) library
pub const STRING: StdLib = StdLib(1 << 4);
#[cfg(any(feature = "lua54", feature = "lua53"))]
/// [`utf8`](https://www.lua.org/manual/5.3/manual.html#6.5) library
///
/// Requires `feature = "lua54/lua53"`
#[cfg(any(feature = "lua54", feature = "lua53", doc))]
pub const UTF8: StdLib = StdLib(1 << 5);
#[cfg(any(feature = "lua52", feature = "luajit"))]
/// [`bit`](https://www.lua.org/manual/5.2/manual.html#6.7) library
///
/// Requires `feature = "lua52/luajit"`
#[cfg(any(feature = "lua52", feature = "luajit", doc))]
pub const BIT: StdLib = StdLib(1 << 6);
/// [`math`](https://www.lua.org/manual/5.3/manual.html#6.7) library
pub const MATH: StdLib = StdLib(1 << 7);
/// [`package`](https://www.lua.org/manual/5.3/manual.html#6.3) library
pub const PACKAGE: StdLib = StdLib(1 << 8);
#[cfg(feature = "luajit")]
/// [`jit`](http://luajit.org/ext_jit.html) library
///
/// Requires `feature = "luajit"`
#[cfg(any(feature = "luajit", doc))]
pub const JIT: StdLib = StdLib(1 << 9);
/// `ffi` (unsafe) module `feature = "luajit"`
#[cfg(feature = "luajit")]
/// (unsafe) [`ffi`](http://luajit.org/ext_ffi.html) library
///
/// Requires `feature = "luajit"`
#[cfg(any(feature = "luajit", doc))]
pub const FFI: StdLib = StdLib(1 << 30);
/// `debug` (unsafe) module
/// (unsafe) [`debug`](https://www.lua.org/manual/5.3/manual.html#6.10) library
pub const DEBUG: StdLib = StdLib(1 << 31);
/// (unsafe) All standard libraries
pub const ALL: StdLib = StdLib(u32::MAX);
/// The safe subset of the standard libraries
pub const ALL_SAFE: StdLib = StdLib((1 << 30) - 1);
pub fn contains(self, lib: Self) -> bool {

4
src/table.rs
View file

@ -518,6 +518,8 @@ pub trait TableExt<'lua> {
/// Gets the function associated to `key` from the table and asynchronously executes it,
/// passing the table itself along with `args` as function arguments and returning Future.
///
/// Requires `feature = "async"`
///
/// This might invoke the `__index` metamethod.
#[cfg(feature = "async")]
fn call_async_method<'fut, K, A, R>(&self, key: K, args: A) -> LocalBoxFuture<'fut, Result<R>>
@ -530,6 +532,8 @@ pub trait TableExt<'lua> {
/// Gets the function associated to `key` from the table and asynchronously executes it,
/// passing `args` as function arguments and returning Future.
///
/// Requires `feature = "async"`
///
/// This might invoke the `__index` metamethod.
#[cfg(feature = "async")]
fn call_async_function<'fut, K, A, R>(

4
src/thread.rs
View file

@ -47,6 +47,8 @@ pub struct Thread<'lua>(pub(crate) LuaRef<'lua>);
/// Thread (coroutine) representation as an async [`Future`] or [`Stream`].
///
/// Requires `feature = "async"`
///
/// [`Future`]: ../futures_core/future/trait.Future.html
/// [`Stream`]: ../futures_core/stream/trait.Stream.html
#[cfg(feature = "async")]
@ -184,6 +186,8 @@ impl<'lua> Thread<'lua> {
/// values whereas Future version discards that values and poll until the final
/// one (returned from the thread function).
///
/// Requires `feature = "async"`
///
/// # Examples
///
/// ```

31
src/userdata.rs
View file

@ -34,26 +34,31 @@ pub enum MetaMethod {
Pow,
/// The unary minus (`-`) operator.
Unm,
#[cfg(any(feature = "lua54", feature = "lua53"))]
/// The floor division (//) operator.
/// Requires `feature = "lua54/lua53"`
#[cfg(any(feature = "lua54", feature = "lua53", doc))]
IDiv,
#[cfg(any(feature = "lua54", feature = "lua53"))]
/// The bitwise AND (&) operator.
/// Requires `feature = "lua54/lua53"`
#[cfg(any(feature = "lua54", feature = "lua53", doc))]
BAnd,
#[cfg(any(feature = "lua54", feature = "lua53"))]
/// The bitwise OR (|) operator.
/// Requires `feature = "lua54/lua53"`
#[cfg(any(feature = "lua54", feature = "lua53", doc))]
BOr,
#[cfg(any(feature = "lua54", feature = "lua53"))]
/// The bitwise XOR (binary ~) operator.
/// Requires `feature = "lua54/lua53"`
#[cfg(any(feature = "lua54", feature = "lua53", doc))]
BXor,
#[cfg(any(feature = "lua54", feature = "lua53"))]
/// The bitwise NOT (unary ~) operator.
/// Requires `feature = "lua54/lua53"`
#[cfg(any(feature = "lua54", feature = "lua53", doc))]
BNot,
#[cfg(any(feature = "lua54", feature = "lua53"))]
/// The bitwise left shift (<<) operator.
#[cfg(any(feature = "lua54", feature = "lua53", doc))]
Shl,
#[cfg(any(feature = "lua54", feature = "lua53"))]
/// The bitwise right shift (>>) operator.
#[cfg(any(feature = "lua54", feature = "lua53", doc))]
Shr,
/// The string concatenation operator `..`.
Concat,
@ -75,10 +80,12 @@ pub enum MetaMethod {
///
/// This is not an operator, but will be called by methods such as `tostring` and `print`.
ToString,
#[cfg(any(feature = "lua54", feature = "lua53", feature = "lua52"))]
/// The `__pairs` metamethod.
///
/// This is not an operator, but it will be called by the built-in `pairs` function.
///
/// Requires `feature = "lua54/lua53/lua52"`
#[cfg(any(feature = "lua54", feature = "lua53", feature = "lua52", doc))]
Pairs,
/// The `__close` metamethod.
///
@ -87,8 +94,10 @@ pub enum MetaMethod {
/// More information about to-be-closed variabled can be found in the Lua 5.4
/// [documentation][lua_doc].
///
/// Requires `feature = "lua54"`
///
/// [lua_doc]: https://www.lua.org/manual/5.4/manual.html#3.3.8
#[cfg(feature = "lua54")]
#[cfg(any(feature = "lua54", doc))]
Close,
}
@ -172,6 +181,8 @@ pub trait UserDataMethods<'lua, T: UserData> {
///
/// Refer to [`add_method`] for more information about the implementation.
///
/// Requires `feature = "async"`
///
/// [`add_method`]: #method.add_method
#[cfg(feature = "async")]
fn add_async_method<S, A, R, M, MR>(&mut self, name: &S, method: M)
@ -216,6 +227,8 @@ pub trait UserDataMethods<'lua, T: UserData> {
///
/// This is an async version of [`add_function`].
///
/// Requires `feature = "async"`
///
/// [`add_function`]: #method.add_function
#[cfg(feature = "async")]
fn add_async_function<S, A, R, F, FR>(&mut self, name: &S, function: F)