NAME

       pi_stress - a stress test for POSIX Priority Inheritance mutexes

SYNOPSIS

       pi_stress   [-i|--inversions   inversions]  [-t|--duration  seconds]  [-g|--groups  groups
       [-d|--debug]  [-v|--verbose]   [-s|--signal]   [-r|--rr]   [-p|--prompt]   [-m|--mlockall]
       [-u|--uniprocessor]
       pi_stress -h|--help

DESCRIPTION

       pi_stress  is  a  program  used  to  stress  the priority-inheritance code paths for POSIX
       mutexes, in both the Linux kernel and the C library. It runs as a  realtime-priority  task
       and  launches  inversion  machine  thread  groups.  Each  inversion group causes a priorty
       inversion condition that will deadlock if priority inheritance doesn't work.

OPTIONS

       -i n|--inversions=n
              Run for n number of inversion conditions. This is the total  number  of  inversions
              for all inversion groups. Default is -1 for infinite.

       -t n|--duration=n
              Run the test for n seconds and then terminate.

       -g n|--groups=n
              The number of inversion groups to run. Defaults to 10.

       -d|--debug
              Run in debug mode; lots of extra prints

       -v|--verbose
              Run with verbose messages

       -s|--signal
              Terminate on receipt of SIGTERM (Ctrl-C). Default is to terminate on any keypress.

       -r|--rr
              Run  inversion  group  threads as SCHED_RR (round-robin). The default is to run the
              inversion threads as SCHED_FIFO.

       -p|--prompt
              Prompt before actually starting the stress test

       -u|--uniprocessor
              Run all threads on one processor. The default is to run all inversion group threads
              on one processor and the admin threads (reporting thread, keyboard reader, etc.) on
              a different processor.

       -m|--mlockall
              Call mlockall to lock current and future memory allocations and prevent being paged
              out

       -h|--help
              Display a short help message and options.

CAVEATS

       The  pi_stress  test  threads run as SCHED_FIFO or SCHED_RR threads, which means that they
       can starve critical system threads. It is advisable to change  the  scheduling  policy  of
       critical  system threads to be SCHED_FIFO prior to running pi_stress and use a priority of
       10 or higher, to prevent those threads from being starved by the stress test.

BUGS

       No documented bugs.

AUTHOR

       Clark Williams <williams@redhat.com>

                                           Nov 27, 2006                              pi_stress(8)