---
name: "pi_stress"
section: "8"
platform: "linux"
package: "rt-tests"
version: "2.11-1"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/pi_stress"
---

# pi\_stress(8)

a stress test for POSIX Priority Inheritance mutexes

\# SPDX-License-Identifier: GPL-2.0-or-later

## 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\>