API Redesign

[gudzpoz]

closes #169

Planned Changes

• [X] Throw Lua-side errors as Java exceptions.
  • [X] Decide whether they should be checked exceptions. Probably not I guess?
• [X] LuaValue improvements.
  • [X] Map interface implementation for tables.
  • [X] toProxy().
  • [X] Conversions and calls.
  • [X] Remove the deprecated LuaValue#close and delegate the job fully to cleaners/finalizers.
  • [X] Add LuaFunction to simplify JFunction usages.
  • [X] Rename LuaThread::execute to eval to match JSR223 naming.
• [X] Lua interface improvements:
  • [X] Global value manipulation API (implementing a LuaThread interface, similar to a LuaValue table).
• [X] LuaNative clean up.
  • [X] 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.
  • [X] luaL_gsub.
  • [X] luaJ_pcall.
  • [X] luaJ_metatable.
  • [X] Make C APIs in LuaNatives public.
• [X] Rename java.catched to java.caught.
• [X] Improve test coverage (a 96% should be good to go).
• [X] Update documentation.
• [-] Release.

Non-API Changes

• [X] Upgrade Gradle & Android Gradle Plugin to allow desugaring and using Java 8 features in tests.
• [X] 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 :warning:

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

Additional details and impacted files

```diff @@ 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 ```

:umbrella: View full report in Codecov by Sentry.
:loudspeaker: Have feedback on the report? Share it here.