Changeset View
Changeset View
Standalone View
Standalone View
doc/developer-notes.md
Show First 20 Lines • Show All 207 Lines • ▼ Show 20 Lines | |||||
**DEBUG_LOCKORDER** | **DEBUG_LOCKORDER** | ||||
Bitcoin Core is a multithreaded application, and deadlocks or other multithreading bugs | Bitcoin Core is a multithreaded application, and deadlocks or other multithreading bugs | ||||
can be very difficult to track down. Compiling with -DDEBUG_LOCKORDER (configure | can be very difficult to track down. Compiling with -DDEBUG_LOCKORDER (configure | ||||
CXXFLAGS="-DDEBUG_LOCKORDER -g") inserts run-time checks to keep track of which locks | CXXFLAGS="-DDEBUG_LOCKORDER -g") inserts run-time checks to keep track of which locks | ||||
are held, and adds warnings to the debug.log file if inconsistencies are detected. | are held, and adds warnings to the debug.log file if inconsistencies are detected. | ||||
**Sanitizers** | |||||
Bitcoin can be compiled with various "sanitizers" enabled, which add | |||||
instrumentation for issues regarding things like memory safety, thread race | |||||
conditions, or undefined behavior. This is controlled with the | |||||
`--with-sanitizers` configure flag, which should be a comma separated list of | |||||
sanitizers to enable. The sanitizer list should correspond to supported | |||||
`-fsanitize=` options in your compiler. These sanitizers have runtime overhead, | |||||
so they are most useful when testing changes or producing debugging builds. | |||||
Some examples: | |||||
```bash | |||||
# Enable both the address sanitizer and the undefined behavior sanitizer | |||||
./configure --with-sanitizers=address,undefined | |||||
# Enable the thread sanitizer | |||||
./configure --with-sanitizers=thread | |||||
``` | |||||
If you are compiling with GCC you will typically need to install corresponding | |||||
"san" libraries to actually compile with these flags, e.g. libasan for the | |||||
address sanitizer, libtsan for the thread sanitizer, and libubsan for the | |||||
undefined sanitizer. If you are missing required libraries, the configure script | |||||
will fail with a linker error when testing the sanitizer flags. | |||||
The test suite should pass cleanly with the `thread` and `undefined` sanitizers, | |||||
but there are a number of known problems when using the `address` sanitizer. The | |||||
address sanitizer is known to fail in | |||||
[sha256_sse4::Transform](/src/crypto/sha256_sse4.cpp) which makes it unusable | |||||
unless you also use `--disable-asm` when running configure. We would like to fix | |||||
sanitizer issues, so please send pull requests if you can fix any errors found | |||||
by the address sanitizer (or any other sanitizer). | |||||
Not all sanitizer options can be enabled at the same time, e.g. trying to build | |||||
with `--with-sanitizers=address,thread` will fail in the configure script as | |||||
these sanitizers are mutually incompatible. Refer to your compiler manual to | |||||
learn more about these options and which sanitizers are supported by your | |||||
compiler. | |||||
Additional resources: | |||||
* [AddressSanitizer](https://clang.llvm.org/docs/AddressSanitizer.html) | |||||
* [LeakSanitizer](https://clang.llvm.org/docs/LeakSanitizer.html) | |||||
* [MemorySanitizer](https://clang.llvm.org/docs/MemorySanitizer.html) | |||||
* [ThreadSanitizer](https://clang.llvm.org/docs/ThreadSanitizer.html) | |||||
* [UndefinedBehaviorSanitizer](https://clang.llvm.org/docs/UndefinedBehaviorSanitizer.html) | |||||
* [GCC Instrumentation Options](https://gcc.gnu.org/onlinedocs/gcc/Instrumentation-Options.html) | |||||
* [Google Sanitizers Wiki](https://github.com/google/sanitizers/wiki) | |||||
* [Issue #12691: Enable -fsanitize flags in Travis](https://github.com/bitcoin/bitcoin/issues/12691) | |||||
Locking/mutex usage notes | Locking/mutex usage notes | ||||
------------------------- | ------------------------- | ||||
The code is multi-threaded, and uses mutexes and the | The code is multi-threaded, and uses mutexes and the | ||||
LOCK/TRY_LOCK macros to protect data structures. | LOCK/TRY_LOCK macros to protect data structures. | ||||
Deadlocks due to inconsistent lock ordering (thread 1 locks cs_main | Deadlocks due to inconsistent lock ordering (thread 1 locks cs_main | ||||
and then cs_wallet, while thread 2 locks them in the opposite order: | and then cs_wallet, while thread 2 locks them in the opposite order: | ||||
▲ Show 20 Lines • Show All 307 Lines • Show Last 20 Lines |