2 --Copyright (C) 2016 T4im
4 --This program is free software; you can redistribute it and/or modify
5 --it under the terms of the GNU Lesser General Public License as published by
6 --the Free Software Foundation; either version 2.1 of the License, or
7 --(at your option) any later version.
9 --This program is distributed in the hope that it will be useful,
10 --but WITHOUT ANY WARRANTY; without even the implied warranty of
11 --MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12 --GNU Lesser General Public License for more details.
14 --You should have received a copy of the GNU Lesser General Public License along
15 --with this program; if not, write to the Free Software Foundation, Inc.,
16 --51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
18 local format, pairs, type = string.format, pairs, type
19 local core, get_current_modname = core, core.get_current_modname
20 local profiler, sampler, get_bool_default = ...
22 local instrument_builtin = get_bool_default("instrument.builtin", false)
24 local register_functions = {
25 register_globalstep = 0,
26 register_playerevent = 0,
27 register_on_placenode = 0,
28 register_on_dignode = 0,
29 register_on_punchnode = 0,
30 register_on_generated = 0,
31 register_on_newplayer = 0,
32 register_on_dieplayer = 0,
33 register_on_respawnplayer = 0,
34 register_on_prejoinplayer = 0,
35 register_on_joinplayer = 0,
36 register_on_leaveplayer = 0,
37 register_on_cheat = 0,
38 register_on_chat_message = 0,
39 register_on_player_receive_fields = 0,
40 register_on_craft = 0,
41 register_craft_predict = 0,
42 register_on_protection_violation = 0,
43 register_on_item_eat = 0,
44 register_on_punchplayer = 0,
45 register_on_player_hpchange = 0,
49 -- Create an unique instrument name.
50 -- Generate a missing label with a running index number.
53 local function generate_name(def)
54 local class, label, func_name = def.class, def.label, def.func_name
56 if class or func_name then
57 return format("%s '%s' %s", class or "", label, func_name or ""):trim()
59 return format("%s", label):trim()
60 elseif label == false then
61 return format("%s", class or func_name):trim()
64 local index_id = def.mod .. (class or func_name)
65 local index = counts[index_id] or 1
66 counts[index_id] = index + 1
67 return format("%s[%d] %s", class or func_name, index, class and func_name or ""):trim()
71 -- Keep `measure` and the closure in `instrument` lean, as these, and their
72 -- directly called functions are the overhead that is caused by instrumentation.
74 local time, log = core.get_us_time, sampler.log
75 local function measure(modname, instrument_name, start, ...)
76 log(modname, instrument_name, time() - start)
79 --- Automatically instrument a function to measure and log to the sampler.
84 -- -- if nil, will create a label based on registration order
85 -- label = "" | false,
87 local function instrument(def)
88 if not def or not def.func then
91 def.mod = def.mod or get_current_modname() or "??"
92 local modname = def.mod
93 local instrument_name = generate_name(def)
96 if not instrument_builtin and modname == "*builtin*" then
101 -- This tail-call allows passing all return values of `func`
102 -- also called https://en.wikipedia.org/wiki/Continuation_passing_style
103 -- Compared to table creation and unpacking it won't lose `nil` returns
104 -- and is expected to be faster
105 -- `measure` will be executed after time() and func(...)
106 return measure(modname, instrument_name, time(), func(...))
110 local function can_be_called(func)
111 -- It has to be a function or callable table
112 return type(func) == "function" or
113 ((type(func) == "table" or type(func) == "userdata") and
114 getmetatable(func) and getmetatable(func).__call)
117 local function assert_can_be_called(func, func_name, level)
118 if not can_be_called(func) then
119 -- Then throw an *helpful* error, by pointing on our caller instead of us.
120 error(format("Invalid argument to %s. Expected function-like type instead of '%s'.",
121 func_name, type(func)), level + 1)
126 -- Wraps a registration function `func` in such a way,
127 -- that it will automatically instrument any callback function passed as first argument.
129 local function instrument_register(func, func_name)
130 local register_name = func_name:gsub("^register_", "", 1)
131 return function(callback, ...)
132 assert_can_be_called(callback, func_name, 2)
133 register_functions[func_name] = register_functions[func_name] + 1
134 return func(instrument {
136 func_name = register_name
141 local function init_chatcommand()
142 if get_bool_default("instrument.chatcommand", true) then
143 local orig_register_chatcommand = core.register_chatcommand
144 core.register_chatcommand = function(cmd, def)
145 def.func = instrument {
149 orig_register_chatcommand(cmd, def)
155 -- Start instrumenting selected functions
157 local function init()
158 if get_bool_default("instrument.entity", true) then
159 -- Explicitly declare entity api-methods.
160 -- Simple iteration would ignore lookup via __index.
161 local entity_instrumentation = {
169 -- Wrap register_entity() to instrument them on registration.
170 local orig_register_entity = core.register_entity
171 core.register_entity = function(name, prototype)
172 local modname = get_current_modname()
173 for _, func_name in pairs(entity_instrumentation) do
174 prototype[func_name] = instrument {
175 func = prototype[func_name],
177 func_name = func_name,
178 label = prototype.label,
181 orig_register_entity(name,prototype)
185 if get_bool_default("instrument.abm", true) then
186 -- Wrap register_abm() to automatically instrument abms.
187 local orig_register_abm = core.register_abm
188 core.register_abm = function(spec)
189 spec.action = instrument {
194 orig_register_abm(spec)
198 if get_bool_default("instrument.lbm", true) then
199 -- Wrap register_lbm() to automatically instrument lbms.
200 local orig_register_lbm = core.register_lbm
201 core.register_lbm = function(spec)
202 spec.action = instrument {
205 label = spec.label or spec.name,
207 orig_register_lbm(spec)
211 if get_bool_default("instrument.global_callback", true) then
212 for func_name, _ in pairs(register_functions) do
213 core[func_name] = instrument_register(core[func_name], func_name)
217 if get_bool_default("instrument.profiler", false) then
218 -- Measure overhead of instrumentation, but keep it down for functions
219 -- So keep the `return` for better optimization.
220 profiler.empty_instrument = instrument {
221 func = function() return end,
223 class = "Instrumentation overhead",
230 register_functions = register_functions,
231 instrument = instrument,
233 init_chatcommand = init_chatcommand,