4 This directory contains a collection of `gdb` scripts that we have found helpful.
5 These scripts use the [gdb extension Python API](https://sourceware.org/gdb/current/onlinedocs/gdb/Python.html#Python).
7 ### How to run the scripts
9 To run the scripts, fire up `gdb` and load a script with `source -v`. Example:
13 (gdb) source -v ./folly/experimental/gdb/deadlock.py
14 Type "deadlock" to detect deadlocks.
15 # At this point, any new commands defined in `deadlock.py` are available.
21 ### What does each script do?
23 #### `deadlock.py` - Detect deadlocks
25 Consider the following program that always deadlocks:
29 std::mutex m1, m2, m3;
30 folly::Baton<> b1, b2, b3;
32 auto t1 = std::thread([&m1, &m2, &b1, &b2] {
33 std::lock_guard<std::mutex> g1(m1);
36 std::lock_guard<std::mutex> g2(m2);
39 auto t2 = std::thread([&m3, &m2, &b3, &b2] {
40 std::lock_guard<std::mutex> g2(m2);
43 std::lock_guard<std::mutex> g3(m3);
46 auto t3 = std::thread([&m3, &m1, &b3, &b1] {
47 std::lock_guard<std::mutex> g3(m3);
50 std::lock_guard<std::mutex> g1(m1);
59 The `deadlock.py` script introduces a new `deadlock` command that can help
60 us identify the threads and mutexes involved with the deadlock.
64 (gdb) source -v ./folly/experimental/gdb/deadlock.py
65 Type "deadlock" to detect deadlocks.
68 Thread 2 (LWP 2174497) is waiting on mutex (0x00007ffcff42a4c0) held by Thread 3 (LWP 2174498)
69 Thread 3 (LWP 2174498) is waiting on mutex (0x00007ffcff42a4f0) held by Thread 4 (LWP 2174499)
70 Thread 4 (LWP 2174499) is waiting on mutex (0x00007ffcff42a490) held by Thread 2 (LWP 2174497)
73 NOTE: This script only works on Linux and requires debug symbols to be installed
74 for the `pthread` library.