[PATCH v1 29/58] perf futex-contention: Port futex-contention to use python module

Ian Rogers
2026-04-20T00:00:29Z

Rewrite tools/perf/scripts/python/futex-contention.py to use the
python module and various style changes. By avoiding the overheads in
the `perf script` execution the performance improves by more than 3.2x
as shown in the following (with PYTHON_PATH and PERF_EXEC_PATH set as
necessary):

```
$ perf record -e syscalls:sys_*_futex -a sleep 1
...
$ time perf script tools/perf/scripts/python/futex-contention.py
Install the python-audit package to get syscall names.
For example:
# apt-get install python3-audit (Ubuntu)
# yum install python3-audit (Fedora)
etc.

Press control+C to stop and show the summary
aaa/4[2435653] lock 7f76b380c878 contended 1 times, 1099 avg ns [max: 1099 ns, min 1099 ns]
...
real 0m1.007s
user 0m0.935s
sys 0m0.072s
$ time python3 tools/perf/python/futex-contention.py
...
real 0m0.314s
user 0m0.259s
sys 0m0.056s
```

Signed-off-by: Ian Rogers <irogers@google.com>
---
tools/perf/python/futex-contention.py | 54 +++++++++++++++++++++++++++
1 file changed, 54 insertions(+)
create mode 100755 tools/perf/python/futex-contention.py

diff --git a/tools/perf/python/futex-contention.py b/tools/perf/python/futex-contention.py
new file mode 100755
index 000000000000..153583de9cde
--- /dev/null
+++ b/tools/perf/python/futex-contention.py
@@ -0,0 +1,54 @@
+#!/usr/bin/env python3
+# SPDX-License-Identifier: GPL-2.0
+# Measures futex contention.
+from collections import defaultdict
+from typing import Dict
+import perf
+
+process_names: Dict[int, str] = {}
+start_times: Dict[int, [int, int]] = {}
+session = None
+durations: Dict[[int, int], list] = defaultdict(list)
+
+FUTEX_WAIT = 0
+FUTEX_WAKE = 1
+FUTEX_PRIVATE_FLAG = 128
+FUTEX_CLOCK_REALTIME = 256
+FUTEX_CMD_MASK = ~(FUTEX_PRIVATE_FLAG | FUTEX_CLOCK_REALTIME)
+
+
+def process_event(sample):
+ def handle_start(tid: int, uaddr: int, op: int, start_time: int) -> None:
+ if (op & FUTEX_CMD_MASK) != FUTEX_WAIT:
+ return
+ if tid not in process_names:
+ try:
+ process = session.process(tid)
+ except Exception:
+ return
+ process_names[tid] = process.comm()
+ start_times[tid] = (uaddr, start_time)
+
+ def handle_end(tid: int, end_time: int) -> None:
+ if tid not in start_times:
+ return
+ (uaddr, start_time) = start_times[tid]
+ del start_times[tid]
+ durations[(tid, uaddr)].append(end_time - start_time)
+ event_name = str(sample.evsel)
+ if event_name == "evsel(syscalls:sys_enter_futex)":
+ handle_start(sample.sample_tid, sample.uaddr,
+ sample.op, sample.sample_time)
+ elif event_name == "evsel(syscalls:sys_exit_futex)":
+ handle_end(sample.sample_tid, sample.sample_time)
+
+
+if __name__ == "__main__":
+ session = perf.session(perf.data("perf.data"), sample=process_event)
+ session.process_events()
+ for ((tid, uaddr), vals) in sorted(durations.items()):
+ avg = sum(vals) / len(vals)
+ max_val = max(vals)
+ min_val = min(vals)
+ print(f"{process_names[tid]}[{tid}] lock {uaddr:x} contended {len(vals)} "
+ f"times, {avg} avg ns [max: {max_val} ns, min {min_val} ns]")
--
2.54.0.rc1.513.gad8abe7a5a-goog