API Redesign

[gudzpoz]

closes #169

Planned Changes

• Throw Lua-side errors as Java exceptions.
  • Decide whether they should be checked exceptions.
    Probably not I guess?
• LuaValue improvements.
  • Map interface implementation for tables.
  • toProxy().
  • Conversions and calls.
  • Remove the deprecated LuaValue#close and delegate the job fully to cleaners/finalizers.
  • Add LuaFunction to simplify JFunction usages.
  • Rename LuaThread::execute to eval to match JSR223 naming.
• Lua interface improvements:
  • Global value manipulation API (implementing a LuaThread interface, similar to a LuaValue table).
• LuaNative clean up.
  • Check LuaJNatives for more useless functions present in the LuaNative interface.
    • Some Lua C API functions are common between Lua versions, for example, luaL_gsub. Our bindings are mostly programmatically generated and include these functions. However, luaL_gsub is just doing C string substitution (no, it does not involve any Lua) and should be safe to remove.
    • luaL_gsub.
    • luaJ_pcall.
    • luaJ_metatable.
  • Make C APIs in LuaNatives public.
• Rename java.catched to java.caught.
• Improve test coverage (a 96% should be good to go).
• Update documentation.
• [-] Release.

Non-API Changes

• Upgrade Gradle & Android Gradle Plugin to allow desugaring and using Java 8 features in tests.
• Fix LuaJ coroutine deadlocks.

[gudzpoz]

After adding more tests, LuaJ's approach to coroutines (by using OS threads) turns out to be problematic: it can deadlock.

In PUC-Rio Lua, all operations are executed a single thread:

synchronized @<thread-1> {
  lua calls another coroutine {
    lua access proxy objects {
      synchronized @<thread-1> { // luajava proxies synchronizes to ensure thread safety
        operations can be done since it it fine to nest sync-scopes in the same thread
      }
    }
  }
}

However, LuaJ uses OS threads for coroutines:

synchronized @<thread-1> {
  lua calls another coroutine {
    here is @<thread-2> !!!
    lua access proxy objects {
      synchronized @<thread-2> { // deadlock here
        unreachable~
      }
    }
  }
}

However, after looking into the implementation of LuaThread in LuaJ, it actually seems possible to re-implement coroutines with a single-threaded executor. No, it's not.

Fixed in 46ea2c3 (#171) and a24b929 (#171) .

[codecov-commenter]

Codecov Report

Attention: Patch coverage is 99.69605% with 1 lines in your changes are missing coverage. Please review.

Project coverage is 96.55%. Comparing base (f6872e0) to head (09596f4).
Report is 1 commits behind head on main.

Files	Patch %	Lines
...in/java/party/iroiro/luajava/luaj/LuaJNatives.java	90.90%	0 Missing and 1 partial ⚠️

❗ Your organization needs to install the Codecov GitHub app to enable full functionality.

Additional details and impacted files

@@             Coverage Diff              @@
##               main     #171      +/-   ##
============================================
+ Coverage     92.73%   96.55%   +3.81%     
- Complexity      847      912      +65     
============================================
  Files            43       44       +1     
  Lines          2368     2465      +97     
  Branches        281      286       +5     
============================================
+ Hits           2196     2380     +184     
+ Misses          125       61      -64     
+ Partials         47       24      -23     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.