ptsematest(8)

💅 ptsematest(8) — like, the manual page but make it make sense

okay bestie, gather round 🫶 this is the manual page for ptsematest, and yes it's in section 8, and yes we're gonna get through it together. no cap.

fun legal moment first: this page carries the license tag SPDX-License-Identifier: GPL-2.0-or-later. iconic of it.

---

✨ NAME ✨

ptsematest — start two threads and measure the latency of interprocess communication with POSIX mutex. 🧵🧵

---

🌸 SYNOPSIS 🌸

ptsematest [-a|--affinity [PROC]] [-b|--breaktrace USEC] [-d|--distance
DIST] [-D|--duration TIME] [-h|--help] [-i|--interval INTV] [--json
FILENAME] [-l|--loops LOOPS] [-p|--prio PRIO] [-q|--quiet] [-S|--smp]
[-t|--threads [NUM]]

that's the whole vibe right there ↑ read it like a spell you're casting.

---

🦋 DESCRIPTION 🦋

so here's the tea ☕ — ptsematest starts two threads, and those two threads are synced up via pthread_mutex_unlock()/pthread_mutex_lock(). then it measures the latency between releasing the lock and getting it back. that's it. that's the whole program. obsessed.

---

💖 OPTIONS 💖

• -a, --affinity[=PROC] — run on processor number PROC. if you don't say which PROC, it just runs on whatever the current processor is. letting the scheduler choose, we love a chill queen.
• -b, --breaktrace=USEC — send the break trace command when latency goes over USEC. this is a debugging option, for controlling the latency tracer in the realtime preemption patch. it's genuinely useful for tracking down unexpected large latencies on a system. 🔍
• -d, --distance=DIST — sets the distance between thread intervals in microseconds (default is 500 us). heads up: when cyclictest is called with the -t option and more than one thread gets created, this distance value gets added to the interval of the threads, like so: Interval(thread N) = Interval(thread N-1) + DIST
• -D, --duration=TIME — specify how long the test run lasts. tack on 'm', 'h', or 'd' to say minutes, hours or days. ⏰
• -h, --help — print the help message. the classic.
• -i, --interval=INTV — set the base interval of the thread(s) in microseconds (default is 1000 us). this sets the interval of the first thread. also go look at -d. 👀
• --json=FILENAME — write the final results into FILENAME, JSON formatted. for the data girlies 📊
• -l, --loops=LOOPS — set the number of loops. default is 0, which means endless. this option is the move for automated tests that want a given number of test cycles. ptsematest gets stopped once the number of timer intervals has been reached.
• -p, --prio=PRIO — set the priority of the process. 👑
• -q, --quiet — print a summary only on exit. useful for automated tests where you only need to capture the summary output. shhh 🤫
• -S, --smp — SMP testing: that's options -a -t and same priority.
• -t, --threads[=NUM] — set the number of test threads (default is 1 if you don't pass this option at all). if NUM is specified, create NUM test threads. if NUM is not specified, NUM gets set to the number of available CPUs. infinite threads glitch, but make it legal

---

🔥 EXAMPLES 🔥

the following example was running on a 4-way processor:

# ptsematest -a -t -p99 -i100 -d25 -l1000000
#0: ID8672, P99, CPU0, I100; #1: ID8673, P99, CPU0, Cycles 1000000
#2: ID8674, P98, CPU1, I125; #3: ID8675, P98, CPU1, Cycles 811035
#4: ID8676, P97, CPU2, I150; #5: ID8677, P97, CPU2, Cycles 668130
#6: ID8678, P96, CPU3, I175; #7: ID8679, P96, CPU3, Cycles 589423
#1 -> #0, Min    1, Cur    1, Avg    2, Max   11
#3 -> #2, Min    1, Cur    2, Avg    2, Max   13
#5 -> #4, Min    1, Cur    4, Avg    3, Max   12
#7 -> #6, Min    1, Cur    4, Avg    2, Max   12

look at those numbers go. absolutely ate. 💅

---

🎀 AUTHORS 🎀

Carsten Emde <C.Emde@osadl.org> — thank you for your service, legend 🫡

---

⭐ SEE ALSO ⭐

• pthread_mutex_lock(3p)
• pthread_mutex_unlock(3p)

---

and that's the page, bestie. version 0.1, and yeah it lives in section 8 of the manual like all the cool system admin stuff does. go forth and measure your latencies ✨💖🦋