#35518 doc: document -blocknotify, -walletnotify and other -*notify options
| Reviewability | Reviews | Agreement | Size | ||||
|---|---|---|---|---|---|---|---|
| #35518 doc: document -blocknotify, -walletnotify and other -*notify options | Author silent 124d | 1 | Positive | 21 | |||
|
|
|
|
| |||
Reviewability: ReadyStalePaused Agreement: StrongPositivePositive w/ caveatsNeutralMildDisputedBlockedCrickets Reviews: current code-review ACKs, then (+stale ACKs) and -NACKs; greener = more ACKs. Size: lines added or modified outside tests, then in tests; greener = smaller. | |||||||
Goal
Adds doc/notifications.md to document the execution model of the five -*notify startup options. Specifically explains that each notification runs asynchronously in a detached thread without ordering guarantees, directing consumers to query state via RPC instead.
Problem: Users and external script integrations have historically assumed sequential notification execution, leading to race conditions and confusion as noted in issue #14278.
Reviewability
Stale · Author silent 124d
No author activity for 124 days; a review may wait a long time for a response.
Waiting on (from the thread read):
- reviewer: review from willcl-ark 2026-10-31
Agreement
Positive
support without stated reasons, no open objection (sedited)
Thread notes: sedited pinged willcl-ark for review. No new claims or support entries were introduced.
Objections, suggestions, and questions:
| Reviewer | Type | Harm, request, or question | Status | Must be | Author replied | Quote |
|---|---|---|---|---|---|---|
| sedited (member) | suggestion, usefulness | distill doc to a single paragraph on threading and ordering behavior plus a list of commands, keeping command-level documentation in help output / man pages | accepted · author distilled the doc in c:4774986672 and sedited approved in r:4764304499 | answered | yes | 2026-06-21: 'I don't think exhaustively documenting every command here is useful, and would prefer that the command-level docs continue to live in the help output / man page.' Status from: 2026-07-23: sedited: 'ACK 5801ce70b34b5429ed184645daf85b2fb2ab7200' |
| sedited (member) | suggestion, scope | drop the sentence comparing notifications to ZMQ | accepted · author dropped the comparison in c:4839021430 and sedited approved in r:4764304499 | answered | yes | 2026-06-29: 'I would drop this entire sentence about zmq. This is obvious for developers that know what zmq is.' Status from: 2026-07-23: sedited: 'ACK 5801ce70b34b5429ed184645daf85b2fb2ab7200' |
| sedited (member) | objection, correctness | mischaracterizing notifications as lacking internal consistency | accepted · author dropped the sentence in c:4839021430 and sedited approved in r:4764304499 | answered | yes | 2026-06-29: 'I'm not sure I agree with this last sentence. It is already qualified that events may fire out of order, but internally they seem consistent to me. I would drop this sentence too.' Status from: 2026-07-23: sedited: 'ACK 5801ce70b34b5429ed184645daf85b2fb2ab7200' |
| willcl-ark (member) | suggestion, scope | consider adding tests for notification guarantees | answered · sedited and willcl-ark agreed in follow-up comments that ordering is not guaranteed | answered | by others | 2026-09-15: 'that may be something we want to do here too, if it makes sense...' Status from: 2026-09-16: sedited: 'I'm not sure if we really want to guarantee order. It just seems like a brittle thing to be promising.' |
Support:
- sedited (member) (ACK, 2026-07-23): ACK 5801ce70b34b5429ed184645daf85b2fb2ab7200 [not substantive]
Participants:
- sedited (member, objection, 7 statements 2026-06-21 to 2026-10-31): objected to mischaracterizing notification consistency and suggested distilling doc; later approved
- willcl-ark (member, neutral, 2 statements 2026-09-15 to 2026-09-16): referenced past work on callback docs and promised to review soon
Files
0 lines under test/bench/ci.
- doc/notifications.md +20/-0
- doc/README.md +1/-0
Card
The short text the ranking pass compares across PRs.
Adds doc/notifications.md documenting that shell command notifications (-*notify) run in detached threads without ordering guarantees and recommends verifying state via RPC. Solves a persistent trap for developers integrating external automation with bitcoind, partially closing #14278. The scope was trimmed in review to focus purely on execution semantics, earning an ACK from sedited. The PR is clean and ready for merge consideration despite author inactivity.
Data
thread read through 2026-10-31 (11 statements), head 5801ce70b3
labels: Docs
Categories
Documentation
P3 · user request
Clarifies asynchronous execution semantics of `-*notify` options to prevent user integrations from making flawed concurrency assumptions. Resolves long-standing confusion noted in issue #14278 regarding notification ordering guarantees.
Membership: Matches the Docs label and exclusively adds documentation files in doc/.
Factors: security/stability 0, bug 0, performance 0, user value 1, leverage 0