Skip to content

Commit ba30fc2

Browse files
gilzoidegilzoide
authored
Merge pull request #104 from gilzoide/lua-thread-hook-event
Move HookEvent enum to LuaThread class
2 parents 3cb753b + e49f68c commit ba30fc2

File tree

7 files changed

+190
-20
lines changed

7 files changed

+190
-20
lines changed

‎doc_classes/LuaDebug.xml‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
<?xml version="1.0" encoding="UTF-8" ?>
2+
<class name="LuaDebug" inherits="RefCounted" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/godotengine/godot/master/doc/class.xsd">
3+
<brief_description>
4+
A structure used to carry different pieces of information about a Lua function or an activation record.
5+
</brief_description>
6+
<description>
7+
See [url]https://www.lua.org/manual/5.4/manual.html#lua_Debug[/url].
8+
</description>
9+
<tutorials>
10+
</tutorials>
11+
<methods>
12+
<method name="is_tail_call" qualifiers="const">
13+
<return type="bool" />
14+
<description>
15+
Returns [code]true[/code] if this function invocation was called by a tail call. In this case, the caller of this level is not in the stack.
16+
</description>
17+
</method>
18+
<method name="is_vararg" qualifiers="const">
19+
<return type="bool" />
20+
<description>
21+
Returns [code]true[/code] if the function is a variadic function (always true for C functions).
22+
</description>
23+
</method>
24+
</methods>
25+
<members>
26+
<member name="current_line" type="int" setter="" getter="get_current_line">
27+
The current line where the given function is executing. When no line information is available, current_line is set to -1.
28+
</member>
29+
<member name="event" type="int" setter="" getter="get_event" enum="LuaThread.HookEvent">
30+
Hook event that generated this activation record. Only meaningful during hooks.
31+
</member>
32+
<member name="last_line_defined" type="int" setter="" getter="get_last_line_defined">
33+
The line number where the definition of the function ends.
34+
</member>
35+
<member name="line_defined" type="int" setter="" getter="get_line_defined">
36+
The line number where the definition of the function starts.
37+
</member>
38+
<member name="name" type="String" setter="" getter="get_name">
39+
A reasonable name for the given function. Because functions in Lua are first-class values, they do not have a fixed name: some functions can be the value of multiple global variables, while others can be stored only in a table field. If Lua cannot find a name, then name is empty.
40+
</member>
41+
<member name="name_what" type="String" setter="" getter="get_name_what">
42+
Explains the name field. The value of name_what can be "global", "local", "method", "field", "upvalue", or "" (the empty string), according to how the function was called. (Lua uses the empty string when no other option seems to apply.)
43+
</member>
44+
<member name="nparams" type="int" setter="" getter="get_nparams">
45+
The number of parameters of the function (always 0 for C functions).
46+
</member>
47+
<member name="short_src" type="String" setter="" getter="get_short_src">
48+
A "printable" version of source, to be used in error messages.
49+
</member>
50+
<member name="source" type="String" setter="" getter="get_source">
51+
The source of the chunk that created the function. If source starts with a '@', it means that the function was defined in a file where the file name follows the '@'. If source starts with a '=', the remainder of its contents describes the source in a user-dependent manner. Otherwise, the function was defined in a string where source is that string.
52+
</member>
53+
<member name="what" type="String" setter="" getter="get_what">
54+
The string "Lua" if the function is a Lua function, "C" if it is a C function, "main" if it is the main part of a chunk.
55+
</member>
56+
</members>
57+
</class>

‎doc_classes/LuaFunction.xml‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,12 @@
1010
<tutorials>
1111
</tutorials>
1212
<methods>
13+
<method name="get_debug_info" qualifiers="const">
14+
<return type="LuaDebug" />
15+
<description>
16+
Get the debug information available about this function.
17+
</description>
18+
</method>
1319
<method name="invoke" qualifiers="const vararg">
1420
<return type="Variant" />
1521
<description>

‎doc_classes/LuaThread.xml‎

