NAME
Test2::Harness::Stall::Trace - Report a process's own Perl call stack on demand.
DESCRIPTION
Deliberately small. Everything a watcher can see from outside a stuck process -- /proc state, wait channels, open files, the run state -- is collected by whoever sends the signal, because a process wedged in an uninterruptible syscall never runs a handler at all, and that is the case most in need of description. The Perl call stack is the one thing only the process itself can produce, so it is the only thing gathered here.
Nothing in this module may walk harness objects or take a lock; by the time it runs, the process is already believed stuck. It uses a plain caller loop rather than Carp::longmess, which formats each frame's arguments -- and those hold the resource objects and task hashrefs belonging to the code under suspicion.
NEVER SIGNAL A TEST JOB
The handler is installed in harness processes only: the runner, the scheduler, the stages, the collector and the auditor. A test job process sheds it when the runner's Scope::Guard restores the original %SIG, so SIGUSR1 there takes its default action and terminates the test.
Whoever sends the signal must therefore use a whitelist of known harness pids, and must never signal a process group.
SYNOPSIS
use Test2::Harness::Stall::Trace qw/install_trace_handler/;
install_trace_handler(File::Spec->catdir($workdir, 'stall'));EXPORTS
- install_trace_handler($dir)
-
Installs the
SIGUSR1handler. Each signal writes the frames to the process's own STDERR, and to$dir/stack-$$-N.txtwhere N counts up per process.Install it after any snapshot of
%SIGthe process intends to restore, so a forked test job sheds it. - $arrayref = stack_trace()
-
The current call stack as a list of hashrefs with
package,file,lineandsub. Frame arguments are never touched.
SOURCE
The source code repository for Test2-Harness can be found at https://github.com/Test-More/Test2-Harness/.
MAINTAINERS
AUTHORS
COPYRIGHT
Copyright Chad Granum <exodist7@gmail.com>.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.