PIP_STRESS(8)

🌸 NAME 🌸

pip_stress — Priority Inheritance with processes 💅 (yes bestie, processes, not threads, we're doing the spicy version)

---

✨ SYNOPSIS ✨

pip_stress [-u|--usleep TIME]

---

💖 DESCRIPTION 💖

okay so this program is literally a demo, and what it's demoing is the technique of using priority inheritance (PI) mutexes with processes instead of threads. 🫶

The way you pull this off is you grab some shared memory — in this case with mmap that backs a pthread_mutex_t, because that's the thing that will support PI. And pay particular attention to how it's initialized to support processes, because that part is the whole entire point. 👑

The function init_shared_pthread_mutex() is the one doing the magic: it sets the pthread_mutexattr to PTHREAD_PROCESS_SHARED and sets the mutex protocol to PTHREAD_PRIO_INHERIT. No cap. 🔥

In this program we purposely try to invoke a classic priority inversion. Here's the drama:

• A low priority process grabs the mutex and does some work.
• A high priority process comes along and is blocked, because the mutex is taken. 😭
• A medium priority process that doesn't need the mutex at all then takes the processor.

And because the processes are restricted to one cpu, the low priority process never makes any progress, because the medium priority process is just vibing in an infinite loop. 🙈

That right there is a priority inversion, because the medium priority process is running at the expense of the high priority process. It's giving chaos, honestly.

BUT — and this is the slay part — since we used PRIO_INHERIT and we're running on a machine that supports preemption, the high priority process will lend its priority to the low priority process, which will preempt the medium priority process. 💫 Then the low priority process releases the mutex, which the high priority process can obtain. And when the high priority process gets to run? It kills the medium priority process. 💀 periodt.

The state structure keeps track of the progress, fyi.

ngl though — although this program is set up to likely trigger an inversion, there is no guarantee that scheduling will make that happen. Scheduling said "we'll see." 🎀

After the program completes, it reports whether a priority inversion occurred or not. Either way, this program demonstrates how to use priority inheritance mutexes with processes. 🌈

And honestly? In real life you would be better off to avoid scenarios in which a priority inversion occurs if possible — this program tries to trigger them just to show that it works. It's the "we did it for science" of scheduling. 🧚

If you are having difficulty triggering an inversion, merely increase the time that the low priority process sleeps while holding the lock (usleep). Easy fix bestie. ✨

Also note that you have to run as a user with permission to change scheduling priorities. 👀

---

🎀 OPTIONS 🎀

• -u TIME, --usleep=TIME — specify the sleep time in usec of the low priority process. Defaults to 500. 🌸

---

💜 AUTHOR 💜

pip_stress was written by John Kacur <jkacur at redhat.com> 🫶

This manual page was also written by John Kacur.

---

SPDX-License-Identifier: GPL-2.0-or-later — yes it's licensed, yes it's the good license, iykyk. 💅

okay that's the whole page, ily, this is the System Manager's Manual, pip_stress section 8, dated September 17, 2018 — go forth and inherit some priorities, bestie 👑✨