pi_stress(8)

NAME
pi_stress - a stress test for POSIX Priority Inheritance mutexes

SYNOPSIS
pi_stress [-d|--debug] [-D|--duration [-g|--groups N] [-i|--inversions INV] [--json FILENAME] [-m|--mlockall] [-p|--prompt] [-q|--quiet] [-r|--rr] [-s|--sched OPTS] [-u|--uniprocessor] [-v|--verbose] [-V|--version]

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 priority inversion condition that will deadlock if priority inheritance doesn't work.

OPTIONS

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

-D TIME, --duration=TIME
    Specify a length for the test run.
    Append 'm', 'h', or 'd' to specify minutes, hours or days.

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

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

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

--json=FILENAME
    Write final results into FILENAME , JSON formatted.

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

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

-q|--quiet
    Suppress running output

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

-s OPTS|--sched OPTS
    scheduling options per thread type:
    id=[high|med|low],
    policy=[fifo,rr],priority=N,
    policy=deadline,runtime=N,deadline=N,period=N

-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.

-v|--verbose
    Run with verbose messages

-V|--version
    Print version number

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>