folly/experimental/gdb/README.md

   1 `gdb` scripts
   2 -----------
   3
   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).
   6
   7 ### How to run the scripts
   8
   9 To run the scripts, fire up `gdb` and load a script with `source -v`. Example:
  10
  11 ```lang=bash
  12 $ gdb -p 123456
  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.
  16 (gdb) deadlock
  17 Found deadlock!
  18 ...
  19 ```
  20
  21 ### What does each script do?
  22
  23 #### `deadlock.py` - Detect deadlocks
  24
  25 Consider the following program that always deadlocks:
  26
  27 ```lang=cpp
  28 void deadlock3() {
  29   std::mutex m1, m2, m3;
  30   folly::Baton<> b1, b2, b3;
  31
  32   auto t1 = std::thread([&m1, &m2, &b1, &b2] {
  33     std::lock_guard<std::mutex> g1(m1);
  34     b1.post();
  35     b2.wait();
  36     std::lock_guard<std::mutex> g2(m2);
  37   });
  38
  39   auto t2 = std::thread([&m3, &m2, &b3, &b2] {
  40     std::lock_guard<std::mutex> g2(m2);
  41     b2.post();
  42     b3.wait();
  43     std::lock_guard<std::mutex> g3(m3);
  44   });
  45
  46   auto t3 = std::thread([&m3, &m1, &b3, &b1] {
  47     std::lock_guard<std::mutex> g3(m3);
  48     b3.post();
  49     b1.wait();
  50     std::lock_guard<std::mutex> g1(m1);
  51   });
  52
  53   t1.join();
  54   t2.join();
  55   t3.join();
  56 }
  57 ```
  58
  59 The `deadlock.py` script introduces a new `deadlock` command that can help
  60 us identify the threads and mutexes involved with the deadlock.
  61
  62 ```lang=bash
  63 $ gdb -p 2174496
  64 (gdb) source -v ./folly/experimental/gdb/deadlock.py
  65 Type "deadlock" to detect deadlocks.
  66 (gdb) deadlock
  67 Found deadlock!
  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)
  71 ```
  72
  73 NOTE: This script only works on Linux and requires debug symbols to be installed
  74 for the `pthread` library.