mining: replace interrupt methods with cancellation arguments #36097

Depends on bitcoin-core/libmultiprocess#342. Only the last commit belongs to this PR.

The blocking methods (waitTipChanged, createNewBlock, and BlockTemplate::waitNext) currently rely on interrupt()/interruptWait() to cancel them when they are in progress (#33676, #34184). With request cancellation support in libmultiprocess (bitcoin-core/libmultiprocess#342), this is no longer needed.

This PR adds CancelArg arguments to those blocking methods to register a callback that runs on cancellation and deprecates the interrupt methods. Registering returns a CancelGuard that unregisters the callback when destroyed, so the event loop can't run it after the wrapped method goes out of scope.

In the capnp schema, use the Proxy.extraParam annotation for the C++ CancelArg parameter and the Cxx.allowCancellation annotation to enable request cancellation at the RPC layer.

The CustomBuildExtraParam/CustomReadExtraParam overloads for CancelArg live in ipc/capnp/common-types.h, following the reference implementation in the libmultiprocess PR. The client side wraps the request in a kj::Canceler and throws InterruptException when canceled, while the server side registers the method's callback with the request's server context, where the event loop runs it on cancellation.

In tests, update miner_tests to cancel waitNext() from another thread, and interface_ipc_mining.py to drop the response promise. Also add drop_promise() to ipc_util.py to abandon capnp promises, and a cancelable waitCancel method to the ipc_tests FooInterface to exercise both the client and server hooks.

Additional note: this is the Bitcoin Core side of approach 4 in #33575.

<!--e57a25ab6845829454e8d69fc972939a-->

The following sections might be updated with supplementary metadata relevant to reviewers and maintainers.

<!--006a51241073e994b41acfe9ec718e94-->

Code Coverage & Benchmarks

For details see: https://corecheck.dev/bitcoin/bitcoin/pulls/36097.

<!--021abf342d371248e50ceaed478a90ca-->

Reviews

See the guideline and AI policy for information on the review process. A summary of reviews will appear here.

<!--174a7506f384e20aa4161008e828411d-->

Conflicts

Reviewers, this pull request conflicts with the following ones:

• #36257 (qa: assert_equals -> assert_true/assert_false by hodlinator)
• #35932 (ipc: make ipc::disconnectIncoming wait for in-progress calls to complete by ryanofsky)
• #35675 (mining: add block template manager by ismaelsadeeq)
• #35671 (mining: add TxCollection to bandwidth-efficiently validate external block templates by Sjors)
• #35581 (node: add block template manager and track waitNext fee inflow by ismaelsadeeq)
• #35511 (RFC: consensus: Make CAmount a class by hodlinator)
• #35037 (ipc: support per-address max-connections options on -ipcbind by enirox001)
• #33922 (mining: add getMemoryLoad() and track template non-mempool memory footprint by Sjors)
• #29409 (multiprocess: Add capnp wrapper for Chain interface by ryanofsky)
• #19461 (multiprocess: Add bitcoin-gui -ipcconnect option by ryanofsky)
• #19460 (multiprocess: Add bitcoin-wallet -ipcconnect option by ryanofsky)
• #10102 (Multiprocess bitcoin by ryanofsky)

If you consider this pull request important, please also help to review the conflicting pull requests. Ideally, start with the one that should be merged first.

<!--5faf32d7da4f0f540f40219e4f7537a3-->

LLM Linter (✨ experimental)

Possible typos and grammar issues:

• // It safe to access post_writer here because the loop can't exit until this write takes place. -> // It is safe to access post_writer here because the loop can't exit until this write takes place. [missing verb; current sentence is grammatically broken]
• - Adds support for nonunix platforms, making API changes that are not backwards compatible -> - Adds support for non-Unix platforms, making API changes that are not backwards compatible [nonunix is misspelled]

Possible places where comparison-specific test macros should replace generic comparisons:

• [src/ipc/test/ipc_tests.cpp] BOOST_CHECK_THROW(foo->waitCancel(cancel_arg), mp::InterruptException); -> consider BOOST_CHECK_EXCEPTION(...) with a message predicate so the test verifies the expected cancellation reason, not just the exception type.

^{2026-09-11 20:35:17}

<!--85328a0da195eb286784d51f73fa0af9-->

🚧 At least one of the CI tasks failed. _{Task test ancestor commits: https://github.com/bitcoin/bitcoin/actions/runs/33042822923/job/98420040676} _{LLM reason (✨ experimental): CI failed due to a clang build error treated as fatal: a C++23 lambda attribute ([[noreturn]]) is used in mp/proxy-types.h, triggering -Wc++23-lambda-attributes under -Werror.}

<details><summary>Hints</summary>

Try to run the tests locally, according to the documentation. However, a CI failure may still happen due to a number of reasons, for example:

• Possibly due to a silent merge conflict (the changes in this pull request being incompatible with the current code in the target branch). If so, make sure to rebase on the latest commit of the target branch.

• A sanitizer issue, which can only be found by compiling with the sanitizer and running the affected test.

• An intermittent issue.

Leave a comment here, if you need help tracking down a confusing failure.

</details>

Wow, this is very cool. The PR contains a lot of boilerplate updates but the heart of the change (5cdb565ee565b9cd61b3286a3945d7244d0f744c) is simply:

--- a/src/node/interfaces.cpp
+++ b/src/node/interfaces.cpp
@@ -926,8 +926,9 @@ public:
         return SubmitBlock(chainman(), std::make_shared<const CBlock>(m_block_template->block), reason, debug);
     }
 
-    std::unique_ptr<BlockTemplate> waitNext(BlockWaitOptions options) override
+    std::unique_ptr<BlockTemplate> waitNext(BlockWaitOptions options, interfaces::CancelArg cancel) override
     {
+        if (cancel) cancel([this] { InterruptWait(notifications(), m_interrupt_wait); });
         auto new_template = WaitAndCreateNewBlock(chainman(),
                                                   notifications(),
                                                   m_node.mempool.get(),
@@ -939,11 +940,6 @@ public:
         return nullptr;
     }
 
-    void interruptWait() override
-    {
-        InterruptWait(notifications(), m_interrupt_wait);
-    }
-
     const BlockCreateOptions m_create_options;
 
     const std::unique_ptr<CBlockTemplate> m_block_template;

Dropping the interruptWait method, replacing it with a CancelArg argument, and calling the argument with a lambda containing the code that used to be in interruptWait method.

With that change rust, python, and c++ clients can now cancel blocking requests more simply and efficiently using cap'n protos native cancellation mechanism, instead of needing to make new IPC calls to cancel previous ones.

There's an nontrivial amount of code to review here, but this is a very nice end-to-end implementation and demonstration that supporting this cancellation mechanism is worthwhile and makes things simpler for clients and servers. It could also become more important in the future if we want to have blocking calls that are individually cancellable instead of the current situation where interrupt methods can cancel multiple calls.

Updated to match the latest changes in the upstream PR.

5cdb565ee565b9cd61b3286a3945d7244d0f744c -> 1c02f2abea5f3d72fa4887ec8f76e85f51276bbb (compare)

Notable changes:

• libmultiprocess no longer ships mp/type-cancel.h, so the CustomBuildExtraParam/CustomReadExtraParam overloads for CancelArg now live in ipc/capnp/common-types.h, and CancelFn/CancelArg moved to interfaces/types.h.
• CancelArg now returns a CancelGuard that unregisters the callback when destroyed, so the event loop can't run it after the wrapped method goes out of scope.
• Added a cancelable waitCancel method to the ipc_tests FooInterface to exercise both the client and server hooks.