pi_stress(8)

✨ pi_stress — a whole manual page, but make it cute ✨

okay bestie, we're reading pi_stress from the Linux System Administrator's Manual (section 8, iykyk) and honestly? it's giving stress-test royalty. 💅

SPDX-License-Identifier: GPL-2.0-or-later</purl>

---

🌸 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 💖

so pi_stress is this program that stresses the priority-inheritance code paths for POSIX mutexes, both in the Linux kernel and in 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 💀 like, that's the whole point. no cap.

---

✨ 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 🦋

bestie. listen. the pi_stress test threads run as SCHED_FIFO or SCHED_RR threads, which means 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. protecting your babies fr fr 🫶

---

💀 BUGS 💀

no documented bugs. iconic behavior, honestly. not a single one. ✨

---

👑 AUTHOR 👑

Clark Williams <williams@redhat.com> 💜

---

and that's the whole thing bestie, go stress some mutexes responsibly 🌈⭐

this page came from the Linux System Administrator's Manual, dated Nov 27, 2006, and it's pi_stress(8) — mwah, take care of her 🎀💅