Test2::Harness::Stall::Trace(3)

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 "SIGUSR1" handler. Each signal writes the frames to the process's own STDERR, and to "$dir/stack-$$-N.txt" where N counts up per process.

    Install it after any snapshot of %SIG the 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", "line" and "sub". 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

Chad Granum <exodist7@gmail.com>

AUTHORS

Chad Granum <exodist7@gmail.com>

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.

See <https://dev.perl.org/licenses/>