luaneko/luby
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
luby/crates/luajit/src/lib.rs
luaneko 3de17cb77e
Update docs
2025-06-30 17:22:12 +10:00

2490 lines
77 KiB
Rust
Raw Blame History

//! Safe LuaJIT bindings for Rust.
#![allow(non_snake_case)]
use bitflags::bitflags;
use bstr::{BStr, BString, ByteSlice};
use luaffi::future::lua_pollable;
use luajit_sys::*;
use std::{
alloc::{Layout, alloc, dealloc, realloc},
cell::UnsafeCell,
ffi::CString,
fmt,
marker::PhantomData,
mem::{self, ManuallyDrop},
num::NonZero,
ops::{self, Deref, DerefMut},
os::raw::{c_char, c_int, c_void},
pin::Pin,
process,
ptr::{self, NonNull},
rc::Rc,
slice,
};
/// LuaJIT version string.
pub fn version() -> &'static str {
LUAJIT_VERSION.to_str().unwrap()
}
/// LuaJIT copyright string.
pub fn copyright() -> &'static str {
LUAJIT_COPYRIGHT.to_str().unwrap()
}
/// LuaJIT URL string.
pub fn url() -> &'static str {
LUAJIT_URL.to_str().unwrap()
}
/// Lua result.
pub type Result<T> = std::result::Result<T, Error>;
/// Lua error.
#[derive(Debug)]
pub struct Error(ErrorInner);
#[derive(Debug)]
enum ErrorInner {
Memory,
Syntax {
msg: BString,
_chunk: Chunk,
},
Call {
msg: BString,
kind: ErrorKind,
trace: Option<BString>,
},
_Argument {
index: u32,
func: BString,
err: Box<Error>,
},
_Slot {
index: i32,
err: Box<Error>,
},
Type {
expected: &'static str,
got: &'static str,
},
Other(Box<dyn std::error::Error + Send + Sync>),
}
impl Error {
/// Creates a new error with an arbitrary error payload.
pub fn new(error: impl Into<Box<dyn std::error::Error + Send + Sync>>) -> Self {
Self(ErrorInner::Other(error.into()))
}
/// Creates a new error for a type mismatch.
pub fn invalid_type(expected: &'static str, got: &'static str) -> Self {
Self(ErrorInner::Type { expected, got })
}
fn memory() -> Self {
Self(ErrorInner::Memory)
}
fn syntax(msg: impl AsRef<[u8]>, chunk: Chunk) -> Self {
Self(ErrorInner::Syntax {
msg: msg.as_ref().into(),
_chunk: chunk,
})
}
fn call(kind: ErrorKind, msg: impl AsRef<[u8]>, trace: Option<BString>) -> Self {
Self(ErrorInner::Call {
kind,
msg: msg.as_ref().into(),
trace,
})
}
/// Kind of this error.
pub fn kind(&self) -> ErrorKind {
match self.0 {
ErrorInner::Memory => ErrorKind::Memory,
ErrorInner::Syntax { .. } => ErrorKind::Syntax,
ErrorInner::Call { kind, .. } => kind,
_ => std::error::Error::source(self)
.and_then(|err| err.downcast_ref::<Error>())
.map(|err| err.kind())
.unwrap_or(ErrorKind::Runtime),
}
}
/// Stack trace, or [`None`] if it was not collected.
pub fn trace(&self) -> Option<&BStr> {
match self.0 {
ErrorInner::Call { ref trace, .. } => trace.as_ref().map(|s| s.as_ref()),
_ => None,
}
}
}
impl fmt::Display for Error {
fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
match &self.0 {
ErrorInner::Syntax { msg, .. } | ErrorInner::Call { msg, .. } => write!(f, "{msg}"),
ErrorInner::_Argument { index, func, err } => {
write!(f, "bad argument #{index} to '{func}': {err}")
}
ErrorInner::_Slot { index, err } => write!(f, "bad stack slot #{index}: {err}"),
ErrorInner::Type { expected, got } => {
write!(f, "{expected} expected, got {got}")
}
_ => match std::error::Error::source(self) {
Some(err) => write!(f, "{err}"),
None => write!(f, "{}", self.kind()),
},
}
}
}
impl std::error::Error for Error {
fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
match &self.0 {
ErrorInner::_Argument { err, .. } | ErrorInner::_Slot { err, .. } => Some(err),
ErrorInner::Other(err) => Some(err.as_ref()),
_ => None,
}
}
}
/// Lua error kind.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum ErrorKind {
/// Runtime error.
Runtime,
/// Syntax error.
Syntax,
/// Memory allocation error.
Memory,
/// Error while running the error handler function.
Error,
}
impl ErrorKind {
fn from_raw(code: c_int) -> Option<Self> {
Some(match code {
LUA_ERRRUN => Self::Runtime,
LUA_ERRSYNTAX => Self::Syntax,
LUA_ERRMEM => Self::Memory,
LUA_ERRERR => Self::Error,
_ => return None,
})
}
/// Name of this error kind, like `"runtime"` or `"syntax"`.
pub fn name(self) -> &'static str {
match self {
Self::Runtime => "runtime",
Self::Syntax => "syntax",
Self::Memory => "memory",
Self::Error => "error",
}
}
}
impl fmt::Display for ErrorKind {
fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
match self {
ErrorKind::Runtime => write!(f, "runtime error"),
ErrorKind::Syntax => write!(f, "syntax error"),
ErrorKind::Memory => write!(f, "memory allocation error"),
ErrorKind::Error => write!(f, "error while running the error handler function"),
}
}
}
/// Lua type.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
pub enum Type {
/// `nil` type.
#[default]
Nil,
/// `boolean` type.
Boolean,
/// `lightuserdata` type.
Lightuserdata,
/// `number` type.
Number,
/// `string` type.
String,
/// `table` type.
Table,
/// `function` type.
Function,
/// `userdata` type.
Userdata,
/// `thread` type.
Thread,
/// `cdata` type.
Cdata,
}
impl Type {
fn from_raw(code: c_int) -> Option<Self> {
Some(match code {
LUA_TNIL => Self::Nil,
LUA_TBOOLEAN => Self::Boolean,
LUA_TLIGHTUSERDATA => Self::Lightuserdata,
LUA_TNUMBER => Self::Number,
LUA_TSTRING => Self::String,
LUA_TTABLE => Self::Table,
LUA_TFUNCTION => Self::Function,
LUA_TUSERDATA => Self::Userdata,
LUA_TTHREAD => Self::Thread,
LUA_TCDATA => Self::Cdata,
_ => return None,
})
}
/// Name of this type, like `"nil"` or `"string"`.
pub fn name(&self) -> &'static str {
match self {
Self::Nil => "nil",
Self::Boolean => "boolean",
Self::Lightuserdata => "lightuserdata",
Self::Number => "number",
Self::String => "string",
Self::Table => "table",
Self::Function => "function",
Self::Userdata => "userdata",
Self::Thread => "thread",
Self::Cdata => "cdata",
}
}
}
impl fmt::Display for Type {
fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
write!(f, "{}", self.name())
}
}
/// Lua thread status.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
pub enum Status {
/// Thread is alive (currently running or can run a function).
#[default]
Normal,
/// Thread terminated with an error and can no longer be used.
Dead(
/// Why this thread is dead.
ErrorKind,
),
/// Thread suspended with `coroutine.yield(...)` and is awaiting resume.
Suspended,
}
impl Status {
fn from_raw(code: c_int) -> Option<Self> {
Some(match code {
LUA_OK => Self::Normal,
LUA_YIELD => Self::Suspended,
_ => Self::Dead(ErrorKind::from_raw(code)?),
})
}
/// Name of this status, like `"normal"` or `"suspended"`.
pub fn name(&self) -> &'static str {
match self {
Status::Normal => "normal",
Status::Dead(_) => "dead",
Status::Suspended => "suspended",
}
}
}
impl fmt::Display for Status {
fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
match self {
Status::Normal => write!(f, "normal"),
Status::Dead(why) => write!(f, "dead ({why})"),
Status::Suspended => write!(f, "suspended"),
}
}
}
/// Result of [`resume`](Stack::resume).
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum ResumeStatus {
/// Thread completed successfully and can run another function.
#[default]
Ok,
/// Thread suspended with `coroutine.yield(...)` and is awaiting resume.
Suspended,
}
impl ResumeStatus {
/// Name of this status, like `"ok"` or `"suspended"`.
pub fn name(&self) -> &'static str {
match self {
ResumeStatus::Ok => "ok",
ResumeStatus::Suspended => "suspended",
}
}
}
impl fmt::Display for ResumeStatus {
fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
write!(f, "{}", self.name())
}
}
bitflags! {
/// Flags for [`Stack::load`].
#[repr(transparent)]
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub struct LoadMode: usize {
/// No flags.
const NONE = 0b_00_00;
/// Auto-detect chunk type (flag `bt`).
const AUTO = 0b_00_11;
/// Text chunk only (flag `t`).
const TEXT = 0b_00_01;
/// Binary chunk only (flag `b`).
const BINARY = 0b_00_10;
/// Force 32-bit binary format (flag `W`, implies `b`).
const GC32 = 0b_10_10;
/// Force 64-bit binary format (flag `X`, implies `b`).
const GC64 = 0b_01_10;
}
}
impl Default for LoadMode {
fn default() -> Self {
Self::AUTO
}
}
impl LoadMode {
fn mode_str(&self) -> CString {
let mut s = String::new();
self.contains(Self::TEXT).then(|| s.push_str("t"));
self.contains(Self::BINARY).then(|| s.push_str("b"));
self.contains(Self::GC32).then(|| s.push_str("W"));
self.contains(Self::GC64).then(|| s.push_str("X"));
CString::new(s).unwrap()
}
}
bitflags! {
/// Flags for [`Stack::dump`].
#[repr(transparent)]
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub struct DumpMode: usize {
/// No flags.
const NONE = 0b_00_0_0;
/// Strip debug information (flag `s`).
const STRIP = 0b_00_0_1;
/// Deterministic mode (flag `d`).
const DETERMINISTIC = 0b_00_1_0;
/// Force 32-bit binary format (flag `W`).
const GC32 = 0b_10_0_0;
/// Force 64-bit binary format (flag `X`).
const GC64 = 0b_01_0_0;
}
}
impl Default for DumpMode {
fn default() -> Self {
Self::DETERMINISTIC
}
}
impl DumpMode {
fn mode_str(&self) -> CString {
let mut s = String::new();
self.contains(Self::STRIP).then(|| s.push_str("s"));
self.contains(Self::DETERMINISTIC).then(|| s.push_str("d"));
self.contains(Self::GC32).then(|| s.push_str("W"));
self.contains(Self::GC64).then(|| s.push_str("X"));
CString::new(s).unwrap()
}
}
/// Lua chunk data.
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
pub struct Chunk {
name: BString,
content: BString,
mode: LoadMode,
}
impl Chunk {
/// Creates a new chunk with the given content.
pub fn new(content: impl Into<BString>) -> Self {
Self {
name: "?".into(),
content: content.into(),
mode: LoadMode::AUTO,
}
}
/// Name of this chunk, like `"?"` or `"@path/to/file.lua"`.
pub fn name(&self) -> &BStr {
self.name.as_ref()
}
/// Path of this chunk, if the name of this chunk starts with `@`.
pub fn path(&self) -> Option<&BStr> {
self.name.strip_prefix(b"@").map(|s| s.as_ref())
}
/// Mode flag for loading this chunk.
pub fn mode(&self) -> LoadMode {
self.mode
}
/// Assigns a name to this chunk.
pub fn with_name(self, name: impl AsRef<[u8]>) -> Self {
Self {
name: name.as_ref().into(),
..self
}
}
/// Assigns a name to this chunk as a path.
///
/// This sets the name of this chunk to `"@path"`, where `path` is the given path.
pub fn with_path(self, path: impl AsRef<[u8]>) -> Self {
let mut name = BString::from(b"@");
name.extend_from_slice(path.as_ref());
Self { name, ..self }
}
/// Assigns a mode flag for loading this chunk.
pub fn with_mode(self, mode: LoadMode) -> Self {
Self { mode, ..self }
}
}
impl Deref for Chunk {
type Target = BString;
fn deref(&self) -> &Self::Target {
&self.content
}
}
impl DerefMut for Chunk {
fn deref_mut(&mut self) -> &mut Self::Target {
&mut self.content
}
}
impl fmt::Display for Chunk {
fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
write!(f, "{}", self.content)
}
}
impl<T: Into<BString>> From<T> for Chunk {
fn from(value: T) -> Self {
Self::new(value)
}
}
macro_rules! assert_slots {
($stack:expr, $n:expr) => {{
let size = $stack.size();
let n = $n;
assert!(
n <= size,
"stack underflow: expected at least {n} values, got {size}: {stack:?}",
stack = $stack,
);
let _base = size - n;
_base
}};
}
macro_rules! assert_type {
($stack:expr, $slot:expr, $expected:expr, $pat:pat) => {{
let slot = $stack.slot($slot);
let expected = $expected;
let idx = slot.index();
let got = slot.ty();
assert!(
matches!(got, $pat),
"expected {expected} at index {idx}, got {got}: {stack:?}",
stack = $stack,
);
slot
}};
}
#[derive(Debug)]
struct GlobalState {
ptr: NonNull<lua_State>,
_alloc: Box<UnsafeCell<AllocatorState>>,
}
#[derive(Debug, Default)]
struct AllocatorState {
alloc: usize,
dealloc: usize,
}
impl GlobalState {
pub fn new() -> Result<Self> {
unsafe {
// SAFETY: lua_newstate may return a null pointer if allocation fails
let mut alloc = Box::new(UnsafeCell::new(AllocatorState::default()));
let ud = alloc.get_mut() as *mut _ as *mut c_void;
let ptr = NonNull::new(lua_newstate(Some(Self::alloc_cb), ud)).ok_or(Error::memory())?;
lua_atpanic(ptr.as_ptr(), Some(Self::panic_cb));
Ok(Self { ptr, _alloc: alloc })
}
}
fn as_ptr(&self) -> *mut lua_State {
self.ptr.as_ptr()
}
unsafe extern "C" fn alloc_cb(
ud: *mut c_void,
ptr: *mut c_void,
osize: usize,
nsize: usize,
) -> *mut c_void {
unsafe {
// https://github.com/tikv/jemallocator/blob/main/jemallocator/src/lib.rs
#[cfg(any(target_arch = "arm", target_arch = "mips", target_arch = "powerpc"))]
const ALIGNOF_MAX_ALIGN_T: usize = 8;
#[cfg(any(
target_arch = "x86",
target_arch = "x86_64",
target_arch = "aarch64",
target_arch = "powerpc64",
target_arch = "loongarch64",
target_arch = "mips64",
target_arch = "riscv64",
target_arch = "s390x",
target_arch = "sparc64"
))]
const ALIGNOF_MAX_ALIGN_T: usize = 16;
let old = Layout::from_size_align(osize, ALIGNOF_MAX_ALIGN_T)
.expect("lua alloc error: requested osize is too large");
let new = Layout::from_size_align(nsize, ALIGNOF_MAX_ALIGN_T)
.expect("lua alloc error: requested nsize is too large");
let state = &mut *(ud as *mut AllocatorState);
let ptr = ptr as *mut u8;
// SAFETY: from lua documentation:
//
// When nsize is zero, the allocator must return NULL; if osize is not zero, it should
// free the block pointed to by ptr. When nsize is not zero, the allocator returns
// NULL if and only if it cannot fill the request. When nsize is not zero and osize is
// zero, the allocator should behave like malloc. When nsize and osize are not zero,
// the allocator behaves like realloc. Lua assumes that the allocator never fails when
// osize >= nsize.
(if new.size() == 0 {
if old.size() != 0 {
dealloc(ptr, old);
state.dealloc += old.size();
}
ptr::null_mut()
} else {
let ptr = if old.size() == 0 {
alloc(new)
} else {
realloc(ptr, old, new.size())
};
if !ptr.is_null() {
state.alloc += new.size();
state.dealloc += old.size();
}
ptr
}) as *mut c_void
}
}
unsafe extern "C" fn panic_cb(L: *mut lua_State) -> c_int {
// SAFETY: we cannot recover from uncaught lua exceptions; abort instead
assert!(!L.is_null());
let stack = unsafe { Stack::new_unchecked(L) };
let msg = stack
.top()
.and_then(|s| s.string())
.unwrap_or(b"unknown error".into());
eprintln!("lua panicked: {msg}");
process::abort()
}
}
impl Drop for GlobalState {
fn drop(&mut self) {
unsafe { lua_close(self.as_ptr()) }
}
}
/// Key for a [`Ref`] that represents no-reference.
///
/// This key can always be used safely in [`from_raw`](Ref::from_raw) to create a [`Ref`] that does
/// not reference any value in the registry. If dereferenced, it will always evaluate to `nil`.
pub use luajit_sys::LUA_NOREF;
/// Lua value handle into the registry.
///
/// Equivalent to [`luaL_ref`] and [`luaL_unref`] with [`LUA_REGISTRYINDEX`] as the target table.
#[derive(Debug)]
pub struct Ref {
state: Rc<GlobalState>,
key: c_int,
}
impl Ref {
/// Creates a new ref by popping the value at the top of the given stack.
pub fn new(stack: &mut State) -> Self {
// SAFETY: luaL_ref always returns a unique key
assert_slots!(stack, 1);
unsafe { Self::from_raw(stack, luaL_ref(stack.as_ptr(), LUA_REGISTRYINDEX)) }
}
/// Creates a new ref from the given key.
///
/// # Safety
///
/// `key` must have been created by [`into_raw`](Self::into_raw) or a previous call to
/// [`luaL_ref`] with [`LUA_REGISTRYINDEX`] as the target table. It must also be unique; no two
/// [`Ref`] instances with the same key should exist at the same time.
pub unsafe fn from_raw(stack: &State, key: c_int) -> Self {
let state = Rc::clone(&stack.thread_ref.state);
Self { state, key }
}
/// Consumes this ref and returns the original key used to create the ref.
///
/// This key can be used to index into the registry table ([`LUA_REGISTRYINDEX`]) to retrieve
/// the referenced value. The key can be converted back into a ref using
/// [`from_raw`](Ref::from_raw).
pub fn into_raw(self) -> c_int {
let Self { ref mut state, key } = *ManuallyDrop::new(self);
unsafe { ptr::drop_in_place(state) }
key
}
}
impl Clone for Ref {
fn clone(&self) -> Self {
let state = Rc::clone(&self.state);
let key = unsafe {
// SAFETY: luaL_ref always returns a unique key
let mut stack = Stack::new_unchecked(state.as_ptr());
stack.geti(PseudoIndex::Registry, self.key as isize);
luaL_ref(stack.as_ptr(), LUA_REGISTRYINDEX)
};
Self { state, key }
}
}
impl Drop for Ref {
fn drop(&mut self) {
unsafe { luaL_unref(self.state.as_ptr(), LUA_REGISTRYINDEX, self.key) }
}
}
/// Lua state handle.
///
/// A state instance can be manipulated using the [`Stack`] object that it mutably dereferences to.
#[derive(Debug)]
pub struct State {
thread_ref: Ref,
stack: Stack,
}
impl State {
/// Creates a new [`State`].
///
/// All built-in libraries are opened by default.
///
/// This may return an error if allocation or library initialisation fails.
pub fn new() -> Result<Self> {
let state = Rc::new(GlobalState::new()?);
let mut state = Self {
stack: unsafe { Stack::new_unchecked(state.as_ptr()) },
thread_ref: Ref {
// SAFETY: the main thread doesn't need a ref, it doesn't get garbage collected
state,
key: LUA_NOREF,
},
};
state.push(Function::Bare(Self::open_cb));
state.call(0, Some(0))?;
Ok(state)
}
/// Creates a new empty thread (coroutine) associated with the given state.
pub fn new_thread(state: &State) -> Self {
Self {
// SAFETY: must call lua_newthread first before ref'ing it
stack: unsafe {
state.ensure(1);
Stack::new_unchecked(lua_newthread(state.as_ptr()))
},
thread_ref: Ref {
state: Rc::clone(&state.thread_ref.state),
key: unsafe { luaL_ref(state.as_ptr(), LUA_REGISTRYINDEX) },
},
}
}
fn open_cb(stack: &mut Stack) -> c_int {
unsafe {
// SAFETY: this is only ever called once on state initialisation
luaL_openlibs(stack.as_ptr()); // lua base libraries
luaJIT_openlibs(stack.as_ptr()); // luajit-sys extension to open jitlibs
0
}
}
}
impl Deref for State {
type Target = Stack;
fn deref(&self) -> &Self::Target {
&self.stack
}
}
impl DerefMut for State {
fn deref_mut(&mut self) -> &mut Self::Target {
&mut self.stack
}
}
/// Lua stack handle.
///
/// This simply wraps a pointer to the actual [`lua_State`] object and provides safe methods to
/// manipulate the state. Lua states can only be manipulated if the Rust caller holds a mutable
/// reference to its [`Stack`].
///
/// A mutable [`State`] can be dereferenced to obtain a mutable reference to its inner [`Stack`]
/// safely.
///
/// # Indexing
///
/// All indices are 1-based as in Lua convention. Positive values are absolute indices from the
/// bottom of the stack, where index `1` is the first value, index `2` is the second value, and so
/// on. Negative values are relative indices from the top of the stack, where index `-1` is the last
/// value, index `-2` is the second last value, and so on. Index `0` is either invalid or indicates
/// an empty stack.
///
/// # Mutability
///
/// All methods which mutate the *visible contents* of the stack require a mutable reference. For
/// example, pushing values to or popping values from the stack require `&mut Stack`, while parsing
/// a value on the stack into a Rust value requires `&Stack`.
///
/// Although a [`lua_State`] as a C object is internally mutable, this limitation exists to allow
/// for zero-copy marshalling of values like Lua `string`s into Rust `&str` without any allocations.
/// It is guaranteed that the lifetime of an `&str` will not outlive the lifetime of the original
/// `string` while the stack is immutable and the original string cannot be removed from the stack,
/// preventing it from being garbage-collected by Lua.
#[derive(PartialEq, Eq, Hash)]
#[repr(transparent)]
pub struct Stack(NonNull<lua_State>);
impl Stack {
unsafe fn new_unchecked(ptr: *mut lua_State) -> Self {
debug_assert!(!ptr.is_null(), "attempt to create stack with null pointer");
Self(unsafe { NonNull::new_unchecked(ptr) })
}
/// Pointer to the underlying [`lua_State`].
pub fn as_ptr(&self) -> *mut lua_State {
self.0.as_ptr()
}
/// Size of the stack.
///
/// Equivalent to [`lua_gettop`].
pub fn size(&self) -> u32 {
unsafe { lua_gettop(self.as_ptr()) as u32 }
}
/// Resizes the stack to fit exactly `n` values, reallocating the stack and popping any
/// extraneous values or pushing `nil`s to fill the space as necessary.
///
/// Equivalent to [`lua_settop`].
///
/// # Panics
///
/// Panics if the stack could not be resized.
pub fn resize(&mut self, n: u32) {
assert!(
n <= (LUAI_MAXCSTACK as u32),
"stack overflow: cannot resize stack to size > {LUAI_MAXCSTACK}"
);
// SAFETY: lua_settop can throw on oom (calls growstack not cpgrowstack) when growing, so we
// need to call ensure first if we might reallocate
let size = self.size();
n.checked_sub(size).map(|n| self.ensure(n));
unsafe { lua_settop(self.as_ptr(), n as c_int) }
}
/// Reallocates the stack to fit `n` more values, if necessary.
///
/// This does not resize the stack and thus does not require a mutable reference as it does not
/// mutate the *visible contents* of the stack.
///
/// Equivalent to [`lua_checkstack`].
///
/// # Panics
///
/// Panics if reallocation fails.
pub fn ensure(&self, n: u32) {
if n != 0 {
// lua_checkstack throws on oom in PUC lua 5.1, but it is fine in luajit
assert!(
n <= (LUAI_MAXCSTACK as u32),
"stack overflow: cannot reallocate stack to size > {LUAI_MAXCSTACK}"
);
assert!(
unsafe { lua_checkstack(self.as_ptr(), n as c_int) != 0 },
"stack overflow: failed to reallocate stack to size {len}",
len = self.size() + n,
)
}
}
/// Pops `n` values at the top of the stack.
///
/// Equivalent to [`lua_pop`].
///
/// # Panics
///
/// Panics if there are less than `n` values on the stack.
pub fn pop(&mut self, n: u32) {
if n != 0 {
assert_slots!(self, n);
unsafe { lua_pop(self.as_ptr(), n as c_int) }
}
}
/// Pops the value at the top of the stack and inserts it at index `idx` by shifting up existing
/// values, and returns the slot for that index.
///
/// If the index `idx` points to the top of the stack, this does not pop anything and keeps the
/// stack untouched.
///
/// Index `idx` cannot be a pseudo-index.
///
/// Equivalent to [`lua_insert`].
///
/// # Panics
///
/// Panics if the stack is empty or the index `idx` is invalid.
pub fn pop_insert<'s>(&'s mut self, idx: impl ToSlot) -> Slot<'s> {
let top = self.slot(-1).index();
let slot = self.slot(idx);
let idx = slot.index();
if let Index::Stack(_) = idx {
unsafe { (idx != top).then(|| lua_insert(self.as_ptr(), idx.into_raw())) };
} else {
panic!("cannot insert into pseudo-index {idx}");
}
slot
}
/// Pops the value at the top of the stack, replaces the value at index `idx` with it, and
/// returns the slot for that index.
///
/// If the index `idx` points to the top of the stack, this does not pop anything and keeps the
/// stack untouched.
///
/// Equivalent to [`lua_replace`].
///
/// # Panics
///
/// Panics if the stack is empty or the index `idx` is invalid.
pub fn pop_replace<'s>(&'s mut self, idx: impl ToSlot) -> Slot<'s> {
let top = self.slot(-1).index();
let slot = self.slot(idx);
let idx = slot.index();
unsafe { (idx != top).then(|| lua_replace(self.as_ptr(), idx.into_raw())) };
slot
}
/// Status of the current thread.
///
/// Equivalent to [`lua_status`].
pub fn status(&self) -> Status {
Status::from_raw(unsafe { lua_status(self.as_ptr()) }).unwrap()
}
/// Iterator over all values on the stack.
pub fn iter<'s>(&'s self) -> StackIter<'s> {
StackIter::new(self)
}
/// Returns a guard that resets the stack to the current size when dropped.
///
/// This is useful for implementing idempotent stack operations which must keep the stack size
/// consistent.
pub fn guard<'s>(&'s mut self) -> StackGuard<'s> {
StackGuard::new(self, false)
}
/// Similar to [`guard`](Self::guard) but takes an immutable reference to [`Stack`].
///
/// # Safety
///
/// The caller must ensure that the stack from this point onwards until the returned
/// [`StackGuard`] is dropped never mutates any values already on the stack *before* the guard
/// was created. The caller may push new values onto the guarded stack and mutate or pop values
/// that they themselves have pushed, but mutating or popping any values that were already on
/// the stack before the guard was created is **undefined behaviour**.
pub unsafe fn guard_unchecked<'s>(&'s self) -> StackGuard<'s> {
StackGuard::new(self, true)
}
/// Slot for the value at the top of the stack, or [`None`] if the stack is empty.
pub fn top<'s>(&'s self) -> Option<Slot<'s>> {
let size = self.size();
(size != 0).then(|| unsafe { self.slot_unchecked(Index::stack(size)) })
}
/// Slot for the value at index `idx`.
///
/// # Panics
///
/// Panics if the index `idx` is invalid.
pub fn slot<'s>(&'s self, idx: impl ToSlot) -> Slot<'s> {
idx.to_slot(self)
}
/// Slot for the value at index `idx`, without checking if the index is valid.
///
/// # Safety
///
/// The caller must ensure that the index is valid, i.e. within the bounds of the stack.
pub unsafe fn slot_unchecked<'s>(&'s self, idx: Index) -> Slot<'s> {
// SAFETY: the caller must ensure that the index is valid
unsafe { Slot::new_unchecked(self, idx) }
}
/// Slot for the upvalue of the current function at index `idx`.
pub fn upvalue<'s>(&'s self, idx: u32) -> Slot<'s> {
self.slot(Index::upvalue(idx))
}
/// Slot for the registry table.
pub fn registry<'s>(&'s self) -> Slot<'s> {
self.slot(PseudoIndex::Registry)
}
/// Slot for the environment table of the current function.
pub fn environment<'s>(&'s self) -> Slot<'s> {
self.slot(PseudoIndex::Environment)
}
/// Slot for the global environment table of the current thread.
pub fn globals<'s>(&'s self) -> Slot<'s> {
self.slot(PseudoIndex::Globals)
}
/// Pushes the given value to the top of the stack.
///
/// Equivalent to the `lua_push*` family of functions depending on the type of `T`.
pub fn push<'s, T: Push>(&'s mut self, value: T) {
value.push(self);
}
/// Pushes the value at index `idx` to the top of the stack.
///
/// Equivalent to [`lua_pushvalue`].
pub fn push_idx(&mut self, idx: impl ToSlot) {
self.push(self.slot(idx).index());
}
/// Gets a field of the table at index `idx` using the value at the top of the stack as the key,
/// replaces the key with the field value, and returns the slot for it.
///
/// This function does not invoke the `__index` metamethod.
///
/// Equivalent to [`lua_rawget`].
///
/// # Panics
///
/// Panics if the value at index `idx` is not a table.
pub fn get<'s>(&'s mut self, idx: impl ToSlot) -> Slot<'s> {
let slot = assert_type!(self, idx, "table", Type::Table);
assert_slots!(self, 1);
unsafe { lua_rawget(self.as_ptr(), slot.index().into_raw()) }
slot
}
/// Gets a field of the table at index `idx` using `n` as the key, pushes the field value at the
/// top of the stack, and returns the slot for it.
///
/// This function does not invoke the `__index` metamethod.
///
/// Equivalent to [`lua_rawgeti`].
///
/// # Panics
///
/// Panics if the value at index `idx` is not a table.
pub fn geti<'s>(&'s mut self, idx: impl ToSlot, n: isize) -> Slot<'s> {
let slot = assert_type!(self, idx, "table", Type::Table);
self.ensure(1);
match n.try_into() {
Ok(n) => unsafe { lua_rawgeti(self.as_ptr(), slot.index().into_raw(), n) },
Err(_) => unsafe {
lua_pushinteger(self.as_ptr(), n as lua_Integer);
lua_rawget(self.as_ptr(), slot.index().into_raw());
},
}
slot
}
/// Sets a field of the table at index `idx` using two values at the top of the stack as the key
/// and value.
///
/// Both the key and value are popped from the stack.
///
/// This function does not invoke the `__newindex` metamethod.
///
/// Equivalent to [`lua_rawset`].
///
/// # Panics
///
/// Panics if the value at index `idx` is not a table.
pub fn set(&mut self, idx: impl ToSlot) {
let slot = assert_type!(self, idx, "table", Type::Table);
assert_slots!(self, 2);
unsafe { lua_rawset(self.as_ptr(), slot.index().into_raw()) }
}
/// Sets a field of the table at index `idx` using `n` is the key and the value at the top of
/// the stack as the value.
///
/// The value is popped from the stack.
///
/// This function does not invoke the `__newindex` metamethod.
///
/// Equivalent to [`lua_rawseti`].
///
/// # Panics
///
/// Panics if the value at index `idx` is not a table.
pub fn seti(&mut self, idx: impl ToSlot, n: isize) {
let slot = assert_type!(self, idx, "table", Type::Table);
assert_slots!(self, 1);
match n.try_into() {
Ok(n) => unsafe { lua_rawseti(self.as_ptr(), slot.index().into_raw(), n) },
Err(_) => unsafe {
self.ensure(1);
lua_pushinteger(self.as_ptr(), n as lua_Integer);
lua_insert(self.as_ptr(), -2);
lua_rawset(self.as_ptr(), slot.index().into_raw());
},
}
}
/// Gets the metatable of the value at index `idx`, pushes it onto the stack, and returns the
/// slot for that metatable.
///
/// If the value at index `idx` does not have a metatable, then nothing is pushed onto the stack
/// and [`None`] is returned.
///
/// Metatables can be attached to non-table values including primitives like numbers, strings,
/// and booleans.
pub fn get_metatable<'s>(&'s mut self, idx: impl ToSlot) -> Option<Slot<'s>> {
let slot = self.slot(idx);
self.ensure(1);
unsafe { lua_getmetatable(self.as_ptr(), slot.index().into_raw()) != 0 }
.then(|| self.slot(-1))
}
/// Sets the metatable of the value at index `idx` to the value at the top of the stack, and
/// returns the slot for that value.
///
/// The value at the top of the stack can be `nil` to remove the metatable, or a table to set it
/// as the new metatable. This value is popped from the stack and set as the metatable of the
/// value at index `idx`.
///
/// Metatables can be attached to non-table values including primitives like numbers, strings,
/// and booleans.
pub fn set_metatable<'s>(&'s mut self, idx: impl ToSlot) -> Slot<'s> {
let slot = self.slot(idx);
assert_type!(self, -1, "table or nil", Type::Table | Type::Nil);
unsafe { lua_setmetatable(self.as_ptr(), slot.index().into_raw()) }; // always returns 1
slot
}
/// Packs the array-part of the table at index `idx` from the stack.
///
/// This pops `n` values at the top of the stack, sets them as the fields of the table at index
/// `idx` at indices `1` to `n` inclusive, then sets the field `"n"` to `n`. Any existing values
/// in the table are overwritten. If the table already has more than `n` values in its
/// array-part, these values are **not** cleared. The number of values popped is returned, which
/// is always equal to `n`.
///
/// This method does not invoke any metamethods. The table is not popped from the stack.
///
/// Equivalent to `table.pack(...)`.
///
/// # Panics
///
/// Panics if `n` is negative, there are not enough values on the stack, or the value at index
/// `idx` is not a table.
pub fn pack(&mut self, idx: impl ToSlot, n: u32) -> u32 {
let slot = assert_type!(self, idx, "table", Type::Table);
let base = assert_slots!(self, n);
if let Index::Stack(idx) = slot.index() {
assert!(
idx.get() <= base,
"cannot pack a table into itself: {self:?}"
);
}
unsafe {
for i in 0..n {
lua_rawseti(self.as_ptr(), slot.index().into_raw(), (n - i) as c_int);
}
self.ensure(2);
lua_pushliteral(self.as_ptr(), "n");
lua_pushinteger(self.as_ptr(), n as lua_Integer);
lua_rawset(self.as_ptr(), slot.index().into_raw());
n
}
}
/// Unpacks the array-part of the table at index `idx` onto the stack, and returns the number of
/// values pushed.
///
/// If `j` is [`None`], then it is set to be the value of the field `"n"` interpreted as an
/// integer. If this field does not exist, then it is set to the be length of the table as
/// defined by the Lua `#` length operator. All values in indices `i` to `j` inclusive are
/// pushed to the top of the stack in ascending order. If `i > j`, then nothing is pushed.
/// Otherwise, `j - i + 1` values are pushed, and the number of values pushed is returned.
///
/// This method does not invoke any metamethods. The table is not popped from the stack or
/// altered in any way.
///
/// Equivalent to `table.unpack(list, i, j)`.
///
/// # Panics
///
/// Panics if the value at index `idx` is not a table.
pub fn unpack(&mut self, idx: impl ToSlot, i: isize, j: Option<isize>) -> u32 {
let slot = assert_type!(self, idx, "table", Type::Table);
let j = match j {
Some(j) => j,
None => unsafe {
self.ensure(1);
lua_pushliteral(self.as_ptr(), "n");
lua_rawget(self.as_ptr(), slot.index().into_raw());
let mut isnum = 0;
let n = lua_tointegerx(self.as_ptr(), -1, &raw mut isnum);
lua_pop(self.as_ptr(), 1);
(isnum != 0)
.then_some(n as isize)
.unwrap_or_else(|| slot.length() as isize)
},
};
let n = (j - i + 1)
.max(0)
.try_into()
.expect("too many values to unpack");
if n > 0 {
self.ensure(n);
for k in i..=j {
match k.try_into() {
Ok(n) => unsafe { lua_rawgeti(self.as_ptr(), slot.index().into_raw(), n) },
Err(_) => unsafe {
lua_pushinteger(self.as_ptr(), n as lua_Integer);
lua_rawget(self.as_ptr(), slot.index().into_raw());
},
}
}
}
n
}
/// Pushes the result of a Lua `require(...)` call onto the stack.
///
/// Any return values from the library `name` are pushed. Lua libraries are allowed to return
/// multiple values. If `nret` is not [`None`], then the number of return values pushed will be
/// exactly `nret`, filling with nils if necessary. The number values pushed to the stack is
/// returned.
///
/// Equivalent to `require(name)`.
pub fn require(&mut self, name: impl AsRef<[u8]>, nret: Option<u32>) -> Result<u32> {
self.push("require");
self.get(PseudoIndex::Globals);
self.push(name.as_ref());
self.call(1, nret)
}
/// Pushes the given chunk as a function to the top of the stack and returns the slot for the
/// new function.
///
/// Equivalent to [`lua_loadx`].
pub fn load(&mut self, chunk: &Chunk) -> Result<()> {
type State<'s> = Option<&'s [u8]>;
let mut state: State = Some(chunk.content.as_ref());
unsafe extern "C" fn read_cb(
_L: *mut lua_State,
state: *mut c_void,
size: *mut usize,
) -> *const c_char {
unsafe {
if let Some(chunk) = (*(state as *mut State)).take() {
*size = chunk.len();
chunk.as_ptr().cast()
} else {
*size = 0;
ptr::null()
}
}
}
let name = CString::new(chunk.name.to_vec())
.map_err(|err| Error::syntax(format!("invalid chunk name: {err}"), chunk.clone()))?;
let mode = chunk.mode.mode_str();
self.ensure(1);
match unsafe {
lua_loadx(
self.as_ptr(),
Some(read_cb),
&raw mut state as *mut c_void,
name.as_ptr(),
mode.as_ptr(),
)
} {
LUA_OK => Ok(()),
LUA_ERRMEM => {
self.pop(1);
Err(Error::memory())
}
LUA_ERRSYNTAX => {
let msg = self
.slot(-1)
.string()
.unwrap_or(b"unknown error".into())
.to_owned();
self.pop(1);
Err(Error::syntax(msg, chunk.clone()))
}
_ => unreachable!(),
}
}
/// Dumps the function at index `idx` into bytecode.
///
/// Equivalent to `string.dump(f, mode)`.
///
/// # Panics
///
/// Panics if the value at index `idx` is not a function.
pub fn dump(&self, idx: impl ToSlot, mode: DumpMode) -> Result<BString> {
let idx = assert_type!(self, idx, "function", Type::Function).index();
unsafe {
let mut s = self.guard_unchecked();
s.push("string");
s.get(PseudoIndex::Globals);
s.push("dump");
s.get(-2); // local dump = string.dump
s.push(idx);
s.push(mode.mode_str().to_bytes());
s.call(2, Some(1))?;
s.slot(-1).parse() // return dump(idx, mode)
}
}
/// Evaluates the given chunk on the stack synchronously with `narg` values at the top of the
/// stack as arguments.
///
/// Equivalent to calling [`load`](Self::load) on the chunk and then [`call`](Self::call) on the
/// loaded function.
///
/// # Panics
///
/// Panics if there are not enough values on the stack or thread status is invalid.
pub fn eval(&mut self, chunk: &Chunk, narg: u32, nret: Option<u32>) -> Result<u32> {
let base = assert_slots!(self, narg);
self.load(chunk)?;
self.pop_insert(base + 1);
self.call(narg, nret)
}
/// Calls a function on the stack synchronously with `narg` values at the top of the stack as
/// arguments.
///
/// There must be `narg + 1` values at the top of the stack, including the function to call at
/// the index `top - narg` (i.e. the function is pushed first and then `narg` values as
/// arguments). All arguments and the function are popped from the stack and then any return
/// values are pushed. If `nret` is not [`None`], then the number of return values pushed will
/// be exactly `nret`, filling with nils if necessary. Finally, the number of values pushed to
/// the stack is returned.
///
/// The current thread status must not be suspended or dead.
///
/// Equivalent to [`lua_pcall`].
///
/// # Panics
///
/// Panics if there are not enough values on the stack, the function to call is not on the
/// stack, or thread status is invalid.
pub fn call(&mut self, narg: u32, nret: Option<u32>) -> Result<u32> {
let base = match self.status() {
Status::Normal => {
// need the function on the stack
let base = assert_slots!(self, narg + 1);
assert_type!(self, base + 1, "function", Type::Function);
base
}
status => panic!("thread {self:p} called in wrong state: {status}"),
};
// TODO: use error handler to collect backtrace
match unsafe {
lua_pcall(
self.as_ptr(),
narg as c_int,
nret.map_or(LUA_MULTRET, |n| {
n.try_into().expect("too many return values")
}),
0,
)
} {
LUA_OK => Ok(self.size() - base),
LUA_ERRMEM => {
self.pop(1);
Err(Error::memory())
}
code => {
let msg = self
.slot(-1)
.string()
.unwrap_or(b"unknown error".into())
.to_owned();
self.pop(1);
Err(Error::call(ErrorKind::from_raw(code).unwrap(), msg, None))
}
}
}
/// Calls a function on the stack asynchronously with `narg` values at the top of the stack as
/// arguments.
///
/// There must be `narg + 1` values at the top of the stack, including the function to call at
/// the index `top - narg` (i.e. the function is pushed first and then `narg` values as
/// arguments). All arguments and the function are popped from the stack and then any return
/// values are pushed. If `nret` is not [`None`], then the number of return values pushed will
/// be exactly `nret`, filling with nils if necessary. Finally, the number values pushed to the
/// stack is returned.
///
/// If the thread yields a Rust [`Future`] value, then it will be polled to completion before
/// the thread is resumed with the output of the [`Future`] as the argument. If the thread
/// yields any other value, the thread is resumed immediately with no arguments.
///
/// The current thread status must not be suspended or dead.
///
/// Equivalent to multiple calls to [`lua_resume`] until the thread completes with a normal
/// result.
///
/// # Panics
///
/// Panics if there are not enough values on the stack, the function to call is not on the
/// stack, or thread status is invalid.
pub async fn call_async(&mut self, mut narg: u32, nret: Option<u32>) -> Result<u32> {
let base = match self.status() {
Status::Normal => {
// need the function on the stack
let base = assert_slots!(self, narg + 1);
assert_type!(self, base + 1, "function", Type::Function);
base
}
status => panic!("thread {self:p} called in wrong state: {status}"),
};
loop {
match self.resume(narg)? {
ResumeStatus::Ok => {
break Ok(match nret {
Some(n) => {
self.resize(base + n);
n
}
None => self.size() - base,
});
}
ResumeStatus::Suspended => unsafe {
narg = 0;
self.resize(1);
// SAFETY: Rust futures boxed in cdata payloads are never moved by the GC so we
// can safely make a Pin out of this pointer. See also comments in
// `luaffi::future::lua_future<T>`.
if let Some(fut) = self
.slot(1)
.cdata_mut::<lua_pollable>()
.map(|ptr| Pin::new_unchecked(ptr))
&& fut.is_valid()
{
fut.await;
}
},
}
}
}
/// Resumes the current thread with `narg` values on the stack as arguments.
///
/// If the current thread status is normal, then there must be `narg + 1` values at the top of
/// the stack, including the function to call at the index `top - narg` (i.e. the function is
/// pushed first and then `narg` values as arguments). If the current thread status is
/// suspended, then there must be `narg` values at the top of the stack. All arguments and the
/// function are popped from the stack and then any yielded values are pushed. Finally, the new
/// status of the thread indicating whether the thread had completed or suspended is returned.
///
/// The current thread status must not be dead.
///
/// Equivalent to [`lua_resume`].
///
/// # Panics
///
/// Panics if there are not enough values on the stack, the function to call is not on the
/// stack, or thread status is invalid.
pub fn resume(&mut self, narg: u32) -> Result<ResumeStatus> {
match self.status() {
Status::Normal => {
// need the function on the stack
let base = assert_slots!(self, narg + 1);
assert_type!(self, base + 1, "function", Type::Function);
base
}
Status::Suspended => assert_slots!(self, narg),
status => panic!("thread {self:p} resumed in wrong state: {status}"),
};
match unsafe { lua_resume(self.as_ptr(), narg as c_int) } {
LUA_OK => Ok(ResumeStatus::Ok),
LUA_YIELD => Ok(ResumeStatus::Suspended),
LUA_ERRMEM => {
self.pop(1);
Err(Error::memory())
}
code => {
let msg = self
.slot(-1)
.string()
.unwrap_or(b"unknown error".into())
.to_owned();
self.pop(1);
Err(Error::call(
ErrorKind::from_raw(code).unwrap(),
msg,
self.backtrace(0),
))
}
}
}
/// Captures a stack backtrace of the current thread.
///
/// This does not return any useful data unless the thread terminated with an error without
/// unwinding, which only happens when resuming a thread, or it is called inside the error
/// handler of a protected call. Both of these cases are already handled by this library
/// which automatically provides the backtrace with [`Error::trace`] if it is available.
///
/// Equivalent to [`luaL_traceback`].
pub fn backtrace(&self, level: u32) -> Option<BString> {
unsafe {
self.ensure(LUA_MINSTACK as u32);
luaL_traceback(
self.as_ptr(), // thread to push the trace onto
self.as_ptr(), // thread to trace
ptr::null(), // message prefixed to trace string
level.try_into().expect("invalid trace level"),
);
// SAFETY: must clone the trace string here before popping it off the stack
let trace = self
.slot(-1)
.string()
.map(|s| s.strip_prefix(b"stack traceback:\n").unwrap_or(s).as_bstr())
.filter(|s| !s.is_empty())
.map(|s| s.to_owned());
lua_pop(self.as_ptr(), 1);
trace
}
}
}
impl fmt::Debug for Stack {
fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
struct Slots<'s>(&'s Stack);
impl<'s> fmt::Debug for Slots<'s> {
fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
f.debug_list().entries(self.0.iter()).finish()
}
}
f.debug_struct("Stack")
.field("ptr", &self.0)
.field("size", &self.size())
.field("slots", &Slots(self))
.finish()
}
}
/// Guarded Lua stack handle.
///
/// This value resets the stack to the original size when dropped. This is useful for implementing
/// idempotent stack operations which must keep the stack size consistent.
///
/// Can be obtained by [`Stack::guard`].
#[derive(Debug)]
pub struct StackGuard<'s> {
parent: PhantomData<&'s mut Stack>,
stack: Stack,
base: u32,
check_overpop: bool,
}
impl<'s> StackGuard<'s> {
fn new(stack: &'s Stack, check_overpop: bool) -> Self {
Self {
parent: PhantomData,
stack: unsafe { Stack::new_unchecked(stack.as_ptr()) }, // SAFETY: stack.as_ptr() is never null
base: stack.size(),
check_overpop,
}
}
}
impl<'s> Deref for StackGuard<'s> {
type Target = Stack;
fn deref(&self) -> &Self::Target {
&self.stack
}
}
impl<'s> DerefMut for StackGuard<'s> {
fn deref_mut(&mut self) -> &mut Self::Target {
&mut self.stack
}
}
impl<'s> Drop for StackGuard<'s> {
fn drop(&mut self) {
if cfg!(debug_assertions) && self.check_overpop {
let new_size = self.stack.size();
assert!(
self.base <= new_size,
"StackGuard detected over-popping by {n} values (this is UB!!)",
n = self.base - new_size,
);
}
self.stack.resize(self.base);
}
}
/// Iterator over the values in a [`Stack`].
///
/// Can be obtained by [`Stack::iter`].
#[derive(Debug)]
pub struct StackIter<'s> {
stack: &'s Stack,
idx: u32,
size: u32,
}
impl<'s> StackIter<'s> {
fn new(stack: &'s Stack) -> Self {
Self {
stack,
idx: 0,
size: stack.size(),
}
}
}
impl<'s> Iterator for StackIter<'s> {
type Item = Slot<'s>;
fn next(&mut self) -> Option<Self::Item> {
(self.idx < self.size).then(|| {
self.idx += 1;
unsafe { self.stack.slot_unchecked(Index::stack(self.idx)) }
})
}
}
/// Index of a value in a [`Stack`].
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub enum Index {
/// Absolute stack index.
Stack(NonZero<u32>),
/// Upvalue index.
Upvalue(NonZero<u32>),
/// Pseudo-index.
Pseudo(PseudoIndex),
}
impl Index {
/// Creates a new absolute stack index.
///
/// # Panics
///
/// The index must be non-zero.
pub fn stack(idx: u32) -> Self {
Self::Stack(NonZero::new(idx).expect("stack index cannot be zero"))
}
/// Creates a new upvalue index.
///
/// # Panics
///
/// The index must be non-zero.
pub fn upvalue(idx: u32) -> Self {
Self::Upvalue(NonZero::new(idx).expect("upvalue index cannot be zero"))
}
/// Creates a new registry table pseudo-index.
pub fn registry() -> Self {
Self::Pseudo(PseudoIndex::Registry)
}
/// Creates a new environment table pseudo-index.
pub fn environment() -> Self {
Self::Pseudo(PseudoIndex::Environment)
}
/// Creates a new globals table pseudo-index.
pub fn globals() -> Self {
Self::Pseudo(PseudoIndex::Globals)
}
fn _from_raw(idx: c_int) -> Self {
match idx {
0 => panic!("index cannot be zero"),
idx if idx > 0 => Self::stack(idx as u32),
idx if idx < LUA_GLOBALSINDEX => Self::upvalue((LUA_GLOBALSINDEX - idx) as u32),
_ => match PseudoIndex::_from_raw(idx) {
Some(idx) => Self::Pseudo(idx),
None => panic!("invalid pseudo-index {idx}"),
},
}
}
fn into_raw(self) -> c_int {
match self {
Self::Stack(idx) => idx.get().try_into().expect("stack index overflow"),
Self::Upvalue(idx) => idx
.get()
.try_into()
.ok()
.and_then(|idx| LUA_GLOBALSINDEX.checked_sub(idx))
.expect("upvalue index overflow"),
Self::Pseudo(idx) => idx.into_raw(),
}
}
}
impl ops::Add<u32> for Index {
type Output = Index;
fn add(self, rhs: u32) -> Self::Output {
match self {
Self::Stack(idx) => {
Self::stack(idx.get().checked_add(rhs).expect("stack index overflow"))
}
Self::Upvalue(idx) => {
Self::upvalue(idx.get().checked_add(rhs).expect("upvalue index overflow"))
}
Self::Pseudo(idx) => panic!("cannot add offset to {idx} pseudo-index"),
}
}
}
impl ops::Sub<u32> for Index {
type Output = Index;
fn sub(self, rhs: u32) -> Self::Output {
match self {
Self::Stack(idx) => {
Self::stack(idx.get().checked_sub(rhs).expect("stack index underflow"))
}
Self::Upvalue(idx) => {
Self::upvalue(idx.get().checked_sub(rhs).expect("upvalue index underflow"))
}
Self::Pseudo(idx) => panic!("cannot subtract offset from {idx} pseudo-index"),
}
}
}
impl fmt::Display for Index {
fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
match self {
Self::Stack(idx) => write!(f, "stack#{idx}"),
Self::Upvalue(idx) => write!(f, "upvalue#{idx}"),
Self::Pseudo(idx) => write!(f, "{idx}"),
}
}
}
/// Pseudo-index in a [`Stack`].
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub enum PseudoIndex {
/// Registry table index.
Registry,
/// Environment table index.
Environment,
/// Globals table index.
Globals,
}
impl PseudoIndex {
fn _from_raw(idx: c_int) -> Option<Self> {
Some(match idx {
LUA_REGISTRYINDEX => Self::Registry,
LUA_ENVIRONINDEX => Self::Environment,
LUA_GLOBALSINDEX => Self::Globals,
_ => return None,
})
}
fn into_raw(self) -> c_int {
match self {
Self::Registry => LUA_REGISTRYINDEX,
Self::Environment => LUA_ENVIRONINDEX,
Self::Globals => LUA_GLOBALSINDEX,
}
}
}
impl fmt::Display for PseudoIndex {
fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
match self {
Self::Registry => write!(f, "registry"),
Self::Environment => write!(f, "environment"),
Self::Globals => write!(f, "globals"),
}
}
}
/// Lua value handle into the stack.
#[derive(Clone, Copy)]
pub struct Slot<'s> {
stack: &'s Stack,
idx: Index,
}
impl<'s> Slot<'s> {
unsafe fn new_unchecked(stack: &'s Stack, idx: Index) -> Self {
debug_assert!(
unsafe { lua_type(stack.as_ptr(), idx.into_raw()) != LUA_TNONE },
"invalid stack index {idx}: {stack:?}"
);
Self { stack, idx }
}
/// Index of this slot.
pub fn index(&self) -> Index {
self.idx
}
/// Type of the value in this slot.
pub fn ty(&self) -> Type {
Type::from_raw(unsafe { lua_type(self.stack.as_ptr(), self.idx.into_raw()) })
.unwrap_or(Type::Nil)
}
/// Parses the value in this slot as the type `T`.
pub fn parse<T: Parse<'s>>(&self) -> Result<T> {
T::parse(self)
}
/// Parses the value in this slot as a [`bool`].
///
/// If the value is not a `boolean`, then this returns false. `nil` is always considered false.
///
/// Equivalent to [`lua_toboolean`].
pub fn boolean(&self) -> bool {
self.parse().unwrap_or(false)
}
/// Parses the value in this slot as a `lightuserdata` pointer.
///
/// If the value is not a `lightuserdata`, then this returns a null pointer.
///
/// Equivalent to [`lua_touserdata`].
pub fn lightuserdata<T>(&self) -> *mut T {
(self.ty() == Type::Lightuserdata)
.then(|| self.parse().ok())
.flatten()
.unwrap_or(ptr::null_mut())
}
/// Parses the value in this slot as a [`lua_Number`].
///
/// If the value is not a `number` or a `string` that can be parsed as a number, then this
/// returns [`None`].
///
/// Equivalent to [`lua_tonumberx`].
pub fn number(&self) -> Option<lua_Number> {
self.parse().ok()
}
/// Parses the value in this slot as a [`lua_Integer`].
///
/// If the value is not a `number` or a `string` that can be parsed as an integer, then this
/// returns [`None`].
///
/// Equivalent to [`lua_tointegerx`].
pub fn integer(&self) -> Option<lua_Integer> {
self.parse().ok()
}
/// Parses the value in this slot as a binary string.
///
/// If the value is a `number`, then it is converted in-place into a `string` representation of
/// the value first.
///
/// If the value is not a `string`, then this returns [`None`].
///
/// Equivalent to [`lua_tolstring`].
pub fn string(&self) -> Option<&'s BStr> {
self.parse().ok()
}
/// Parses the value in this slot as a UTF-8 string.
///
/// If the value is a `number`, then it is converted in-place into a `string` representation
/// first.
///
/// Equivalent to [`lua_tolstring`].
pub fn string_utf8(&self) -> Option<&'s str> {
self.parse().ok()
}
/// Parses the value in this slot as a [`lua_CFunction`].
///
/// If the value is not a raw C function, then this returns [`None`].
///
/// Equivalent to [`lua_tocfunction`].
pub fn function_raw(&self) -> lua_CFunction {
unsafe { lua_tocfunction(self.stack.as_ptr(), self.idx.into_raw()) }
}
/// Parses the value in this slot as a `cdata` and returns an immutable reference to its
/// payload.
///
/// See [`cdata_ptr`](Self::cdata_ptr) regarding safety.
pub unsafe fn cdata<T>(&self) -> Option<&T> {
let ptr = self.cdata_ptr::<T>();
(!ptr.is_null()).then(|| unsafe { &*ptr })
}
/// Parses the value in this slot as a `cdata` and returns a mutable reference to its payload.
///
/// See [`cdata_ptr_mut`](Self::cdata_ptr_mut) regarding safety.
pub unsafe fn cdata_mut<T>(&self) -> Option<&mut T> {
let ptr = self.cdata_ptr_mut::<T>();
(!ptr.is_null()).then(|| unsafe { &mut *ptr })
}
/// Parses the value in this slot as a `cdata` and returns a mutable pointer to its payload.
///
/// If the value is a `cdata`, then the returned pointer is the address of the base of the its
/// payload. Otherwise, this returns a null pointer.
///
/// Nothing is done to ensure that the payload is of the type `T`. If only the pointer is needed
/// and not its payload, then it is recommended for `T` to be [`c_void`].
///
/// Refer to LuaJIT's [FFI semantics](https://luajit.org/ext_ffi_semantics.html) more
/// documentation regarding cdata objects.
///
/// Equivalent to [`lua_topointer`].
pub fn cdata_ptr<T>(&self) -> *const T {
(self.ty() == Type::Cdata)
.then(|| self.pointer().cast())
.unwrap_or(ptr::null_mut())
}
/// Parses the value in this slot as a `cdata` and returns a mutable pointer to its payload.
///
/// If the value is a `cdata`, then the returned pointer is the address of the base of the its
/// payload. Otherwise, this returns a null pointer.
///
/// Nothing is done to ensure that the payload is of the type `T`. If only the pointer is needed
/// and not its payload, then it is recommended for `T` to be [`c_void`].
///
/// Refer to LuaJIT's [FFI semantics](https://luajit.org/ext_ffi_semantics.html) more
/// documentation regarding cdata objects. In particular, reference cdata objects are immutable
/// after initialisation and must not be modified ("no re-seating of references").
///
/// Equivalent to [`lua_topointer`].
pub fn cdata_ptr_mut<T>(&self) -> *mut T {
self.cdata_ptr::<T>().cast_mut()
}
/// Parses the value in this slot as a generic pointer.
///
/// If the value is not a garbage-collected object that can be represented by a pointer (i.e. a
/// non-`nil` primitive value), then this returns a null pointer.
///
/// Equivalent to [`lua_topointer`].
pub fn pointer(&self) -> *const c_void {
unsafe { lua_topointer(self.stack.as_ptr(), self.idx.into_raw()).cast() }
}
/// Returns the length of the value in this slot.
///
/// For strings, this is the byte-length of the string. For tables, this is the length of the
/// table defined by the Lua `#` operator. For userdata, this is the size of its payload in
/// bytes. Otherwise, this returns 0.
///
/// This function does not invoke the `__len` metamethod.
///
/// Equivalent to [`lua_objlen`].
pub fn length(&self) -> usize {
matches!(self.ty(), Type::String | Type::Table | Type::Userdata)
.then(|| unsafe { lua_objlen(self.stack.as_ptr(), self.idx.into_raw()) })
.unwrap_or(0)
}
}
impl<'s> fmt::Debug for Slot<'s> {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
match self.ty() {
Type::Nil => write!(f, "nil"),
Type::Boolean => write!(f, "{}", self.boolean()),
Type::Number => write!(f, "{}", self.number().unwrap()),
Type::String => fmt::Debug::fmt(self.string().unwrap(), f),
ty => write!(f, "{ty} {:p}", self.pointer()),
}
}
}
/// Converts a value to a [`Slot`].
pub trait ToSlot {
/// Converts this value to a [`Slot`] on the given stack.
fn to_slot<'s>(&self, stack: &'s Stack) -> Slot<'s>;
}
impl<T> ToSlot for &T
where
T: ToSlot,
{
fn to_slot<'s>(&self, stack: &'s Stack) -> Slot<'s> {
(*self).to_slot(stack)
}
}
impl ToSlot for Slot<'_> {
fn to_slot<'s>(&self, stack: &'s Stack) -> Slot<'s> {
assert!(self.stack == stack);
unsafe { stack.slot_unchecked(self.idx) }
}
}
impl ToSlot for Index {
fn to_slot<'s>(&self, stack: &'s Stack) -> Slot<'s> {
match self {
Self::Pseudo(_) => {}
Self::Stack(idx) => {
assert!(
idx.get() <= stack.size(),
"stack underflow: expected at least {idx} values: {stack:?}"
);
}
Self::Upvalue(idx) => {
assert!(
unsafe { lua_type(stack.as_ptr(), self.into_raw()) != LUA_TNONE },
"stack underflow: expected at least {idx} upvalues"
);
}
}
unsafe { stack.slot_unchecked(*self) }
}
}
impl ToSlot for PseudoIndex {
fn to_slot<'s>(&self, stack: &'s Stack) -> Slot<'s> {
unsafe { stack.slot_unchecked(Index::Pseudo(*self)) }
}
}
impl ToSlot for u32 {
fn to_slot<'s>(&self, stack: &'s Stack) -> Slot<'s> {
stack.slot(Index::stack(*self))
}
}
impl ToSlot for i32 {
fn to_slot<'s>(&self, stack: &'s Stack) -> Slot<'s> {
let idx = *self;
if idx >= 0 {
return stack.slot(idx as u32);
}
let size = stack.size();
let offset = (-idx) as u32;
assert!(
offset <= size,
"stack underflow: expected at least {offset} values: {stack:?}"
);
unsafe { stack.slot_unchecked(Index::stack(size - offset + 1)) }
}
}
impl<'s> ops::Add<u32> for Slot<'s> {
type Output = Slot<'s>;
fn add(self, n: u32) -> Self::Output {
if n == 0 {
self
} else {
self.stack.slot(self.idx + n)
}
}
}
impl<'s> ops::Sub<u32> for Slot<'s> {
type Output = Slot<'s>;
fn sub(self, n: u32) -> Self::Output {
if n == 0 {
self
} else {
// SAFETY: subtracted index is guaranteed to be valid
unsafe { self.stack.slot_unchecked(self.idx - n) }
}
}
}
/// Pushes a value onto a [`Stack`].
///
/// This trait can be implemented by any type that can be reasonably converted to an equivalent Lua
/// value. Any type implementing this trait can be passed as an argument to [`Stack::push`].
pub trait Push {
/// Pushes this value to the given stack.
fn push(&self, stack: &mut Stack);
}
impl<T: Push> Push for &T {
fn push(&self, stack: &mut Stack) {
T::push(self, stack)
}
}
impl<T: Push> Push for &mut T {
fn push(&self, stack: &mut Stack) {
T::push(self, stack)
}
}
impl<T: Push> Push for Option<T> {
fn push(&self, stack: &mut Stack) {
match self {
Some(value) => value.push(stack),
None => ().push(stack),
}
}
}
impl Push for () {
fn push(&self, stack: &mut Stack) {
stack.ensure(1);
unsafe { lua_pushnil(stack.as_ptr()) }
}
}
impl Push for bool {
fn push(&self, stack: &mut Stack) {
stack.ensure(1);
unsafe { lua_pushboolean(stack.as_ptr(), *self as c_int) }
}
}
macro_rules! impl_push_ptr {
($type:ty) => {
impl<T> Push for $type {
fn push(&self, stack: &mut Stack) {
stack.ensure(1);
unsafe { lua_pushlightuserdata(stack.as_ptr(), *self as *mut c_void) }
}
}
};
}
impl_push_ptr!(*const T);
impl_push_ptr!(*mut T);
macro_rules! impl_push_num {
($type:ty) => {
impl Push for $type {
fn push(&self, stack: &mut Stack) {
stack.ensure(1);
unsafe { lua_pushnumber(stack.as_ptr(), *self as lua_Number) }
}
}
};
}
impl_push_num!(f32);
impl_push_num!(f64);
macro_rules! impl_push_int {
($type:ty) => {
impl Push for $type {
fn push(&self, stack: &mut Stack) {
stack.ensure(1);
unsafe { lua_pushinteger(stack.as_ptr(), *self as lua_Integer) }
}
}
};
}
impl_push_int!(u8);
impl_push_int!(u16);
impl_push_int!(u32);
impl_push_int!(u64);
impl_push_int!(usize);
impl_push_int!(i8);
impl_push_int!(i16);
impl_push_int!(i32);
impl_push_int!(i64);
impl_push_int!(isize);
macro_rules! impl_push_str {
($type:ty) => {
impl Push for $type {
fn push(&self, stack: &mut Stack) {
stack.ensure(1);
unsafe { lua_pushliteral(stack.as_ptr(), self) }
}
}
};
}
impl_push_str!(&[u8]);
impl_push_str!(Vec<u8>);
impl_push_str!(&BStr);
impl_push_str!(BString);
impl_push_str!(&str);
impl_push_str!(String);
impl Push for Ref {
fn push(&self, stack: &mut Stack) {
stack.ensure(1);
unsafe { lua_rawgeti(stack.as_ptr(), LUA_REGISTRYINDEX, self.key) }
}
}
impl Push for Index {
fn push(&self, stack: &mut Stack) {
match self {
Self::Pseudo(_) => {}
Self::Stack(idx) => {
assert!(
idx.get() <= stack.size(),
"stack underflow: expected at least {idx} values: {stack:?}"
);
}
Self::Upvalue(idx) => {
assert!(
unsafe { lua_type(stack.as_ptr(), self.into_raw()) != LUA_TNONE },
"stack underflow: expected at least {idx} upvalues"
)
}
}
stack.ensure(1);
unsafe { lua_pushvalue(stack.as_ptr(), self.into_raw()) };
}
}
impl Push for PseudoIndex {
fn push(&self, stack: &mut Stack) {
Index::Pseudo(*self).push(stack);
}
}
impl<'s> Push for Slot<'s> {
fn push(&self, stack: &mut Stack) {
assert!(self.stack == stack); // TODO: check global_State are equal and xmove instead
stack.ensure(1);
unsafe { lua_pushvalue(stack.as_ptr(), self.idx.into_raw()) };
}
}
/// [`Push`]es a new table onto a [`Stack`].
///
/// This value can be used as an argument to [`Stack::push`] to create a new empty table onto the
/// stack.
///
/// Equivalent to [`lua_createtable`].
#[derive(Debug, Default, Clone, Copy, Hash)]
pub struct NewTable {
/// Size of the preallocated array part.
pub narr: u32,
/// Size of the preallocated hash part.
pub nrec: u32,
}
impl NewTable {
/// Creates a new [`NewTable`] with no preallocations defined.
pub fn new() -> Self {
Self::sized(0, 0)
}
/// Creates a new [`NewTable`] with the array part set to preallocate `size`.
pub fn array(size: u32) -> Self {
Self::sized(size, 0)
}
/// Creates a new [`NewTable`] with the hash part set to preallocate `size`.
pub fn record(size: u32) -> Self {
Self::sized(0, size)
}
/// Creates a new [`NewTable`] with the array and hash parts set to preallocate `narr` and
/// `nrec` respectively.
pub fn sized(narr: u32, nrec: u32) -> Self {
Self { narr, nrec }
}
}
impl Push for NewTable {
fn push(&self, stack: &mut Stack) {
let Self { narr, nrec } = *self;
stack.ensure(1);
unsafe {
lua_createtable(
stack.as_ptr(),
narr.try_into().expect("table narr too big"),
nrec.try_into().expect("table nrec too big"),
)
}
}
}
/// Bare Rust function that can be called from Lua.
pub type BareFunction = fn(&mut Stack) -> c_int;
/// [`Push`]es a new function onto a [`Stack`].
#[derive(Debug, Clone, Copy, Hash)]
pub enum Function {
/// Bare Rust function.
Bare(BareFunction),
/// Raw C function.
Raw(lua_CFunction),
}
impl Push for Function {
fn push(&self, stack: &mut Stack) {
match *self {
Function::Bare(f) => unsafe {
unsafe extern "C" fn cb(L: *mut lua_State) -> c_int {
unsafe {
let mut stack = Stack::new_unchecked(L);
let f = mem::transmute::<*mut c_void, BareFunction>(
stack.slot(Index::upvalue(1)).lightuserdata(),
);
f(&mut stack)
}
}
stack.ensure(2);
lua_pushlightuserdata(stack.as_ptr(), f as *mut c_void);
lua_pushcclosure(stack.as_ptr(), Some(cb), 1);
},
Function::Raw(f) => unsafe {
assert!(f.is_some(), "raw function cannot be null");
stack.ensure(1);
lua_pushcfunction(stack.as_ptr(), f);
},
}
}
}
impl Push for BareFunction {
fn push(&self, stack: &mut Stack) {
Function::Bare(*self).push(stack);
}
}
/// [`Push`]es the current thread onto a [`Stack`].
///
/// This value can be used as an argument to [`Stack::push`] to push the current thread as a
/// `coroutine` object onto the stack.
///
/// Equivalent to [`lua_pushthread`].
#[derive(Debug, Default, Clone, Copy, Hash)]
pub struct CurrentThread;
impl Push for CurrentThread {
fn push(&self, stack: &mut Stack) {
stack.ensure(1);
unsafe { lua_pushthread(stack.as_ptr()) };
}
}
/// Parses a value on a [`Stack`].
///
/// This trait can be implemented by any type that can be reasonably converted from an equivalent
/// Lua value. Any type implementing this trait can be passed as a generic argument to
/// [`Slot::parse`].
pub trait Parse<'s>: Sized {
/// Parses the value in the given slot.
fn parse(slot: &Slot<'s>) -> Result<Self>;
}
impl Parse<'_> for () {
fn parse(slot: &Slot) -> Result<Self> {
match slot.ty() {
Type::Nil => Ok(()),
ty => Err(Error::invalid_type("nil", ty.name())),
}
}
}
impl Parse<'_> for bool {
fn parse(slot: &Slot) -> Result<Self> {
Ok(unsafe { lua_toboolean(slot.stack.as_ptr(), slot.index().into_raw()) != 0 })
}
}
macro_rules! impl_parse_ptr {
($type:ty) => {
impl<T> Parse<'_> for $type {
fn parse(slot: &Slot) -> Result<Self> {
let ptr = unsafe { lua_touserdata(slot.stack.as_ptr(), slot.index().into_raw()) };
if !ptr.is_null() {
Ok(ptr as $type)
} else {
Err(Error::invalid_type("userdata", slot.ty().name()))
}
}
}
};
}
impl_parse_ptr!(*mut T);
impl_parse_ptr!(*const T);
macro_rules! impl_parse_num {
($type:ty) => {
impl Parse<'_> for $type {
fn parse(slot: &Slot) -> Result<Self> {
let mut isnum = 0;
let n = unsafe {
lua_tonumberx(slot.stack.as_ptr(), slot.index().into_raw(), &raw mut isnum)
};
if isnum != 0 {
Ok(n as $type)
} else {
Err(Error::invalid_type("number", slot.ty().name()))
}
}
}
};
}
impl_parse_num!(f32);
impl_parse_num!(f64);
macro_rules! impl_parse_int {
($type:ty) => {
impl Parse<'_> for $type {
fn parse(slot: &Slot) -> Result<Self> {
let mut isnum = 0;
let n = unsafe {
lua_tointegerx(slot.stack.as_ptr(), slot.index().into_raw(), &raw mut isnum)
};
if isnum != 0 {
Ok(n as $type)
} else {
Err(Error::invalid_type("number", slot.ty().name()))
}
}
}
};
}
impl_parse_int!(u8);
impl_parse_int!(u16);
impl_parse_int!(u32);
impl_parse_int!(u64);
impl_parse_int!(usize);
impl_parse_int!(i8);
impl_parse_int!(i16);
impl_parse_int!(i32);
impl_parse_int!(i64);
impl_parse_int!(isize);
macro_rules! impl_parse_str {
($type:ty) => {
impl<'s> Parse<'s> for $type {
fn parse(slot: &Slot<'s>) -> Result<Self> {
let mut len = 0;
let ptr = unsafe {
lua_tolstring(slot.stack.as_ptr(), slot.index().into_raw(), &mut len)
};
if !ptr.is_null() {
Ok(unsafe { slice::from_raw_parts(ptr.cast(), len).into() })
} else {
Err(Error::invalid_type("string", slot.ty().name()))
}
}
}
};
}
macro_rules! impl_parse_str_utf8 {
($type:ty) => {
impl<'s> Parse<'s> for $type {
fn parse(slot: &Slot<'s>) -> Result<Self> {
Ok(std::str::from_utf8(Parse::parse(slot)?)
.map_err(Error::new)?
.into())
}
}
};
}
impl_parse_str!(&'s [u8]);
impl_parse_str!(&'s BStr);
impl_parse_str!(Vec<u8>);
impl_parse_str!(BString);
impl_parse_str_utf8!(&'s str);
impl_parse_str_utf8!(String);
Reference in New Issue View Git Blame Copy Permalink