llvm-project/lldb/packages/Python/lldbsuite/pre_kill_hook

pre_kill_hook package

Overview

The pre_kill_hook package provides a per-platform method for running code after a test process times out but before the concurrent test runner kills the timed-out process.

Detailed Description of Usage

If a platform defines the hook, then the hook gets called right after a timeout is detected in a test run, but before the process is killed.

The pre-kill-hook mechanism works as follows:

• When a timeout is detected in the process_control.ProcessDriver class that runs the per-test lldb process, a new overridable on_timeout_pre_kill() method is called on the ProcessDriver instance.

• The concurrent test driver's derived ProcessDriver overrides this method. It looks to see if a module called "lldbsuite.pre_kill_hook.{platform-system-name}" module exists, where platform-system-name is replaced with platform.system().lower(). (e.g. "Darwin" becomes the darwin.py module).

  • If that module doesn't exist, the rest of the new behavior is skipped.

  • If that module does exist, it is loaded, and the method "do_pre_kill(process_id, context_dict, output_stream)" is called. If that method throws an exception, we log it and we ignore further processing of the pre-killed process.

  • The process_id argument of the do_pre_kill function is the process id as returned by the ProcessDriver.pid property.

  • The output_stream argument of the do_pre_kill function takes a file-like object. Output to be collected from doing any processing on the process-to-be-killed should be written into the file-like object. The current impl uses a six.StringIO and then writes this output to {TestFilename}-{pid}.sample in the session directory.

• Platforms where platform.system() is "Darwin" will get a pre-kill action that runs the 'sample' program on the lldb that has timed out. That data will be collected on CI and analyzed to determine what is happening during timeouts. (This has an advantage over a core in that it is much smaller and that it clearly demonstrates any liveness of the process, if there is any).

Running the tests

To run the tests in the pre_kill_hook package, open a console, change into this directory and run the following:

python -m unittest discover