From 3d28aff87197e5c78adaa46751eaaa15671d0c97 Mon Sep 17 00:00:00 2001 From: SD Asif Hossein Date: Mon, 19 Aug 2024 23:28:07 +0600 Subject: [PATCH] Notes on using Tracebacks and Pallene Tracer adoption --- doc/traceback.md | 39 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 39 insertions(+) create mode 100644 doc/traceback.md diff --git a/doc/traceback.md b/doc/traceback.md new file mode 100644 index 00000000..f7c65764 --- /dev/null +++ b/doc/traceback.md @@ -0,0 +1,39 @@ +

Tracebacks in Pallene

+ +For debugging purposes, function call tracing can be enabled. Pallene uses [Pallene Tracer](https://github.com/pallene-lang/pallene-tracer) to enable function stack-trace which can be generated in case of runtime errors. + +## How to Enable Function Call Tracing + +To enable function call tracing, simply pass the `--use-traceback` flag while compiling a Pallene translation. + +``` +pallenec foo.pln --use-traceback +``` + +## Generate Stack-trace + +Enabling function tracing in Pallene will only accumulate call-frames in Pallene Tracer call-stack, a separate self-maintained call-stack synchronous with Lua call-stack. To take advantage of the generated tracebacks, the Lua script has to be ran using Pallene Tracer Lua frontend, `pt-lua`. + +``` +pt-lua main.lua args ... +``` + +## Adoption of Pallene Tracer in Pallene + +To know about how Pallene Tracer works, refer to the [documentation](https://github.com/pallene-lang/pallene-tracer/tree/main/docs/MANUAL.md). + +Pallene uses custom set of macros as Pallene is AOT compiled to C from a different source. These macros are defined in at the very beginning of `pallenelib.lua` under Pallene source tree. + +Pallene uses the Dispatch mechanism mentioned in the Pallene Tracer docs. Therefore, all Lua entry point function dispatches to respective Pallene entry point function (C interface function). + +These macros are adopted to each and every compiled \[to C\] function depending on the entry point type. The `PALLENE_LUA_FRAMEENTER` is used at the beginning of the each Lua entry point function, pushing a Lua entry point call-frame. Lua entry point functions do not require FRAMEEXIT. + +The Pallene/C entry point function on the other hand, has to maintain proper FRAMEENTER and FRAMEEXIT, at the beginning of the function and prior to return statement respectively by calling `PALLENE_C_FRAMEENTER` and `PALLENE_FRAMEEXIT` respectively. The Pallene entry point functions has to utilize the `PALLENE_SETLINE` macro to properly set line numbers prior calling a new function or invoking Lua runtime error. + +The macros were properly generated by making changes to `lua_entry_point_definition` and `pallene_entry_point_definition` functions respectively in `coder.lua`, also ensuring proper FRAMEEXIT at the end in case of void Pallene entry points. + +The `PALLENE_SETLINE` macro was adopted by changing the code generator of `CallStatic` and `CallDyn` IR case, which should allow proper call of `PALLENE_SETLINE` prior Pallene -> Pallene or Pallene -> Lua function calls. The macro is also used accordingly in case of invoking runtime errors. + +The Pallene Tracer call-stack and to-be-closed finalizer object is passed through the Pallene Full-userdata global, which is then enclosed to Lua entry point functions as Upvalues. The call-stack passed to Pallene entry points upon dispatch. Pallene entry points do not need to utilize the finalizer object. + +The `--use-traceback` flag is parsed in `pallenec.lua` and passed to the Code Generation compiler pass via `flags` table. The flags table then stored as a property in Coder class. When function traceback is enabled through `--use-traceback` flag, the `use_traceback` field is set to `true` in flags table, which is then used to increase the argument numbers in arity check (because of to-be-closed finalizer object is pushed onto the value-stack upon FRAMEENTER) and to define `PT_DEBUG` macro to enable debug mode in Pallene Tracer. \ No newline at end of file