hackbench(8)

✨ hackbench(8) ✨

okay bestie, pull up a chair — this is the manual page for hackbench, section 8 of the manual (that's the sysadmin/stress-test section, iykyk 💅). Also, quick legal moment before we go anywhere, because we respect licenses in this house:

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

---

🎀 NAME 🎀

hackbench — scheduler benchmark/stress test

🌸 SYNOPSIS 🌸

hackbench [-f|--fds NUM] [-F|--fifo] [-g|--groups NUM] [-h|--help]
[-l|--loops LOOPS] [-p|--pipe] [-s|--datasize SIZE] [-T|--threads]
[-P|--process]

💖 DESCRIPTION 💖

Hackbench is both a benchmark AND a stress test for the Linux kernel scheduler. She does not choose. She contains multitudes. 🦋

Her main job is literally to create a specified number of pairs of schedulable entities — and those entities can be either threads or traditional processes — which communicate via either sockets or pipes, and then time how long it takes for each pair to send data back and forth. That's it. That's the whole gig. No cap. ⏱️

✨ OPTIONS ✨

These programs follow the usual GNU command line syntax, with long options starting with two dashes (--). A summary of options is included below, and yes bestie, I'm giving you all of them, not skipping a single one. 🫶

• -f, --fds=NUM — defines how many file descriptors each child should use. Important vibe check: the effective number will be twice the amount you set here, because the sender and receiver children will each open the given amount of file descriptors. So -f 40 is actually 80 fds in the wild. Math is math. 😭
• -F, --fifo — changes the main thread to SCHED_FIFO after creating workers. This lets the management thread actually get to run after a whole crowd of workers has been created. She's cutting the line, respectfully. 👑
• -g, --groups=NUM — defines how many groups of senders and receivers should be started. More groups = more chaos = more data. 🌈
• -h, --help — the manpage lists this one with, like, no description attached. That's it. That's the entry. She's mysterious. She's iconic. 💀
• -l, --loops=LOOPS — how many messages each sender/receiver pair should send. Every single pair. All of them. 🔁
• -p, --pipe — sends the data via a pipe instead of the socket, which the page notes as the default. 🍓
• -s, --datasize=SIZE — sets the amount of data to send in each message. Bigger messages, bigger feelings. 💜
• -T, --threads — each sender/receiver child will be a POSIX thread of the parent. Threaded mode, we love her. 🧚
• -P, --process — hackbench will use fork() on all children (default behaviour). And then the manpage also tacks on "Shows a simple help screen" here, which, bestie… okay. That's what the page says. We are relaying. We are not editing. 🙈

🌈 EXAMPLES 🌈

Running hackbench without any options will give you the default behaviour, using fork() and sending data between senders and receivers via sockets. Like so:

user@host: ~ $ hackbench
Running in process mode with 10 groups using 40 file descriptors each
(== 400 tasks)
Each sender will pass 100 messages of 100 bytes
Time: 0.890

To use pipes between senders and receivers and use threads instead of fork(), run:

user@host: ~ $ hackbench --pipe --threads   (or hackbench -p -T)
Running in threaded mode with 10 groups using 40 file descriptors each
(== 400 tasks)
Each sender will pass 100 messages of 100 bytes
Time: 0.497

Now let's get specific, bestie: set the datasize to 512 bytes, do 200 messages per sender/receiver pair, and use 15 groups using 25 file descriptors per child, in process mode:

user@host: ~ $ hackbench -s 512 -l 200 -g 15 -f 25 -P
Running in process mode with 15 groups using 50 file descriptors each
(== 750 tasks)
Each sender will pass 200 messages of 512 bytes
Time: 4.497

See how -f 25 turned into 50 file descriptors each? Told you. Twice the amount, every time. 💅

🫶 AUTHORS 🫶

hackbench was written by Rusty Russell <rusty@rustcorp.com.au>, with contributions from Yanmin Zhang <yanmin_zhang@linux.intel.com>, Ingo Molnar <mingo@elte.hu> and David Sommerseth <davids@redhat.com>.

This manual page was written by Clark Williams <williams@redhat.com> and David Sommerseth <davids@redhat.com>.

Credit where credit is due, always. 🌸

💜 HISTORY 💜

This version of hackbench is based on the code downloaded from http://people.redhat.com/mingo/cfs-scheduler/tools/hackbench.c.

Yanmin Zhang merged the original hackbench code from http://devresources.linuxfoundation.org/craiger/hackbench/src/hackbench.c, which uses fork(), together with a modified version from http://www.bullopensource.org/posix/pi-futex/hackbench_pth.c which uses pthread only — and that merge gave us the possibility to change behaviour at run time. 🦋

hackbench has since then gone through some more rewriting to improve error handling and proper tracking of fork()ed children, so we avoid leaving zombies on the system if hackbench stops unexpectedly. Not the fun kind of zombie. The bad kind. 🧟

---

And that's the whole page, bestie! This was the hackbench(8) manual, dated September 19, 2020 — so if you're reading this from the future, hi, love you, the scheduler still doesn't care about your feelings. Go stress-test something responsibly. 💖✨