[转]lua的Debug库

debug库并不给你一个可用的 Lua 调试器，而是给你提供一些为Lua写一个调试器的方便。出于性能方面的考虑，关于这方面官方的接口是通过C API实现的。Lua中的debug库就是一种在Lua代码中直接访问这些C函数的方法。Debug库在一个debug表内声明了他所有的函数。
与其他的标准库不同的是，你应该尽可能少的是有debug库。首先，debug库中的一些函数性能比较低；第二，它破坏了语言的一些真理(sacred truths)，比如你不能在定义一个局部变量的函数外部，访问这个变量。通常，在你的最终产品中，你不想打开这个debug库，或者你可能想删除这个库：
debug = nil
debug库由两种函数组成：自省(introspective)函数和hooks。自省函数使得我们可以检查运行程序的某些方面，比如活动函数栈、当前执行代码的行号、本地变量的名和值。Hooks可以跟踪程序的执行情况。
Debug库中的一个重要的思想是栈级别(stack level)。一个栈级别就是一个指向在当前时刻正在活动的特殊函数的数字，也就是说，这个函数正在被调用但还没有返回。调用debug库的函数级别为1，调用他(他指调用debug库的函数)的函数级别为2，以此类推。
23.1 自省（Introspective）
在debug库中主要的自省函数是debug.getinfo。他的第一个参数可以是一个函数或者栈级别。对于函数foo调用debug.getinfo(foo)，将返回关于这个函数信息的一个表。这个表有下列一些域：
ü source，标明函数被定义的地方。如果函数在一个字符串内被定义（通过loadstring），source就是那个字符串。如果函数在一个文件中定义，source是@加上文件名。
ü short_src，source的简短版本（最多60个字符），记录一些有用的错误信息。
ü linedefined，source中函数被定义之处的行号。
ü what，标明函数类型。如果foo是一个普通得Lua函数，结果为 "Lua"；如果是一个C函数，结果为 "C"；如果是一个Lua的主chunk，结果为 "main"。
ü name，函数的合理名称。
ü namewhat，上一个字段代表的含义。这个字段的取值可能为：W"global"、"local"、"method"、"field"，或者 ""（空字符串）。空字符串意味着Lua没有找到这个函数名。
ü nups，函数的upvalues的个数。
ü func，函数本身；详细情况看后面。
当foo是一个C函数的时候，Lua无法知道很多相关的信息，所以对这种函数，只有what、name、namewhat这几个域的值可用。
以数字 n调用debug.getinfo(n)时，返回在n级栈的活动函数的信息数据。比如，如果n=1，返回的是正在进行调用的那个函数的信息。（n=0表示C函数getinfo本身）如果n比栈中活动函数的个数大的话，debug.getinfo返回nil。当你使用数字n调用debug.getinfo查询活动函数的信息的时候，返回的结果table中有一个额外的域：currentline，即在那个时刻函数所在的行号。另外，func表示指定n级的活动函数。
字段名的写法有些技巧。记住：因为在Lua中函数是第一类值，所以一个函数可能有多个函数名。查找指定值的函数的时候，Lua会首先在全局变量中查找，如果没找到才会到调用这个函数的代码中看它是如何被调用的。后面这种情况只有在我们使用数字调用getinfo的时候才会起作用，也就是这个时候我们能够获取调用相关的详细信息。
函数getinfo 的效率并不高。Lua以不消弱程序执行的方式保存debug信息（Lua keeps debug information in a form that does not impair program execution），效率被放在第二位。为了获取比较好地执行性能，getinfo可选的第二个参数可以用来指定选取哪些信息。指定了这个参数之后，程序不会浪费时间去收集那些用户不关心的信息。这个参数的格式是一个字符串，每一个字母代表一种类型的信息，可用的字母的含义如下：
'n'

selects fields name and namewhat
'f'

selects field func
'S'

selects fields source, short_src, what, and linedefined
'l'

selects field currentline
'u'

