Lua C API

Lua C API
Name	Lua C API
Developer	Roberto Ierusalimschy, Luiz Henrique de Figueiredo, Waldemar Celes
Initial release	1993
Written in	C (programming language)
Operating system	Cross-platform software
License	MIT License
Website	Lua (programming language)

Lua C API

The Lua C API is the official foreign-function interface between the Lua (programming language) interpreter and programs written in C (programming language), enabling embedding and extending the Lua (programming language) runtime in host applications such as Nginx, Redis, and World of Warcraft. It provides a small, stack-based ABI for manipulating Lua values, registering C functions, and controlling the Lua (programming language) garbage collector; authors such as Roberto Ierusalimschy documented the design alongside implementations in projects like LuaJIT and integrations in engines such as Unreal Engine and Unity (game engine).

Overview

The API exposes a procedural interface implemented in C (programming language) that uses a virtual stack to pass values between host code and the Lua (programming language) interpreter, similar in intent to other embedding interfaces like the Python/C API, the Java Native Interface, and the .NET Framework interop layers. Core concepts include the Lua (programming language) state (lua_State), metamethods modeled after Object-oriented programming patterns in languages like Smalltalk and C++, and a registry mechanism resembling the global registries used in Redis modules and PostgreSQL extensions. The API design influenced scripting integrations in projects such as Blender, GIMP, Apache HTTP Server, and the LuaRocks package manager ecosystem.

Stack and Data Types

The stack exposes typed slots manipulated with functions that mirror typed operations found in C (programming language) runtimes and the POSIX standard: push, pop, index, and type queries. Supported Lua types correspond to nodes in the Abstract syntax tree of the interpreter: nil, boolean, number, string, table, function, userdata, thread, and lightuserdata; analogous typed interfaces occur in the JavaScript engine embedding APIs and the V8 (JavaScript engine) C++ API. The API provides conversion routines between host numeric types like IEEE 754 doubles and integer types used in systems such as x86-64 and ARM architectures, and uses metatables that echo design patterns from Prototype-based programming seen in Self (programming language).

Calling Lua from C

Calling Lua code from C uses the stack to load chunks, push arguments, and call functions with protected variants that mirror POSIX-style error handling. Typical operations include loading bytecode compiled by tools similar to LuaRocks or compilers like luac, setting up environments similar to chroot-style isolation, and invoking coroutines comparable to constructs in Erlang or Go (programming language). The API supports creating and resuming threads (coroutines) akin to Fibers (computer science) and cooperative multitasking frameworks such as those used in Game development frameworks like Godot Engine and CryEngine.

Calling C from Lua

Embedding C functions into Lua requires registering C-callable wrappers that conform to the expected stack discipline; this model resembles native extensions in Node.js, the Python (programming language) C-API, and the Ruby (programming language) C-extension interface used by projects like Rails. The API enables creation of userdata with metatables to represent opaque host resources similar to POSIX threads or OpenGL contexts used in Blender and GIMP plugins, and allows use of lightuserdata for simple pointer passing as in MySQL client extensions and SQLite virtual tables.

Error Handling and Memory Management

Error handling uses longjmp-style protected calls via APIs that provide stack traces and message handler hooks comparable to the setjmp/longjmp pattern in C (programming language) and structured exception interfaces in Windows API and POSIX. Memory management is coordinated with the Lua garbage collector, configurable through APIs similar to memory allocators in glibc and custom allocators seen in Redis and Nginx modules; integration points allow applications to supply custom allocators paralleling strategies used in jemalloc and tcmalloc. Finalizer semantics for userdata resemble destructors in C++ and finalizers in Java (programming language), and debugging integrations can leverage tools like Valgrind and profilers used with Perf (Linux).

Performance and Best Practices

Performance considerations echo those in high-performance systems such as LuaJIT, V8 (JavaScript engine), and native module systems like Node.js addons: minimize allocations, cache stack indices, avoid repeated metamethod lookups, and prefer lightuserdata or upvalues for frequent callbacks. Use of buffering patterns familiar from ZeroMQ, batching analogous to SQL prepared statements, and memory pools used in Apache HTTP Server modules can reduce overhead. Benchmarking strategies employ suites and harnesses inspired by SPEC and continuous integration practices used in projects like GitLab and Travis CI.

Examples and Use Cases

Common use cases include embedding in game engines such as Unreal Engine, Unity (game engine), and Godot Engine for scripting gameplay; server-side extensions in Nginx and Redis modules for request handling; automation plugins in Blender, GIMP, and Wireshark; and sandboxed scripting in applications like Adobe Photoshop-style plugins and scientific tools used alongside NumPy-based workflows. Example patterns—registering modules, exposing C structs as userdata, using coroutines for asynchronous workflows—are employed in projects like luacheck, LuaRocks, luvit, and OpenResty.

Category:Application programming interfaces