diff --git a/src/function.rs b/src/function.rs index 3589b2b..fe98c5a 100644 --- a/src/function.rs +++ b/src/function.rs @@ -94,6 +94,8 @@ impl<'lua> Function<'lua> { /// /// Internaly it wraps the function to an [`AsyncThread`]. /// + /// Requires `feature = "async"` + /// /// # Examples /// /// ``` diff --git a/src/lib.rs b/src/lib.rs index f9ba28d..0a03e69 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -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 diff --git a/src/lua.rs b/src/lua.rs index 1719fff..a0d96a1 100644 --- a/src/lua.rs +++ b/src/lua.rs @@ -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 { 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> @@ -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> diff --git a/src/scope.rs b/src/scope.rs index 3bcad2c..e208963 100644 --- a/src/scope.rs +++ b/src/scope.rs @@ -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 diff --git a/src/stdlib.rs b/src/stdlib.rs index 0175efb..02f7e3d 100644 --- a/src/stdlib.rs +++ b/src/stdlib.rs @@ -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 { diff --git a/src/table.rs b/src/table.rs index fbd6326..ecd4b95 100644 --- a/src/table.rs +++ b/src/table.rs @@ -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> @@ -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>( diff --git a/src/thread.rs b/src/thread.rs index b8a2513..661abd3 100644 --- a/src/thread.rs +++ b/src/thread.rs @@ -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 /// /// ``` diff --git a/src/userdata.rs b/src/userdata.rs index 5fcf3eb..68aa208 100644 --- a/src/userdata.rs +++ b/src/userdata.rs @@ -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(&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(&mut self, name: &S, function: F)