highperfocused/bitcoin
1
0
Fork 0
mirror of https://github.com/bitcoin/bitcoin.git synced 2026-05-31 16:24:48 +02:00
Code Issues Packages Projects Releases Wiki Activity

Merge bitcoin/bitcoin#35304: kernel: doc: document wipe lifecycle and best entry nullability

Browse Source 
6189335f6b kernel: doc: document wipe lifecycle and best entry nullability (csjones)

Pull request description:

  Document on `btck_chainstate_manager_options_set_wipe_dbs` that a wipe must be followed by `btck_chainstate_manager_import_blocks` before the chainstate manager is used for anything else, as the existing kernel tests already do (specifically the `chainman_reindex*` kernel tests). Note in the `@return` of `btck_chainstate_manager_get_best_entry` that it can return null when no block headers have been loaded.

  Background: I've been working on a bindings project using the libbitcoinkernel and tripped on a SIGSEGV calling the entry accessors on the null pointer returned by `get_best_entry` after a `(true, true)` wipe (#35293). The C++ wrapper handles this via `btck::check<>`, but bindings generated from the C header don't see the wrapper. Adding a nullability documentation hint helps generators produce the correct signature, and the `@note` on `set_wipe_dbs` documents the lifecycle that avoids the null in the first place.

  Docs-only change; no tests ran.

ACKs for top commit:
  sedited:
    ACK 6189335f6b
  alexanderwiederin:
    ACK 6189335f6b

Tree-SHA512: 319d9704c9857c8eb12e8726d16710d8b5777404f8ecf50d832a5e5b0a9b9f0d8321074ecb8b985e5b03a6eb7119cc4eb73f36d096dc0149a73de7d6a74de4cb
This commit is contained in:
merge-script
2026-05-21 10:06:14 +02:00
parent b796bf44f3 6189335f6b
commit c6dbf3158b
1 changed files with 3 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
src/kernel/bitcoinkernel.h
View File

@@ -1178,6 +1178,8 @@ BITCOINKERNEL_API void btck_chainstate_manager_options_set_worker_threads_num(
* @param[in] wipe_block_tree_db Set wipe block tree db. Should only be 1 if wipe_chainstate_db is 1 too.
* @param[in] wipe_chainstate_db Set wipe chainstate db.
* @return 0 if the set was successful, non-zero if the set failed.
* @note When a wipe is set, the caller must invoke @ref btck_chainstate_manager_import_blocks
* on the resulting chainstate manager before using it for anything else.
*/
BITCOINKERNEL_API int BITCOINKERNEL_WARN_UNUSED_RESULT btck_chainstate_manager_options_set_wipe_dbs(
btck_ChainstateManagerOptions* chainstate_manager_options,
@@ -1232,7 +1234,7 @@ BITCOINKERNEL_API btck_ChainstateManager* BITCOINKERNEL_WARN_UNUSED_RESULT btck_
* known cumulative proof of work.
*
* @param[in] chainstate_manager Non-null.
* @return The btck_BlockTreeEntry.
* @return The btck_BlockTreeEntry, or null if no block headers have been loaded.
*/
BITCOINKERNEL_API const btck_BlockTreeEntry* BITCOINKERNEL_WARN_UNUSED_RESULT btck_chainstate_manager_get_best_entry(
const btck_ChainstateManager* chainstate_manager) BITCOINKERNEL_ARG_NONNULL(1);