48 lines
2.2 KiB
Plaintext
48 lines
2.2 KiB
Plaintext
ADVPROFILER
|
|
===========
|
|
|
|
advprofiler is a Minetest mod library to facilitate profiling of Minetest mod functions. It tries to unify and extend the functionality of existing profiling frameworks (namely https://bitbucket.org/sorcerykid/stopwatch and
|
|
https://github.com/xyzz/minetest-mods/blob/master/seasons/profiler.lua)
|
|
|
|
What it does differently than other profilers is that it is step-oriented. It counts the times and calls measured per Minetest server step, and not continuously.
|
|
|
|
Profilers and units
|
|
===================
|
|
|
|
A profiler (profiler instance) represents one large project to be monitored. It is obtained by a constructor, and has a name which is purely informational.
|
|
|
|
A single profiler consists of several units. Units are identified only by a string key, which needs to be unique. Units can be explicitly registered to specify functions to present and/or accumulate data, if they are not explicitly registered, they're created implicitly using default presentation functions.
|
|
|
|
Profiling variants
|
|
==================
|
|
|
|
Each unit measures two things: 'count' and 'time'. Whether you actually use the "time" value is up to you, if you never access it, the implementation will handle this efficiently.
|
|
|
|
There are two ways to access a unit. Both can be used interchangeably on the same unit, depending on the use case.
|
|
|
|
Count mode
|
|
----------
|
|
|
|
This mode consists of a single call, which simply increases the 'count' value:
|
|
# prof:count("unit", [count_inc=1])
|
|
|
|
It does neither start nor stop the timetaker
|
|
|
|
Time mode
|
|
---------
|
|
# prof:enter("unit", [count_inc=1])
|
|
Increments the 'count' and saves the current os.clock() as start timestamp
|
|
|
|
# prof:leave("unit")
|
|
Stops the timetaker and adds the elapsed time to the 'time'.
|
|
|
|
Recursing units is not supported. Calling enter() on an already entered unit results in a warning, as well as calling leave() on a not-entered unit.
|
|
|
|
Server Steps
|
|
============
|
|
Once per server step, advprofiler performs an intermediate evaluation step, in which it determines the per-step average values. This happens in a dedicated globalstep callback.
|
|
|
|
During the step evaluation, none of the units should be in 'entered' state. If an unit is still not left, a warning is emitted and the time sample is discarded (the 'count' is still applied in this case!)
|
|
|
|
|