GSoC 24 - Final Report.md

Google Summer of Code 2024 : LabLua - Final Report

Project Title: Adapt LuaSQL drivers to Lua 5.4

Project Goal

The primary objective of this project was to adapt LuaSQL drivers to Lua 5.4. This involved addressing the Incompatibilities introduced in Lua 5.4, Implementing new changes suitable for LuaSQL, updating the documentation and Improving the Test suite.

• Project Milestones
  • 1. Resolving Incompatibilities
  • 2. Adaptation of Drivers to To-be-closed variables
  • 3. Refactor Resource cleanup methods
  • 4. Documentation Update

This report highlights the key accomplishments and contributions made during my participation in Google Summer of Code 2024 for the LabLua organization and the LuaSQL Project.

Project Milestones

1. Resolving Incompatibilities - PR Link

• Resolved an incompatibility between LuaSQL drivers and Lua 5.4, addressing key API changes introduced in the new Lua version.
• Replaced the lua_newuserdata with lua_newuserdatauv API, which has an extra argument for user values.
• Introduced the LUASQL_NEWUD macro to have a version check and abstract these differences, it handles version-agnostic userdata creation for different Lua versions in all the drivers.

2. Adaptation of Drivers to To-be-closed variables - PR Link

Lua 5.4 introduced To-be-closed variables, a mechanism to free memory or otherwise release resources when the variable goes out of scope due to any reason. To do so, two requirements must be met:

1. The underlying userdata value must have a __close metamethod.
2. The Lua program must annotate a variable as to-be-closed.
   

• LuaSQL drivers had only 2 methods for Resouce cleanup - :close() and __gc, the __close method was absent. Thus the actual implementation did not provide the method that allow the correct implementation of functionality of To-be-closed variables.
• Added the missing __close metamethod for environment, connection and cursor objects.
• Added Test-suite to test the to-be-closed support of LuaSQL Drivers.
• Bug-fix : Checking Names and Types of variables ignoring case in the test-script.

3. Refactor Resource cleanup methods - PR Link

During driver testing, a bug was identified where the :close() method was, in some cases, inadvertently triggering the __gc (garbage collector) metamethod. The __gc method would then check for open cursors and, instead of closing the connection, would throw an error. This behavior is incorrect because the :close() method should only be invoked by the programmer, while the Lua interpreter is responsible for invoking the __close and __gc methods. However, in this scenario, the programmer was indirectly able to trigger the __gc method. Thus, Standardized the implementation of all drivers to make all of them behave the same and separate those invocations.

• Updated the __close metamethods of LuaSQL objects with their respective __gc methods.
• Enhancement : The :close() method now returns false and a string with appropriate message instead of raising an error when there are related open objects.
• :close() method does not invoke the __gc metamethod in case of related open objects.
• Update : The __gc method no longer checks for the open object counter as it should only be concerned with garbage collection, not object state. (Incase of SQLite and SQLite3 driver)

4. Documentation Update - PR Link

• Added a new section detailing the use of To-be-closed objects in LuaSQL along with an example.
• :close() Method Return Types : Updated the documentation to accurately reflect the return type of the :close() methods across all the objects.