{
 "number": 32278,
 "repo": "bitcoin/bitcoin",
 "url": "https://github.com/bitcoin/bitcoin/pull/32278",
 "title": "doc: better document NetEventsInterface and the deletion of \"CNode\"s",
 "author": "vasild",
 "author_association": "MEMBER",
 "created_at": "2025-04-15T16:06:05Z",
 "updated_at": "2026-09-04T07:55:26Z",
 "age_days": 520,
 "draft": false,
 "labels": [
  "Docs"
 ],
 "milestone": null,
 "base": "master",
 "head_sha": "5647c188138ae03cdb15db7a99b7e6b160bb9ba0",
 "head_ref": "doc_NetEventsInterface",
 "head_repo": "vasild/bitcoin",
 "head_history": [
  {
   "t": "2025-04-16T04:11:30Z",
   "sha": "0f26ac35e26c0da0b0ff75c497fe5fe5bdc38a2d"
  },
  {
   "t": "2025-04-16T04:15:21Z",
   "sha": "e44e669378f2c63b09eda68797039b73047febff"
  },
  {
   "t": "2025-11-13T15:42:46Z",
   "sha": "110548c9eabc0bdd1341e4aafe9fe3f9119ed7be"
  },
  {
   "t": "2026-06-22T13:36:54Z",
   "sha": "5647c188138ae03cdb15db7a99b7e6b160bb9ba0"
  }
 ],
 "additions": 61,
 "deletions": 6,
 "changed_files": 1,
 "commit_count": 1,
 "size_bucket": "S",
 "mergeable_state": "clean",
 "bot": {
  "drahtbot": {
   "present": true,
   "reviews": {
    "stale_ack": [
     {
      "login": "w0xlt",
      "url": "https://github.com/bitcoin/bitcoin/pull/32278#pullrequestreview-2776535326"
     }
    ]
   },
   "conflicts": [
    {
     "number": 35600,
     "title": "net: prevent duplication manual connections (take 2)",
     "author": "willcl-ark"
    }
   ]
  }
 },
 "acks_parsed": {
  "w0xlt": {
   "kind": "ack",
   "hash": null,
   "t": "2025-04-17T17:52:49Z",
   "stale": true
  }
 },
 "acks_tally": {
  "ack": 0,
  "stale_ack": 1,
  "concept_ack": 0,
  "approach_ack": 0,
  "nack": 0,
  "concept_nack": 0,
  "approach_nack": 0
 },
 "reviews": {
  "approved": 0,
  "changes_requested": 0,
  "distinct_reviewers": [
   "ajtowns",
   "laanwj",
   "sedited",
   "w0xlt"
  ]
 },
 "signals": {
  "needs_rebase": false,
  "ci_failed": false,
  "mergeable_state": "clean",
  "last_author_activity": "2026-06-22T13:37:25Z",
  "last_reviewer_activity": "2026-09-04T07:55:23Z",
  "last_reviewer": "sedited",
  "author_silent_days": 87,
  "waiting_on_author_days": 13,
  "days_since_update": 13
 },
 "refs": {
  "mentioned": [],
  "depends_on": [],
  "fixes": [],
  "linked_issues": [],
  "references": [],
  "conflicts": [
   35600
  ]
 },
 "stack": {
  "shares_commits_with": [],
  "based_on": [],
  "base_for": []
 },
 "review_paths": [
  "src/net.h"
 ],
 "body": "Document the requirements around the `NetEventsInterface`'s methods and the lifetime of `CNode` objects in `CConnman::m_nodes`.",
 "commits": [
  {
   "sha": "5647c188138ae03cdb15db7a99b7e6b160bb9ba0",
   "date": "2026-06-22T13:33:36Z",
   "message": "doc: better document NetEventsInterface and the deletion of \"CNode\"s\n\nDocument the requirements around the `NetEventsInterface`'s methods and\nthe lifetime of `CNode` objects in `CConnman::m_nodes`.\n\nCo-authored-by: Anthony Towns <aj@erisian.com.au>"
  }
 ],
 "timeline": [
  {
   "t": "2025-04-16T04:11:30Z",
   "kind": "force_push",
   "who": "vasild",
   "commit": "0f26ac35e26c0da0b0ff75c497fe5fe5bdc38a2d"
  },
  {
   "t": "2025-04-16T04:15:21Z",
   "kind": "force_push",
   "who": "vasild",
   "commit": "e44e669378f2c63b09eda68797039b73047febff"
  },
  {
   "t": "2025-04-16T04:16:18Z",
   "kind": "comment",
   "who": "vasild",
   "assoc": "MEMBER",
   "text": "`1091faf8ff...0f26ac35e2` and `0f26ac35e2...e44e669378`: further elaborate how we safely access `CNode`s in `m_nodes` and how we avoid `CNode` destruction while it is being referenced."
  },
  {
   "t": "2025-04-17T17:52:49Z",
   "kind": "review",
   "who": "w0xlt",
   "assoc": "CONTRIBUTOR",
   "state": "COMMENTED",
   "commit": "e44e669378f2c63b09eda68797039b73047febff",
   "text": "ACK https://github.com/bitcoin/bitcoin/pull/32278/commits/e44e669378f2c63b09eda68797039b73047febff\n\nClear improvement in documentation."
  },
  {
   "t": "2025-10-23T13:48:35Z",
   "kind": "review_comment",
   "who": "laanwj",
   "assoc": "MEMBER",
   "path": "src/net.h",
   "commit": "e44e669378f2c63b09eda68797039b73047febff",
   "in_reply_to": null,
   "text": "What do you mean with \"(without a help from the standard library)\"?"
  },
  {
   "t": "2025-10-29T17:51:17Z",
   "kind": "review_comment",
   "who": "ajtowns",
   "assoc": "MEMBER",
   "path": "src/net.h",
   "commit": "e44e669378f2c63b09eda68797039b73047febff",
   "in_reply_to": null,
   "text": "I think this would be better phrased as requirements for implementers of the interface, rather than the user of the interface. ie: \"For a given `CNode`, the methods will be called in the following order:\".  (Both `CNode` and `NetEventsInterface` are interfaces the net module offers, so the appropriate documentation is how they work and what you need to do to implement NetEventsInterface, not how net.cpp needs to be implemented)"
  },
  {
   "t": "2025-10-29T18:03:37Z",
   "kind": "review_comment",
   "who": "ajtowns",
   "assoc": "MEMBER",
   "path": "src/net.h",
   "commit": "e44e669378f2c63b09eda68797039b73047febff",
   "in_reply_to": 2455209415,
   "text": "I'd phrase this as:\n\nDestroying objects from this list works as follows (see DisconnectNodes(), DeleteNode()):\n * we will close the socket, release locks, and reset global info relating to the connection\n * the node will be moved from `m_nodes` to `m_nodes_disconnected`, preventing future calls to `ProcessMessages()` and `SendMessages()` for this node, and decrementing the reference count\n * we will wait for GetRefCount() to return `<= 0` indicating there are no other references to this node in use (and hence no current calls to `ProcessMessages` or `SendMessages`)\n * the node will be removed from m_nodes_disconnected\n * `FinalizeNode()` will be called to indicate the node is about to be destroyed\n * the `CNode` is deleted"
  },
  {
   "t": "2025-10-29T21:28:47Z",
   "kind": "review_comment",
   "who": "ajtowns",
   "assoc": "MEMBER",
   "path": "src/net.h",
   "commit": "5647c188138ae03cdb15db7a99b7e6b160bb9ba0",
   "in_reply_to": null,
   "text": "Perhaps document how we prevent concurrent access to this while you're at it? (We can't use `GUARDED_BY(m_nodes_mutex)` since that results in lock order issues with cs_main)\n\nAIUI, accesses are:\n\n * `DisconnectNodes()` via `ThreadSocketHandler()` which adds nodes and removes them in normal operation\n * `StopNodes()` via `Stop()` which runs it after `StopThreads()`, which ensures `threadSocketHandler` is joined before returning. `Stop()` is invoked in `~CConnman()` and `init.cpp:Shutdown()`\n\n[EDIT: Adding a `m_disconnected_nodes_mutex` that is locked in `ThreadSocketHandler()` and `StopNodes()` would also be feasible afaics, though if we're doing a rewrite just documenting why it works now also seems fine]"
  },
  {
   "t": "2025-11-13T15:42:46Z",
   "kind": "force_push",
   "who": "vasild",
   "commit": "110548c9eabc0bdd1341e4aafe9fe3f9119ed7be"
  },
  {
   "t": "2025-11-13T15:42:56Z",
   "kind": "comment",
   "who": "vasild",
   "assoc": "MEMBER",
   "text": "`e44e669378...110548c9ea`: take suggestions"
  },
  {
   "t": "2025-11-13T15:45:01Z",
   "kind": "review_comment",
   "who": "vasild",
   "assoc": "MEMBER",
   "path": "src/net.h",
   "commit": "e44e669378f2c63b09eda68797039b73047febff",
   "in_reply_to": 2455209415,
   "text": "[quoted text omitted]\n\nI meant without using `shared_ptr`, but surely we do use the standard library for other things. Removed this sentence altogether.\n\n@ajtowns I took that wording, thanks! Since I copied it right away, I added you as co-author of the commit. Let me know if you do not want that."
  },
  {
   "t": "2025-11-13T15:45:26Z",
   "kind": "review_comment",
   "who": "vasild",
   "assoc": "MEMBER",
   "path": "src/net.h",
   "commit": "e44e669378f2c63b09eda68797039b73047febff",
   "in_reply_to": 2474399807,
   "text": "Changed."
  },
  {
   "t": "2025-11-13T15:46:20Z",
   "kind": "review_comment",
   "who": "vasild",
   "assoc": "MEMBER",
   "path": "src/net.h",
   "commit": "5647c188138ae03cdb15db7a99b7e6b160bb9ba0",
   "in_reply_to": 2475563895,
   "text": "Good idea! Added some brief explanation amongst those lines, thanks!"
  },
  {
   "t": "2026-06-19T11:11:21Z",
   "kind": "comment",
   "who": "sedited",
   "assoc": "MEMBER",
   "text": "@vasild can you rebase this?"
  },
  {
   "t": "2026-06-22T13:36:54Z",
   "kind": "force_push",
   "who": "vasild",
   "commit": "5647c188138ae03cdb15db7a99b7e6b160bb9ba0"
  },
  {
   "t": "2026-06-22T13:37:25Z",
   "kind": "comment",
   "who": "vasild",
   "assoc": "MEMBER",
   "text": "`110548c9eabc0bdd1341e4aafe9fe3f9119ed7be...5647c188138ae03cdb15db7a99b7e6b160bb9ba0`: rebase due to conflicts, thanks for the ping!"
  },
  {
   "t": "2026-09-04T07:55:23Z",
   "kind": "comment",
   "who": "sedited",
   "assoc": "MEMBER",
   "text": "The last review for this change is nearly a year old. Maybe this is not interesting enough to reviewers and should be closed? These kind of documentation changes might also be less popular, since an LLM might be able to give a similar description."
  }
 ],
 "labels_log": [
  {
   "t": "2025-04-15T16:06:12Z",
   "action": "labeled",
   "label": "Docs",
   "who": "DrahtBot"
  },
  {
   "t": "2025-04-28T22:34:51Z",
   "action": "labeled",
   "label": "CI failed",
   "who": "DrahtBot"
  },
  {
   "t": "2025-05-02T05:16:08Z",
   "action": "unlabeled",
   "label": "CI failed",
   "who": "DrahtBot"
  },
  {
   "t": "2026-02-07T01:47:14Z",
   "action": "labeled",
   "label": "Needs rebase",
   "who": "DrahtBot"
  },
  {
   "t": "2026-06-22T14:27:25Z",
   "action": "unlabeled",
   "label": "Needs rebase",
   "who": "DrahtBot"
  },
  {
   "t": "2026-06-22T15:45:28Z",
   "action": "labeled",
   "label": "CI failed",
   "who": "DrahtBot"
  },
  {
   "t": "2026-06-26T11:55:06Z",
   "action": "unlabeled",
   "label": "CI failed",
   "who": "DrahtBot"
  }
 ],
 "state_log": [],
 "text_chars": 3548,
 "text_tokens_estimate": 887,
 "changed_paths": [
  "src/net.h"
 ],
 "files": [
  {
   "path": "src/net.h",
   "add": 61,
   "del": 6
  }
 ],
 "test_lines": 0,
 "git": {
  "head": "5647c188138ae03cdb15db7a99b7e6b160bb9ba0",
  "head_matches_backup": true,
  "base": "9c20859b5f0db428c293d4f29196854a506c3b06",
  "commits": [
   {
    "sha": "5647c18813",
    "subject": "doc: better document NetEventsInterface and the deletion of \"CNode\"s",
    "files": 1,
    "add": 61,
    "del": 6
   }
  ],
  "patch_truncated": false
 },
 "input_hash": "fc005dbddbcca124",
 "extracted_at": "2026-09-17T16:15:31+00:00"
}