Lines changed: 105 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,13 +10,86 @@
1010
<tutorials>
1111
</tutorials>
1212
<methods>
13+
<method name="get_hook" qualifiers="const">
14+
<return type="Variant" />
15+
<description>
16+
Returns the current hook function.
17+
See [method set_hook].
18+
</description>
19+
</method>
20+
<method name="get_hook_count" qualifiers="const">
21+
<return type="int" />
22+
<description>
23+
Returns the current hook count.
24+
See [method set_hook].
25+
</description>
26+
</method>
27+
<method name="get_hook_mask" qualifiers="const">
28+
<return type="int" enum="LuaThread.HookMask" is_bitfield="true" />
29+
<description>
30+
Returns the current hook mask.
31+
See [method set_hook].
32+
</description>
33+
</method>
34+
<method name="get_stack_info" qualifiers="const">
35+
<return type="LuaDebug[]" />
36+
<description>
37+
Get debug information about the stack of this thread of execution.
38+
</description>
39+
</method>
40+
<method name="get_stack_level_info" qualifiers="const">
41+
<return type="LuaDebug" />
42+
<param index="0" name="level" type="int" />
43+
<description>
44+
Get debug information about the activation record of the function executing at a given [param level].
45+
Level 0 is the current running function, whereas level n+1 is the function that has called level n (except for tail calls, which do not count in the stack).
46+
When called with a level greater than the stack depth, returns [code]null[/code].
47+
</description>
48+
</method>
49+
<method name="get_traceback" qualifiers="const">
50+
<return type="String" />
51+
<param index="0" name="message" type="String" default="&quot;&quot;" />
52+
<param index="1" name="level" type="int" default="0" />
53+
<description>
54+
Returns a traceback of the stack.
55+
[param message] is appended at the beginning of the traceback.
56+
[param level] tells at which level to start the traceback.
57+
</description>
58+
</method>
1359
<method name="is_main_thread" qualifiers="const">
1460
<return type="bool" />
1561
<description>
1662
Whether this thread is the [LuaState]'s main thread.
1763
See also [member LuaState.main_thread].
1864
</description>
1965
</method>
66+
<method name="set_hook">
67+
<return type="void" />
68+
<param index="0" name="hook" type="Variant" />
69+
<param index="1" name="mask" type="int" enum="LuaThread.HookMask" is_bitfield="true" />
70+
<param index="2" name="count" type="int" default="0" />
71+
<description>
72+
Sets the debugging hook function.
73+
[param hook] is the Hook function, which should be either a [Callable] or [LuaFunction]. Pass [code]null[/code] to disable hooks.
74+
[param mask] specifies on which events the hook will be called: it is formed by a bitwise OR of the constants [constant HOOK_MASK_CALL], [constant HOOK_MASK_RETURN], [constant HOOK_MASK_LINE] and [constant HOOK_MASK_COUNT]. Pass 0 to disable hooks.
75+
[param count] is only meaningful when the mask includes [constant HOOK_MASK_COUNT].
76+
See [enum HookEvent] for the available hook events.
77+
See also [url]https://www.lua.org/manual/5.4/manual.html#lua_sethook[/url].
78+
[codeblocks]
79+
[gdscript]
80+
var line_hook := func(ar: LuaDebug): prints("Running line: ", ar.current_line)
81+
var state := LuaState.new()
82+
state.main_thread.set_hook(line_hook, LuaThread.HOOK_MASK_LINE)
83+
# The line hook will be called once for each line of Lua code
84+
state.do_string("""
85+
local line1 = 1
86+
local line2 = 2
87+
local line3 = 3
88+
""")
89+
[/gdscript]
90+
[/codeblocks]
91+
</description>
92+
</method>
2093
</methods>
2194
<members>
2295
<member name="status" type="int" setter="" getter="get_status" enum="LuaThread.Status">
@@ -45,5 +118,37 @@
45118
<constant name="STATUS_DEAD" value="-1" enum="Status">
46119
The thread has finished execution.
47120
</constant>
121+
<constant name="HOOK_MASK_CALL" value="1" enum="HookMask" is_bitfield="true">
122+
Mask passed to [method set_hook] to subscribe to [constant HOOK_EVENT_CALL] and [constant HOOK_EVENT_TAIL_CALL] hooks.
123+
</constant>
124+
<constant name="HOOK_MASK_RETURN" value="2" enum="HookMask" is_bitfield="true">
125+
Mask passed to [method set_hook] to subscribe to [constant HOOK_EVENT_RETURN] hooks.
126+
</constant>
127+
<constant name="HOOK_MASK_LINE" value="4" enum="HookMask" is_bitfield="true">
128+
Mask passed to [method set_hook] to subscribe to [constant HOOK_EVENT_LINE] hooks.
129+
</constant>
130+
<constant name="HOOK_MASK_COUNT" value="8" enum="HookMask" is_bitfield="true">
131+
Mask passed to [method set_hook] to subscribe to [constant HOOK_EVENT_COUNT] hooks.
132+
</constant>
133+
<constant name="HOOK_EVENT_CALL" value="0" enum="HookEvent">
134+
Hook event that is called when the interpreter calls a function. The hook is called just after Lua enters the new function.
135+
</constant>
136+
<constant name="HOOK_EVENT_RETURN" value="1" enum="HookEvent">
137+
Hook event that is called when the interpreter returns from a function. The hook is called just before Lua leaves the function.
138+
</constant>
139+
<constant name="HOOK_EVENT_LINE" value="2" enum="HookEvent">
140+
Hook event that is called when the interpreter is about to start the execution of a new line of code, or when it jumps back in the code (even to the same line). This event only happens while Lua is executing a Lua function.
141+
</constant>
142+
<constant name="HOOK_EVENT_COUNT" value="3" enum="HookEvent">
143+
Hook event that is called after the interpreter executes every [code]count[/code] instructions. This event only happens while Lua is executing a Lua function.
144+
</constant>
145+
<constant name="HOOK_EVENT_TAIL_CALL" value="4" enum="HookEvent">
146+
Hook event that is called when the interpreter calls a function as a tail call. In this case, there will be no corresponding return event.
147+
</constant>
148+
<constant name="HOOK_OK" value="0" enum="HookResult">
149+
</constant>
150+
<constant name="HOOK_YIELD" value="-1" enum="HookResult">
151+
Return this value from line or count hook events to yield execution of the current Lua function that triggered the hook.
152+
</constant>
48153
</constants>
49154
</class>