selects field nup
下面的函数阐明了debug.getinfo的使用，函数打印一个活动栈的原始跟踪信息（traceback）：
function traceback ()
local level = 1
while true do
local info = debug.getinfo(level, "Sl")
if not info then break end
if info.what == "C" then -- is a C function?
print(level, "C function")
else -- a Lua function
print(string.format("[%s]:%d",
info.short_src, info.currentline))
end
level = level + 1
end
end
不难改进这个函数，使得getinfo获取更多的数据，实际上debug库提供了一个改善的版本debug.traceback，与我们上面的函数不同的是，debug.traceback并不打印结果，而是返回一个字符串。
23.1.1访问局部变量
调用debug库的getlocal函数可以访问任何活动状态的局部变量。这个函数由两个参数：将要查询的函数的栈级别和变量的索引。函数有两个返回值：变量名和变量当前值。如果指定的变量的索引大于活动变量个数，getlocal返回nil。如果指定的栈级别无效，函数会抛出错误。（你可以使用debug.getinfo检查栈级别的有效性）
Lua对函数中所出现的所有局部变量依次计数，只有在当前函数的范围内是有效的局部变量才会被计数。比如，下面的代码
function foo (a,b)
local x
do local c = a - b end
local a = 1
while true do
local name, value = debug.getlocal(1, a)
if not name then break end
print(name, value)
a = a + 1
end
end

foo(10, 20)
结果为：
a 10
b 20
x nil
a 4
索引为1的变量是a，2是b，3是x，4是另一个a。在getlocal被调用的那一点，c已经超出了范围，name和value都不在范围内。（记住：局部变量仅仅在他们被初始化之后才可见）也可以使用debug.setlocal修改一个局部变量的值，他的前两个参数是栈级别和变量索引，第三个参数是变量的新值。这个函数返回一个变量名或者nil（如果变量索引超出范围）
23.1.2访问Upvalues
我们也可以通过debug库的getupvalue函数访问Lua函数的upvalues。和局部变量不同的是，即使函数不在活动状态他依然有upvalues（这也就是闭包的意义所在）。所以，getupvalue的第一个参数不是栈级别而是一个函数（精确的说应该是一个闭包），第二个参数是upvalue的索引。Lua按照upvalue在一个函数中被引用(refer)的顺序依次编号，因为一个函数不能有两个相同名字的upvalues，所以这个顺序和upvalue并没什么关联（relevant）。
可以使用函数ebug.setupvalue修改upvalues。也许你已经猜到，他有三个参数：一个闭包，一个upvalues索引和一个新的upvalue值。和setlocal类似，这个函数返回upvalue的名字，或者nil（如果upvalue索引超出索引范围）。
下面的代码显示了，在给定变量名的情况下，如何访问一个正在调用的函数的任意的给定变量的值：
function getvarvalue (name)
local value, found

-- try local variables
local i = 1
while true do
local n, v = debug.getlocal(2, i)
if not n then break end
if n == name then
value = v
found = true
end
i = i + 1
end
if found then return value end

-- try upvalues
local func = debug.getinfo(2).func
i = 1
while true do
local n, v = debug.getupvalue(func, i)
if not n then break end
if n == name then return v end
i = i + 1
end

-- not found; get global
return getfenv(func)[name]
end
首先，我们尝试这个变量是否为局部变量：如果对于给定名字的变量有多个变量，我们必须访问具有最高索引的那一个，所以我们总是需要遍历整个循环。如果在局部变量中找不到指定名字的变量，我们尝试这个变量是否为upvalues：首先，我们使用debug.getinfo(2).func获取调用的函数，然后遍历这个函数的upvalues，最后如果我们找到给定名字的变量，我们在全局变量中查找。注意调用debug.getlocal和debug.getinfo的参数2（用来访问正在调用的函数）的用法。
23.2 Hooks
debug库的hook是这样一种机制：注册一个函数，用来在程序运行中某一事件到达时被调用。有四种可以触发一个hook的事件：当Lua调用一个函数的时候call事件发生；每次函数返回的时候，return事件发生；Lua开始执行代码的新行时候，line事件发生；运行指定数目的指令之后，count事件发生。Lua使用单个参数调用hooks，参数为一个描述产生调用的事件："call"、"return"、"line" 或 "count"。另外，对于line事件，还可以传递第二个参数：新行号。我们在一个hook内总是可以使用debug.getinfo获取更多的信息。
使用带有两个或者三个参数的debug.sethook 函数来注册一个hook：第一个参数是hook函数；第二个参数是一个描述我们打算监控的事件的字符串；可选的第三个参数是一个数字，描述我们打算获取count事件的频率。为了监控call、return和line事件，可以将他们的第一个字母（'c'、'r' 或 'l'）组合成一个mask字符串即可。要想关掉hooks，只需要不带参数地调用sethook即可。
下面的简单代码，是一个安装原始的跟踪器：打印解释器执行的每一个新行的行号：
debug.sethook(print, "l")
上面这一行代码，简单的将print函数作为hook函数，并指示Lua当line事件发生时调用print函数。可以使用getinfo将当前正在执行的文件名信息加上去，使得跟踪器稍微精致点的：
function trace (event, line)
local s = debug.getinfo(2).short_src
print(s .. ":" .. line)
end

