Inside Bitcoin

751
752  - [ThreadMessageHandler (`b-msghand`)](https://doxygen.bitcoincore.org/class_c_connman.html#msghand)
753    : Application level message handling (sending and receiving). Almost
754    all net_processing and validation logic runs on this thread.
755
756  - [ThreadDNSAddressSeed (`b-dnsseed`)](https://doxygen.bitcoincore.org/class_c_connman.html#dnsseed)
757    : Loads addresses of peers from the DNS.
758
759  - [ThreadMapPort (`b-mapport`)](https://doxygen.bitcoincore.org/mapport_8cpp.html#mapport)
760    : Universal plug-and-play startup/shutdown.
761
762  - [ThreadSocketHandler (`b-net`)](https://doxygen.bitcoincore.org/class_c_connman.html#net)
763    : Sends/Receives data from peers on port 8333.
764
765  - [ThreadOpenAddedConnections (`b-addcon`)](https://doxygen.bitcoincore.org/class_c_connman.html#addcon)
766    : Opens network connections to added nodes.
767
768  - [ThreadOpenConnections (`b-opencon`)](https://doxygen.bitcoincore.org/class_c_connman.html#opencon)
769    : Initiates new connections to peers.
770
771  - [ThreadI2PAcceptIncoming (`b-i2paccept`)](https://doxygen.bitcoincore.org/class_c_connman.html#i2paccept)
772    : Listens for and accepts incoming I2P connections through the I2P SAM proxy.
773
774## General Bitcoin Core
775
776- New features should be exposed on RPC first, then can be made available in the GUI.
777
778  - *Rationale*: RPC allows for better automatic testing. The test suite for
779    the GUI is very limited.
780
781## Logging
782
783The macros `LogInfo`, `LogDebug`, `LogTrace`, `LogWarning` and `LogError` are available for
784logging messages. They should be used as follows:
785
786- `LogDebug(BCLog::CATEGORY, fmt, params...)` is what you want
787  most of the time, and it should be used for log messages that are
788  useful for debugging and can reasonably be enabled on a production
789  system (that has sufficient free storage space). They will be logged
790  if the program is started with `-debug=category` or `-debug=1`, or
791  the category is enabled through the `logging` RPC.
792
793- `LogInfo(fmt, params...)` should only be used rarely, e.g. for startup
794  messages or for infrequent and important events such as a new block tip
795  being found or a new outbound connection being made.
796
797- `LogError(fmt, params...)` should be used in place of `LogInfo` for
798  severe problems that require the node (or a subsystem) to shut down
799  entirely (e.g., insufficient storage space).
800
801- `LogWarning(fmt, params...)` should be used in place of `LogInfo` for
802  severe problems that the node admin should address, but are not
803  severe enough to warrant shutting down the node (e.g., system time
804  appears to be wrong, unknown soft fork appears to have activated).
805
806- `LogTrace(BCLog::CATEGORY, fmt, params...)` should be used in place of
807  `LogDebug` for log messages that would be unusable on a production
808  system, e.g. due to being too noisy in normal use, or too resource
809  intensive to process. These will be logged if the startup
810  options `-debug=category -loglevel=category:trace` or `-debug=1
811  -loglevel=trace` are selected.
812
813Note that the format strings and parameters of `LogDebug` and `LogTrace`
814are only evaluated if the logging category is enabled, so you must be
815careful to avoid side-effects in those expressions.
816
817While `LogInfo`, `LogWarning` and `LogError` messages should be rare,
818in case there are circumstances where they are not, those messages
819are automatically rate-limited to prevent potential disk-filling
820attacks. For the cases where this protection is undesirable,
821rate-limiting can be avoided with the `util::log::NO_RATE_LIMIT` tag, eg
822`LogInfo(util::log::NO_RATE_LIMIT, "UpdateTip: new best=%s ...",...)`.
823
824## General C++
825
826For general C++ guidelines, you may refer to the [C++ Core
827Guidelines](https://isocpp.github.io/CppCoreGuidelines/).
828
829Common misconceptions are clarified in those sections:
830
831- Passing (non-)fundamental types in the [C++ Core
832  Guidelines](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#rf-conventional).
833
834- If you use the `.h`, you must link the `.cpp`.
835
836  - *Rationale*: Include files define the interface for the code in implementation files. Including one but
837      not linking the other is confusing. Please avoid that. Moving functions from
838      the `.h` to the `.cpp` should not result in build errors.
839
840- Use the RAII (Resource Acquisition Is Initialization) paradigm where possible. For example, by using
841  `unique_ptr` for allocations in a function.
842
843  - *Rationale*: This avoids memory and resource leaks, and ensures exception safety.
844
845## C++ data structures
846
847- Never use the `std::map []` syntax when reading from a map, but instead use `.find()`.
848
849  - *Rationale*: `[]` does an insert (of the default element) if the item doesn't
850    exist in the map yet. This has resulted in memory leaks in the past, as well as
851    race conditions (expecting read-read behavior). Using `[]` is fine for *writing* to a map.
852
853- Do not compare an iterator from one data structure with an iterator of
854  another data structure (even if of the same type).
855
856  - *Rationale*: Behavior is undefined. In C++ parlance this means "may reformat
857    the universe", in practice this has resulted in at least one hard-to-debug crash bug.
858
859- Watch out for out-of-bounds vector access. `&vch[vch.size()]` is illegal,
860  including `&vch[0]` for an empty vector. Use `vch.data()` and `vch.data() +
861  vch.size()` instead.
862
863- Vector bounds checking is only enabled in debug mode. Do not rely on it.
864
865- Initialize all non-static class members where they are defined.
866  If this is skipped for a good reason (i.e., optimization on the critical
867  path), add an explicit comment about this.
868
869  - *Rationale*: Ensure determinism by avoiding accidental use of uninitialized
870    values. Also, static analyzers balk about this.
871    Initializing the members in the declaration makes it easy to
872    spot uninitialized ones.
873
874```cpp
875class A
876{
877    uint32_t m_count{0};
878}
879```
880
881- By default, declare constructors `explicit`.
882
883  - *Rationale*: This is a precaution to avoid unintended
884    [conversions](https://en.cppreference.com/w/cpp/language/converting_constructor).
885
886- Use explicitly signed or unsigned `char`s, or even better `uint8_t` and
887  `int8_t`. Do not use bare `char` unless it is to pass to a third-party API.
888  This type can be signed or unsigned depending on the architecture, which can
889  lead to interoperability problems or dangerous conditions such as
890  out-of-bounds array accesses.
891
892- Prefer explicit constructions over implicit ones that rely on 'magical' C++ behavior.
893
894  - *Rationale*: Easier to understand what is happening, thus easier to spot mistakes, even for those
895  that are not language lawyers.
896
897- Use `std::span` as function argument when it can operate on any range-like container.
898
899  - *Rationale*: Compared to `Foo(const vector<int>&)` this avoids the need for a (potentially expensive)
900    conversion to vector if the caller happens to have the input stored in another type of container.
901    However, be aware of the pitfalls documented in [span.h](../src/span.h).
902
903```cpp
904void Foo(std::span<const int> data);
905
906std::vector<int> vec{1,2,3};
907Foo(vec);
908```
909
910- Prefer `enum class` (scoped enumerations) over `enum` (traditional enumerations) where possible.
911
912  - *Rationale*: Scoped enumerations avoid two potential pitfalls/problems with traditional C++ enumerations: implicit conversions to `int`, and name clashes due to enumerators being exported to the surrounding scope.
913
914- `switch` statement on an enumeration example:
915
916```cpp
917enum class Tabs {
918    info,
919    console,
920};
921
922int GetInt(Tabs tab)
923{
924    int ret = [&]() {
925        switch (tab) {
926        case Tabs::info: return 0;
927        case Tabs::console: return 1;
928        } // no default case, so the compiler can warn about missing cases
929        assert(false);
930    }();
931    LogInfo("Tab %s", ret);
932    return ret;
933}
934```
935
936*Rationale*: The comment documents skipping `default:` label, and it complies with `clang-format` rules. The assertion prevents firing of `-Wreturn-type` warning on some compilers.
937
938## Strings and formatting
939
940- Use `std::string`, avoid C string manipulation functions.
941
942  - *Rationale*: C++ string handling is marginally safer, less scope for
943    buffer overflows, and surprises with `\0` characters. Also, some C string manipulations
944    tend to act differently depending on platform, or even the user locale.
945
946- For `strprintf`, `LogInfo`, `LogDebug`, etc formatting characters don't need size specifiers (hh, h, l, ll, j, z, t, L) for arithmetic types.
947
948  - *Rationale*: Bitcoin Core uses tinyformat, which is type safe. Leave them out to avoid confusion.
949
950- Use `.c_str()` sparingly. Its only valid use is to pass C++ strings to C functions that take NULL-terminated
951  strings.
952
953  - Do not use it when passing a sized array (so along with `.size()`). Use `.data()` instead to get a pointer
954    to the raw data.
955
956    - *Rationale*: Although this is guaranteed to be safe starting with C++11, `.data()` communicates the intent better.
957
958  - Do not use it when passing strings to `tfm::format`, `strprintf`, `LogInfo`, `LogDebug`, etc.
959
960    - *Rationale*: This is redundant. Tinyformat handles strings.
961
962  - Do not use it to convert to `QString`. Use `QString::fromStdString()`.
963
964    - *Rationale*: Qt has built-in functionality for converting their string
965      type from/to C++. No need to roll your own.
966
967  - In cases where you do call `.c_str()`, you might want to additionally check that the string does not contain embedded '\0' characters, because
968    it will (necessarily) truncate the string. This might be used to hide parts of the string from logging or to circumvent
969    checks. If a use of strings is sensitive to this, take care to check the string for embedded NULL characters first
970    and reject it if there are any.
971
972## Shadowing
973
974Although the shadowing warning (`-Wshadow`) is not enabled by default (it prevents issues arising
975from using a different variable with the same name),
976please name variables so that their names do not shadow variables defined in the source code.
977
978When using nested cycles, do not name the inner cycle variable the same as in
979the outer cycle, etc.
980
981## Lifetimebound
982
983The [Clang `lifetimebound`
984attribute](https://clang.llvm.org/docs/AttributeReference.html#lifetimebound)
985can be used to tell the compiler that a lifetime is bound to an object and
986potentially see a compile-time warning if the object has a shorter lifetime from
987the invalid use of a temporary. You can use the attribute by adding a `LIFETIMEBOUND`
988annotation defined in `src/attributes.h`; please grep the codebase for examples.
989
990## Threads and synchronization
991
992- Prefer `Mutex` type to `RecursiveMutex` one.
993
994- Consistently use [Clang Thread Safety Analysis](https://clang.llvm.org/docs/ThreadSafetyAnalysis.html) annotations to
995  get compile-time warnings about potential race conditions or deadlocks in code.
996
997  - In functions that are declared separately from where they are defined, the
998    thread safety annotations should be added exclusively to the function
999    declaration. Annotations on the definition could lead to false positives
1000    (lack of compile failure) at call sites between the two.