‎src/LuaDebug.cpp‎

Lines changed: 3 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -27,8 +27,8 @@ LuaDebug::LuaDebug() : debug() {}
2727
LuaDebug::LuaDebug(const lua_Debug& debug) : debug(debug) {}
2828
LuaDebug::LuaDebug(lua_Debug&& debug) : debug(std::move(debug)) {}
2929

30-
LuaDebug::HookEvent LuaDebug::get_event() const {
31-
return (LuaDebug::HookEvent) debug.event;
30+
LuaThread::HookEvent LuaDebug::get_event() const {
31+
return (LuaThread::HookEvent) debug.event;
3232
}
3333

3434
String LuaDebug::get_name() const {
@@ -91,12 +91,6 @@ void LuaDebug::fill_info(const sol::protected_function& f, lua_Debug *ar) {
9191
}
9292

9393
void LuaDebug::_bind_methods() {
94-
BIND_ENUM_CONSTANT(EVENT_CALL);
95-
BIND_ENUM_CONSTANT(EVENT_RETURN);
96-
BIND_ENUM_CONSTANT(EVENT_LINE);
97-
BIND_ENUM_CONSTANT(EVENT_COUNT);
98-
BIND_ENUM_CONSTANT(EVENT_TAIL_CALL);
99-
10094
ClassDB::bind_method(D_METHOD("get_event"), &LuaDebug::get_event);
10195
ClassDB::bind_method(D_METHOD("get_name"), &LuaDebug::get_name);
10296
ClassDB::bind_method(D_METHOD("get_name_what"), &LuaDebug::get_name_what);
@@ -112,7 +106,7 @@ void LuaDebug::_bind_methods() {
112106
ClassDB::bind_method(D_METHOD("is_vararg"), &LuaDebug::is_vararg);
113107
#endif
114108

115-
ADD_PROPERTY(PropertyInfo(Variant::INT, "event", PROPERTY_HINT_NONE, "", PROPERTY_USAGE_CLASS_IS_ENUM, "HookEvent"), "", "get_event");
109+
ADD_PROPERTY(PropertyInfo(Variant::INT, "event", PROPERTY_HINT_NONE, "", PROPERTY_USAGE_CLASS_IS_ENUM, "LuaThread::HookEvent"), "", "get_event");
116110
ADD_PROPERTY(PropertyInfo(Variant::STRING, "name", PROPERTY_HINT_NONE, "", PROPERTY_USAGE_NONE), "", "get_name");
117111
ADD_PROPERTY(PropertyInfo(Variant::STRING, "name_what", PROPERTY_HINT_NONE, "", PROPERTY_USAGE_NONE), "", "get_name_what");
118112
ADD_PROPERTY(PropertyInfo(Variant::STRING, "what", PROPERTY_HINT_NONE, "", PROPERTY_USAGE_NONE), "", "get_what");

‎src/LuaDebug.hpp‎

Lines changed: 3 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,8 @@
2525
#include <godot_cpp/classes/ref_counted.hpp>
2626
#include <sol/sol.hpp>
2727

28+
#include "LuaThread.hpp"
29+
2830
using namespace godot;
2931

3032
namespace luagdextension {
@@ -33,19 +35,11 @@ class LuaDebug : public RefCounted {
3335
GDCLASS(LuaDebug, RefCounted);
3436

3537
public:
36-
enum HookEvent {
37-
EVENT_CALL = LUA_HOOKCALL,
38-
EVENT_RETURN = LUA_HOOKRET,
39-
EVENT_LINE = LUA_HOOKLINE,
40-
EVENT_COUNT = LUA_HOOKCOUNT,
41-
EVENT_TAIL_CALL = LUA_HOOKTAILCALL,
42-
};
43-
4438
LuaDebug();
4539
LuaDebug(const lua_Debug& debug);
4640
LuaDebug(lua_Debug&& debug);
4741

48-
HookEvent get_event() const;
42+
LuaThread::HookEvent get_event() const;
4943
String get_name() const;
5044
String get_name_what() const;
5145
String get_what() const;
@@ -71,6 +65,5 @@ class LuaDebug : public RefCounted {
7165
};
7266

7367
}
74-
VARIANT_ENUM_CAST(luagdextension::LuaDebug::HookEvent);
7568

7669
#endif // __LUA_DEBUG_HPP__

‎src/LuaThread.cpp‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -168,6 +168,12 @@ void LuaThread::_bind_methods() {
168168
BIND_BITFIELD_FLAG(HOOK_MASK_LINE);
169169
BIND_BITFIELD_FLAG(HOOK_MASK_COUNT);
170170

171+
BIND_ENUM_CONSTANT(HOOK_EVENT_CALL);
172+
BIND_ENUM_CONSTANT(HOOK_EVENT_RETURN);
173+
BIND_ENUM_CONSTANT(HOOK_EVENT_LINE);
174+
BIND_ENUM_CONSTANT(HOOK_EVENT_COUNT);
175+
BIND_ENUM_CONSTANT(HOOK_EVENT_TAIL_CALL);
176+
171177
BIND_ENUM_CONSTANT(HOOK_OK);
172178
BIND_ENUM_CONSTANT(HOOK_YIELD);
173179

‎src/LuaThread.hpp‎

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -51,6 +51,14 @@ class LuaThread : public LuaObjectSubclass<sol::thread> {
5151
HOOK_MASK_COUNT = LUA_MASKCOUNT,
5252
};
5353

54+
enum HookEvent {
55+
HOOK_EVENT_CALL = LUA_HOOKCALL,
56+
HOOK_EVENT_RETURN = LUA_HOOKRET,
57+
HOOK_EVENT_LINE = LUA_HOOKLINE,
58+
HOOK_EVENT_COUNT = LUA_HOOKCOUNT,
59+
HOOK_EVENT_TAIL_CALL = LUA_HOOKTAILCALL,
60+
};
61+
5462
enum HookResult {
5563
HOOK_OK = 0,
5664
HOOK_YIELD = -1,
@@ -77,8 +85,9 @@ class LuaThread : public LuaObjectSubclass<sol::thread> {
7785
};
7886

7987
}
80-
VARIANT_ENUM_CAST(luagdextension::LuaThread::Status);
88+
VARIANT_ENUM_CAST(luagdextension::LuaThread::HookEvent);
8189
VARIANT_ENUM_CAST(luagdextension::LuaThread::HookResult);
90+
VARIANT_ENUM_CAST(luagdextension::LuaThread::Status);
8291
VARIANT_BITFIELD_CAST(luagdextension::LuaThread::HookMask);
8392

8493
#endif // __LUA_THREAD_HPP__

0 commit comments

Comments
 (0)