DOCSEARCHbyAlgolia
Submit Docs

LuaJava

repository·main·Indexed 42 days ago

https://github.com/gudzpoz/luajava

A scripting tool for seamless integration between Java and Lua, allowing Lua scripts to manipulate Java components and implement Java interfaces. Version 4.1.0 provides a hybrid Java/JNI architecture with specialized userdata types (jclass, jobject, jarray) and a core 'java' module for importing classes, constructing objects, and handling Java exceptions.

Tokens
15.2K
Snippets
41
Records
89
Agent score
54%

What's inside LuaJava

  1. What is LuaJava?

    main

    LuaJava is a scripting tool for Java that enables Lua scripts to manipulate Java components.

    Key capabilities:

    • Direct Access: Java components can be accessed from Lua using standard Lua syntax without declarations or preprocessing.
    • Interface Implementation: Any Java interface can be implemented in Lua and passed as a parameter to Java methods. When the Java method calls the interface, the corresponding Lua function is executed, and the result is passed back to Java.
    • Licensing: Available under the same license as Lua 5.1 (MIT-style), allowing free use for both academic and commercial purposes.

  2. Understand Java-to-Lua call costs

    main

    Calling Lua functions from Java involves JNI (Java Native Interface) overhead. The bare minimum operation involves L.getGlobal("f") to push a function onto the stack and L.pcall(0, 0) to execute it.

    Key performance considerations:

    • JNI Overhead: Java JNI costs are approximately 2x to 3x higher than pure C calls.
    • Argument Scaling: The cost increases with the number of arguments, as every argument requires an additional JNI call to pass it from Java to Lua.

  3. Choose between LuaJava's API sets

    main

    LuaJava provides two distinct ways to interact with Lua from Java:

    1. Lua C API Wrapper: A thin wrapper around the Lua C API. Most API names are converted to CamelCase with the lua_ or luaL_ prefixes removed. This requires familiarity with the Lua C API.
      • If the standard wrapper is insufficient, you can access the bindings directly via Lua#getLuaNatives.
    2. Java-ish API: A higher-level API designed for Java developers that requires significantly less knowledge of Lua internals. See the Java API guide for details.

  4. Understand the LuaJava Code Architecture

    main

    LuaJava uses a hybrid Java/JNI architecture to bridge the JVM with various Lua versions. The system relies on jnigen to generate JNI artifacts.

    Java Layer

    • party.iroiro.luajava: The primary Java API package located in luajava/.
    • LuaNative: An abstract class that defines the Lua C API common to all versions. Each Lua version (5.1, 5.2, etc.) provides a concrete implementation of this class.
    • JuaAPI: Contains methods primarily used by the JNI C++ side.
    • Version-specific implementations: Located in lua<version>/, these classes (e.g., Lua51Natives.java) contain boilerplate JNI code. jnigen extracts C code from these files to generate the actual C++ files used for compilation.

    JNI C++ Layer

    • Entry Point: The initBindings function in jni/luajava/jua.cpp initializes variables for JVM interop.
    • Metatables: When the Java side requests a global Lua state, initMetaRegistry (in jua.cpp) is executed to set up necessary metatables.

  5. LuaJava Module Structure and JPMS Compatibility

    main

    LuaJava is designed to work with the Java Platform Module System using automatic modules and unnamed modules:

    1. party.iroiro.luajava: An automatic module wrapping the party.iroiro.luajava:luajava artifact.
    2. party.iroiro.luajava.lua*: Automatic modules wrapping the Java-side bindings for specific Lua binaries.
    3. Native Binaries: The native binary JARs are placed in the unnamed module.

  6. Thread safety in LuaJava

    main

    LuaJava does not guarantee thread safety for a single Lua state. However, you can safely access a Lua state across multiple OS threads if you implement external synchronization.

    There are two primary ways to handle concurrency:

    1. Use multiple Lua main states: If each OS thread uses its own dedicated Lua main state, no synchronization is required.
    2. Synchronize on the main state: If multiple threads must access the same Lua main state, you must use synchronized blocks to prevent concurrent access. This applies to both direct calls to party.iroiro.luajava.Lua methods and calls to methods on proxied objects (which trigger underlying Lua functions).

  7. Java 8 usage constraints in LuaJava

    main

    Due to Android compatibility requirements, there are strict rules regarding Java 8 features:

    • Main Codebase: Do not use Java 8 features (such as default methods in interfaces or lambda functions). Requiring users to set up desugaring is considered too high a barrier.
    • Test Code: Using Java 8 lambdas, default functions, etc., is acceptable within the test environment as the build configuration allows it.

  8. Understand Proxied Method Calls and Overloading

    main

    LuaJava proxies Java method calls by treating missing fields on a jobject as potential method calls. Because Java supports method overloading, the resolution of which method to call happens only after parameters are supplied.

    Important Behaviors:

    • Missing Fields: A missing field on a jobject is never nil; it is treated as a possible function call. Do not rely on type(obj.missing_field) == 'function' for logic.
    • Resolution Process: LuaJava iterates through available methods and attempts to convert Lua stack values to the required Java types. The first method that allows successful conversion is executed.
    • No Prioritization: There is no priority for specific overloads. For example, if calling java.lang.Math.max, you cannot guarantee whether the int, int or double, double version will be called based on standard syntax alone.
    • Varargs Support: Standard Java varargs are not supported directly. To simulate varargs, you must combine java.method and java.array.

  9. Understand Lua-to-Java call costs

    main

    Calling Java methods from Lua is generally slower than Java-to-Lua calls because Lua is dynamic while Java requires static argument types. The system must perform lookups to match the dynamic Lua call to a static Java method.

    Optimization techniques:

    • Use java.method: To reduce dynamic lookup overhead, use java.method to look up methods using user-provided signatures. This speeds up the call process.
    • LuaJ Performance: In scenarios with heavy cross-language boundaries, LuaJ may perform better than LuaJIT because LuaJ is implemented entirely in Java, allowing the JVM to use method inlining and avoiding JNI costs.

  10. The LuaValue interface

    main
    The party.iroiro.luajava.value.LuaValue interface is a wrapper around a Lua value. For complex values like Lua tables, it uses references to the Lua value, which are garbage collected once the LuaValue instance becomes a phantom reference.

  11. Performance comparison of Lua engines

    main

    Performance varies significantly depending on whether the workload is pure Lua or involves frequent cross-language (JNI) boundaries.

    • Pure Lua: LuaJIT is typically the fastest for pure Lua logic (e.g., heavy loops and biased branching).
    • JNI-Heavy Workloads: LuaJ can be surprisingly more performant than LuaJIT because it avoids JNI overhead and benefits from JVM inlining.
    • LuaJIT Limitations: LuaJIT cannot optimize across the C/Lua boundary, so its performance advantage diminishes when JNI calls are frequent.

  12. Use the `Lua` interface for stack-based operations

    main

    The party.iroiro.luajava.Lua interface is a Java wrapper around the lua_State pointer. It provides access to common parts of the Lua C APIs (Lua 5.1 ~ 5.4 and LuaJIT).

    Important Mental Model: The Lua API is stack-based. Most operations require you to push values onto the Lua stack before performing actions like assigning to globals or querying tables. While this interface is available, it is generally recommended to use the higher-level LuaValue API instead.

    // Note: Use the LuaValue API for most tasks. Use the Lua interface for stack-based C-style operations.