debug.sethook(trace, "l")
23.3 Profiles
尽管debug库名字上看来是一个调式库，除了用于调式以外，还可以用于完成其他任务。这种常见的任务就是profiling。对于一个实时的profile来说（For a profile with timing），最好使用C接口来完成：对于每一个hook过多的Lua调用代价太大并且通常会导致测量的结果不准确。然而，对于计数的profiles而言，Lua代码可以很好的胜任。下面这部分我们将实现一个简单的profiler：列出在程序运行过程中，每一个函数被调用的次数。
我们程序的主要数据结构是两张表，一张关联函数和他们调用次数的表，一张关联函数和函数名的表。这两个表的索引下标是函数本身。
local Counters = {}
local Names = {}
在profiling之后，我们可以访问函数名数据，但是记住：在函数在活动状态的情况下，可以得到比较好的结果，因为那时候Lua会察看正在运行的函数的代码来查找指定的函数名。
现在我们定义hook函数，他的任务就是获取正在执行的函数并将对应的计数器加1；同时这个hook函数也收集函数名信息：
local function hook ()
local f = debug.getinfo(2, "f").func
if Counters[f] == nil then -- first time `f' is called?
Counters[f] = 1
Names[f] = debug.getinfo(2, "Sn")
else -- only increment the counter
Counters[f] = Counters[f] + 1
end
end
下一步就是使用这个hook运行程序，我们假设程序的主chunk在一个文件内，并且用户将这个文件名作为profiler的参数：
prompt> lua profiler main-prog
这种情况下，我们的文件名保存在arg[1]，打开hook并运行文件：
local f = assert(loadfile(arg[1]))
debug.sethook(hook, "c") -- turn on the hook
f() -- run the main program
debug.sethook() -- turn off the hook
最后一步是显示结果，下一个函数为一个函数产生名称，因为在Lua中的函数名不确定，所以我们对每一个函数加上他的位置信息，型如file:line 。如果一个函数没有名字，那么我们只用它的位置表示。如果一个函数是C函数，我们只是用它的名字表示（他没有位置信息）。
function getname (func)
local n = Names[func]
if n.what == "C" then
return n.name
end
local loc = string.format("[%s]:%s",
n.short_src, n.linedefined)
if n.namewhat ~= "" then
return string.format("%s (%s)", loc, n.name)
else
return string.format("%s", loc)
end
end
最后，我们打印每一个函数和他的计数器：
for func, count in pairs(Counters) do
print(getname(func), count)
end
如果我们将我们的profiler应用到Section 10.2的马尔科夫链的例子上，我们得到如下结果：
[markov.lua]:4 884723
write 10000
[markov.lua]:0 (f) 1
read 31103
sub 884722
[markov.lua]:1 (allwords) 1
[markov.lua]:20 (prefix) 894723
find 915824
[markov.lua]:26 (insert) 884723
random 10000
sethook 1
insert 884723
那意味着第四行的匿名函数（在allwords内定义的迭代函数）被调用884,723次，write(io.write)被调用10,000次。
你可以对这个profiler进行一些改进，比如对输出排序、打印出比较好的函数名、改善输出格式。不过，这个基本的profiler已经很有用，并且可以作为很多高级工具的基础。