builtin/profiler/instrumentation.lua

   1 --Minetest
   2 --Copyright (C) 2016 T4im
   3 --
   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.
   8 --
   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.
  13 --
  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.
  17
  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 = ...
  21
  22 local instrument_builtin = get_bool_default("instrument.builtin", false)
  23
  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,
  46         register_on_mapblocks_changed = 0,
  47 }
  48
  49 ---
  50 -- Create an unique instrument name.
  51 -- Generate a missing label with a running index number.
  52 --
  53 local counts = {}
  54 local function generate_name(def)
  55         local class, label, func_name = def.class, def.label, def.func_name
  56         if label then
  57                 if class or func_name then
  58                         return format("%s '%s' %s", class or "", label, func_name or ""):trim()
  59                 end
  60                 return format("%s", label):trim()
  61         elseif label == false then
  62                 return format("%s", class or func_name):trim()
  63         end
  64
  65         local index_id = def.mod .. (class or func_name)
  66         local index = counts[index_id] or 1
  67         counts[index_id] = index + 1
  68         return format("%s[%d] %s", class or func_name, index, class and func_name or ""):trim()
  69 end
  70
  71 ---
  72 -- Keep `measure` and the closure in `instrument` lean, as these, and their
  73 -- directly called functions are the overhead that is caused by instrumentation.
  74 --
  75 local time, log = core.get_us_time, sampler.log
  76 local function measure(modname, instrument_name, start, ...)
  77         log(modname, instrument_name, time() - start)
  78         return ...
  79 end
  80 --- Automatically instrument a function to measure and log to the sampler.
  81 -- def = {
  82 --              mod = "",
  83 --              class = "",
  84 --              func_name = "",
  85 --              -- if nil, will create a label based on registration order
  86 --              label = "" | false,
  87 -- }
  88 local function instrument(def)
  89         if not def or not def.func then
  90                 return
  91         end
  92         def.mod = def.mod or get_current_modname() or "??"
  93         local modname = def.mod
  94         local instrument_name = generate_name(def)
  95         local func = def.func
  96
  97         if not instrument_builtin and modname == "*builtin*" then
  98                 return func
  99         end
 100
 101         return function(...)
 102                 -- This tail-call allows passing all return values of `func`
 103                 -- also called https://en.wikipedia.org/wiki/Continuation_passing_style
 104                 -- Compared to table creation and unpacking it won't lose `nil` returns
 105                 -- and is expected to be faster
 106                 -- `measure` will be executed after func(...)
 107                 local start = time()
 108                 return measure(modname, instrument_name, start, func(...))
 109         end
 110 end
 111
 112 local function can_be_called(func)
 113         -- It has to be a function or callable table
 114         return type(func) == "function" or
 115                 ((type(func) == "table" or type(func) == "userdata") and
 116                 getmetatable(func) and getmetatable(func).__call)
 117 end
 118
 119 local function assert_can_be_called(func, func_name, level)
 120         if not can_be_called(func) then
 121                 -- Then throw an *helpful* error, by pointing on our caller instead of us.
 122                 error(format("Invalid argument to %s. Expected function-like type instead of '%s'.",
 123                                 func_name, type(func)), level + 1)
 124         end
 125 end
 126
 127 ---
 128 -- Wraps a registration function `func` in such a way,
 129 -- that it will automatically instrument any callback function passed as first argument.
 130 --
 131 local function instrument_register(func, func_name)
 132         local register_name = func_name:gsub("^register_", "", 1)
 133         return function(callback, ...)
 134                 assert_can_be_called(callback, func_name, 2)
 135                 register_functions[func_name] = register_functions[func_name] + 1
 136                 return func(instrument {
 137                         func = callback,
 138                         func_name = register_name
 139                 }, ...)
 140         end
 141 end
 142
 143 local function init_chatcommand()
 144         if get_bool_default("instrument.chatcommand", true) then
 145                 local orig_register_chatcommand = core.register_chatcommand
 146                 core.register_chatcommand = function(cmd, def)
 147                         def.func = instrument {
 148                                 func = def.func,
 149                                 label = "/" .. cmd,
 150                         }
 151                         orig_register_chatcommand(cmd, def)
 152                 end
 153         end
 154 end
 155
 156 ---
 157 -- Start instrumenting selected functions
 158 --
 159 local function init()
 160         if get_bool_default("instrument.entity", true) then
 161                 -- Explicitly declare entity api-methods.
 162                 -- Simple iteration would ignore lookup via __index.
 163                 local entity_instrumentation = {
 164                         "on_activate",
 165                         "on_deactivate",
 166                         "on_step",
 167                         "on_punch",
 168                         "on_rightclick",
 169                         "get_staticdata",
 170                 }
 171                 -- Wrap register_entity() to instrument them on registration.
 172                 local orig_register_entity = core.register_entity
 173                 core.register_entity = function(name, prototype)
 174                         local modname = get_current_modname()
 175                         for _, func_name in pairs(entity_instrumentation) do
 176                                 prototype[func_name] = instrument {
 177                                         func = prototype[func_name],
 178                                         mod = modname,
 179                                         func_name = func_name,
 180                                         label = prototype.label,
 181                                 }
 182                         end
 183                         orig_register_entity(name,prototype)
 184                 end
 185         end
 186
 187         if get_bool_default("instrument.abm", true) then
 188                 -- Wrap register_abm() to automatically instrument abms.
 189                 local orig_register_abm = core.register_abm
 190                 core.register_abm = function(spec)
 191                         spec.action = instrument {
 192                                 func = spec.action,
 193                                 class = "ABM",
 194                                 label = spec.label,
 195                         }
 196                         orig_register_abm(spec)
 197                 end
 198         end
 199
 200         if get_bool_default("instrument.lbm", true) then
 201                 -- Wrap register_lbm() to automatically instrument lbms.
 202                 local orig_register_lbm = core.register_lbm
 203                 core.register_lbm = function(spec)
 204                         spec.action = instrument {
 205                                 func = spec.action,
 206                                 class = "LBM",
 207                                 label = spec.label or spec.name,
 208                         }
 209                         orig_register_lbm(spec)
 210                 end
 211         end
 212
 213         if get_bool_default("instrument.global_callback", true) then
 214                 for func_name, _ in pairs(register_functions) do
 215                         core[func_name] = instrument_register(core[func_name], func_name)
 216                 end
 217         end
 218
 219         if get_bool_default("instrument.profiler", false) then
 220                 -- Measure overhead of instrumentation, but keep it down for functions
 221                 -- So keep the `return` for better optimization.
 222                 profiler.empty_instrument = instrument {
 223                         func = function() return end,
 224                         mod = "*profiler*",
 225                         class = "Instrumentation overhead",
 226                         label = false,
 227                 }
 228         end
 229 end
 230
 231 return {
 232         register_functions = register_functions,
 233         instrument = instrument,
 234         init = init,
 235         init_chatcommand = init_chatcommand,
 236 }