pcall y xpcall: el manejador corre antes de desenrollar

Casi toda la documentación presenta xpcall como un pcall al que además le pasas una función para tratar el error, como si la diferencia fuera de ergonomía. No lo es. La diferencia es temporal: el manejador de xpcall se ejecuta en el instante del fallo, con todos los marcos de la pila todavía presentes, mientras que pcall te devuelve el control cuando esa pila ya se ha deshecho y no queda de ella más que el valor lanzado. Esa ventana de unos pocos microsegundos es la única oportunidad de capturar un rastro de pila, de inspeccionar variables locales del marco que falló o de decidir en función de dónde estaba el programa. Quien no entiende esto acaba escribiendo un rastro de pila desde fuera de pcall y preguntándose por qué solo muestra dos líneas inútiles.

El instante del manejador

Cuando error se dispara dentro de una llamada protegida, la máquina virtual hace dos cosas en orden. Primero, si la barrera es un xpcall, invoca al manejador pasándole el valor del error, con la pila del fallo todavía viva encima. Después deshace esa pila hasta la barrera y devuelve el control, usando como segundo resultado lo que el manejador haya devuelto.

local function nivel3() error("fallo profundo") end
local function nivel2() nivel3() end
local function nivel1() nivel2() end

local ok, rastro = xpcall(nivel1, debug.traceback)
print(rastro)
-- archivo.lua:1: fallo profundo
-- stack traceback:
--   [C]: in function 'error'
--   archivo.lua:1: in upvalue 'nivel3'
--   archivo.lua:2: in upvalue 'nivel2'
--   archivo.lua:3: in function <archivo.lua:3>
--   [C]: in function 'xpcall'
--   ...

Compara con el intento equivalente y erróneo que casi todo el mundo escribe una vez:

local ok, err = pcall(nivel1)
if not ok then
  print(debug.traceback(err))   -- el rastro es el de AQUI, no el del fallo
end

En el segundo caso, los marcos de las tres funciones ya no existen. El rastro que obtienes describe el lugar donde estás preguntando, no el lugar donde ocurrió el problema, y por tanto no contiene ninguna información que no tuvieras ya.

flowchart TD
A[error se dispara en el marco profundo] --> B[La pila sigue completa]
B --> C[Con xpcall se llama al manejador aqui]
C --> D[El manejador ve todos los marcos y puede leerlos]
D --> E[Se desenrolla la pila hasta la barrera]
B --> F[Con pcall no se llama a nadie]
F --> E
E --> G[Se devuelve falso y el valor o lo que devolvio el manejador]

Qué puede y qué no puede hacer el manejador

El manejador recibe un único argumento —el valor del error— y lo que devuelve se convierte en el segundo resultado de xpcall. Dentro de él tienes acceso a la biblioteca de depuración operando sobre la pila del fallo: puedes pedir el rastro, recorrer los marcos con la función de información de pila, o leer las variables locales del marco que reventó.

local function manejador(err)
  local info = debug.getinfo(2, "Sl")     -- marco donde ocurrio el error
  return {
    mensaje = err,
    fuente  = info and info.short_src,
    linea   = info and info.currentline,
    rastro  = debug.traceback("", 2),
  }
end

local ok, detalle = xpcall(procesar, manejador, entrada)

Ese último argumento es importante: desde Lua 5.2, xpcall acepta argumentos extra que se pasan a la función llamada, igual que hace pcall. Antes de esa versión había que envolver la llamada en un closure, lo que suponía asignar un objeto nuevo en cada invocación.

Hay tres cosas que el manejador no debe hacer. La primera es trabajo pesado: se ejecuta en un estado del intérprete que puede ser precario, y el caso extremo es un desbordamiento de pila, donde el margen para llamar a más funciones es mínimo. La segunda es fallar: un error lanzado dentro del manejador no se maneja llamándolo otra vez, sino que aborta la secuencia con un estado especial y un mensaje fijo sobre error durante el manejo de errores, perdiendo por completo el diagnóstico original. La tercera es retener referencias a objetos de la pila del fallo más allá de su vida útil, porque prolongan artificialmente la vida de estructuras que deberían morir con el desenrollado.

Recoger los resultados sin perder ninguno

La forma habitual de leer el retorno de una llamada protegida asume que sabes cuántos valores devuelve la función. Cuando no lo sabes —porque envuelves código ajeno, o porque la función tiene retornos variables— hay que capturar la tupla completa.

local resultados = table.pack(pcall(funcionDesconocida, a, b))
if not resultados[1] then
  return nil, resultados[2]
end
return table.unpack(resultados, 2, resultados.n)

El campo de longitud que produce esa función de empaquetado es imprescindible aquí, porque un retorno legítimo puede contener valores nulos intercalados y el operador de longitud no los contaría. Este patrón es la base de cualquier envoltorio genérico, y su coste es una tabla por llamada, lo que lo descarta para rutas calientes pero lo hace perfectamente aceptable en fronteras de módulo.

Cuando el número de retornos sí se conoce, hay una forma más barata que evita la tabla y que conviene tener a mano:

local ok, a, b, c = pcall(fn, x)
if not ok then return nil, a end   -- en el caso de fallo, a es el error

La asimetría de esa línea —la misma variable contiene un resultado o un error según el booleano anterior— es fea pero idiomática, y es la razón de que la convención de nombrar las variables de retorno de una llamada protegida sea distinta de la habitual: mucho código las llama simplemente por su posición precisamente para no mentir sobre su contenido.

El coste de llamar en modo protegido

Instalar una barrera no es gratis. La máquina virtual guarda un punto de recuperación, registra el nivel de pila actual y marca el límite de la llamada protegida. En términos de orden de magnitud, una llamada protegida cuesta entre dos y cuatro veces lo que una llamada ordinaria a la misma función, dependiendo de la versión, de la plataforma y de si el intérprete se compiló con manejo de excepciones del anfitrión o con saltos no locales.

-- Coste innecesario: un closure nuevo en cada vuelta
for _, tarea in ipairs(cola) do
  local ok = pcall(function() ejecutar(tarea, contexto) end)
end

-- Sin asignaciones: la funcion y sus argumentos van por separado
for _, tarea in ipairs(cola) do
  local ok = pcall(ejecutar, tarea, contexto)
end

Una consideración adicional afecta a las optimizaciones. El cuerpo de la función llamada conserva sus llamadas de cola con normalidad, pero la barrera en sí introduce un marco de C que aparece en los rastros y que corta la cadena de marcos de Lua. En programas con muchas capas protegidas anidadas, esa acumulación de marcos de C consume el límite de llamadas anidadas del anfitrión mucho antes que el límite de pila de Lua.