doc: Add comments to FIELD_* constants in proxy.h - #279
Conversation
|
The following sections might be updated with supplementary metadata relevant to reviewers and maintainers. ReviewsSee the guideline for information on the review process.
If your review is incorrectly listed, please copy-paste ConflictsReviewers, this pull request conflicts with the following ones:
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. |
| static constexpr int FIELD_IN = 1; //!< Field is read from the Cap'n Proto Params struct (client -> server). | ||
| static constexpr int FIELD_OUT = 2; //!< Field is read from the Cap'n Proto Results struct (server -> client). |
There was a problem hiding this comment.
In commit "doc: Add comments to FIELD_* constants in proxy.h" (d706480)
I think it would be better to say "present" instead of "read". "read" is accurate but these flags are used to decide whether to write fields as well, so "present" reflects the wider context
| static constexpr int FIELD_OPTIONAL = 4; | ||
| static constexpr int FIELD_REQUESTED = 8; | ||
| static constexpr int FIELD_BOXED = 16; | ||
| static constexpr int FIELD_IN = 1; //!< Field is read from the Cap'n Proto Params struct (client -> server). |
There was a problem hiding this comment.
In commit "doc: Add comments to FIELD_* constants in proxy.h" (d706480)
I think it would be better to move these comments to the Accessor struct below where they are used, and written as preceding comments (//!) trailing comments (//!<) so there is more space for the descriptions.
Could keep //!< comments here referring to the Accessor struct below though.
| static constexpr int FIELD_BOXED = 16; | ||
| static constexpr int FIELD_IN = 1; //!< Field is read from the Cap'n Proto Params struct (client -> server). | ||
| static constexpr int FIELD_OUT = 2; //!< Field is read from the Cap'n Proto Results struct (server -> client). | ||
| static constexpr int FIELD_OPTIONAL = 4; //!< Field has a `has<Field>` sibling in the Cap'n Proto schema; value may be absent and presence must be checked via `has()`. |
There was a problem hiding this comment.
In commit "doc: Add comments to FIELD_* constants in proxy.h" (d706480)
Would replace the word "schema" with "struct" to be more specific. Also has<Field> looks like c++ template syntax which could be confusing. And I'm not sure the "presence must be checked" comment is meaningful because it seems focused on reading the field when the flag controls how the field needs to be written as well as read.
Would suggest something more like "Field has a companion has{Name} boolean field in the Cap'n Proto struct. This used to represent optional primitive values (e.g. C++ std::optional<int>) because Cap'n Proto doesn't allow primitive fields to be unset."
| static constexpr int FIELD_IN = 1; //!< Field is read from the Cap'n Proto Params struct (client -> server). | ||
| static constexpr int FIELD_OUT = 2; //!< Field is read from the Cap'n Proto Results struct (server -> client). | ||
| static constexpr int FIELD_OPTIONAL = 4; //!< Field has a `has<Field>` sibling in the Cap'n Proto schema; value may be absent and presence must be checked via `has()`. | ||
| static constexpr int FIELD_REQUESTED = 8; //!< Field has a `want<Field>` sibling in the Cap'n Proto Params struct; client opts in to receiving it. |
There was a problem hiding this comment.
In commit "doc: Add comments to FIELD_* constants in proxy.h" (d706480)
This doesn't really say what the flag is used for. Maybe would write "Results field has a companion want{Name} boolean field in the Params struct. Used for optional output parameters (e.g. C++ int*) and set to true if the caller passed a non-null and wants the result."
| static constexpr int FIELD_OUT = 2; //!< Field is read from the Cap'n Proto Results struct (server -> client). | ||
| static constexpr int FIELD_OPTIONAL = 4; //!< Field has a `has<Field>` sibling in the Cap'n Proto schema; value may be absent and presence must be checked via `has()`. | ||
| static constexpr int FIELD_REQUESTED = 8; //!< Field has a `want<Field>` sibling in the Cap'n Proto Params struct; client opts in to receiving it. | ||
| static constexpr int FIELD_BOXED = 16; //!< Field is a Cap'n Proto pointer type (struct, list, text, data, interface); value may be absent and presence must be checked via `has()`. |
There was a problem hiding this comment.
In commit "doc: Add comments to FIELD_* constants in proxy.h" (d706480)
I think absense/presence is not really relevant here. Would suggest something more like "Field is a Cap'n Proto pointer type (struct, list, text, data, interface) as opposed to a primitive type (bool, int, float, enum)."
d706480 to
e863c6c
Compare
|
Forced-push e863c6c to add suggested changes |
| template <typename Field, int flags> | ||
| struct Accessor : public Field | ||
| { | ||
| //! Field is present from the Cap'n Proto Params struct (client -> server). |
There was a problem hiding this comment.
In commit "doc: Add comments to FIELD_* constants in proxy.h" (e863c6c)
IMO "present in" would sound more natural than "present from" but this seems ok
There was a problem hiding this comment.
I agree. Thanks for the feedback
8412fcdc65 Merge bitcoin-core/libmultiprocess#295: Mark Waiter m_cv as guarded by m_mutex 1593ee2d18 Merge bitcoin-core/libmultiprocess#294: test: Add passDouble smoke test 9885d7dd33 Merge bitcoin-core/libmultiprocess#286: proxy-client: fix TSan data race in clientDestroy fa35501c4f Mark Waiter m_cv as guarded by m_mutex faaedb11f8 test: Add passDouble smoke test 733c64318d Merge bitcoin-core/libmultiprocess#292: type-number: fix clang-tidy modernize-use-nullptr 9cc3479ab3 Merge bitcoin-core/libmultiprocess#291: cmake: Add `mp_headers` custom target 201abd9e3a Merge bitcoin-core/libmultiprocess#289: cmake: make target_capnp_sources use CURRENT dirs 99820c8aec Merge bitcoin-core/libmultiprocess#279: doc: Add comments to FIELD_* constants in proxy.h 73b985540c Merge bitcoin-core/libmultiprocess#278: doc: Fix and expand design.md e7e91b2e23 Merge bitcoin-core/libmultiprocess#277: Add std::unordered_set support and a helper BuildList to dedup list build handlers 91a951f59a tidy fix: modernize-use-nullptr 16362f42d0 cmake: Add `mp_headers` custom target 615a94fe3a cmake: document ONLY_CAPNP option in target_capnp_sources 90982f75c6 mpgen: iwyu changes required by previous commit 25bb3e67f3 proxy-client: fix TSan data race in clientDestroy 620f297f31 cmake: make target_capnp_sources use CURRENT dirs 9de4b885aa test: use camelCase + $Proxy.name for FooStruct fields 011b91793d type: add std::unordered_set support 20d19b9644 proxy: add BuildList helper and dedup map/set/vector build handlers e863c6cdf6 doc: Add comments to FIELD_* constants in proxy.h 18db0ab957 doc: Fix and expand design.md 61de697536 Merge bitcoin-core/libmultiprocess#273: proxy-client: tolerate exceptions from remote destroy during cleanup 9cec9d6ca5 Merge bitcoin-core/libmultiprocess#243: mpgen: support primitive std::optional struct fields 4aaff11374 Merge bitcoin-core/libmultiprocess#238: cmake, ci: updates for recent nixpkgs 2ac55a56b5 Merge bitcoin-core/libmultiprocess#218: Better error and log messages 6de92e1c73 proxy-client: tolerate exceptions from remote destroy during cleanup 90be8354d4 test: regression for ~ProxyClient destroy after peer disconnect 3c69d125a1 Merge bitcoin-core/libmultiprocess#260: event loop: tolerate unexpected exceptions in `post()` callbacks b8a48c65e6 event loop: tolerate unexpected exceptions in `post()` callbacks f787863d2c Merge bitcoin-core/libmultiprocess#270: doc: Bump version 10 > 11 a22f602910 doc: Bump version 10 > 11 4eae445d6d debug: Add TypeName() function and log statements for Proxy objects being created and destroyed f326c5b1b7 logging: Add better logging on IPC server-side failures 6dbfa56a04 mpgen: support primitive std::optional struct fields 8d1277deb5 mpgen refactor: add AccessorType function db716bbcba mpgen refactor: Move field handling code to FieldList class db7acb3ce2 ci: Fix shell.nix compatibility with CMake 4.0 91a7759a9a cmake: Fix IWYU in nix by adding CMAKE_CXX_IMPLICIT_INCLUDE_DIRECTORIES git-subtree-dir: src/ipc/libmultiprocess git-subtree-split: 8412fcdc659e1379f9b4dea896c26bc1c5f3afa8
16bf05d Merge bitcoin-core/libmultiprocess#302: refactor: rename EventLoop::m_num_clients to m_num_refs dd537da Merge bitcoin-core/libmultiprocess#301: test: recursive async IPC calls and cleanups 400291d Merge bitcoin-core/libmultiprocess#299: ci: remove libevent from Core CIs 092be51 Merge bitcoin-core/libmultiprocess#285: Add ReadList helper 5b61788 Merge bitcoin-core/libmultiprocess#283: Add `makePool` method on `ThreadMap` d499830 refactor: rename EventLoop::m_num_clients to m_num_refs 6450345 type: reserve first when reading std::unordered_set 4d0f8db proxy: add ReadList helper and dedup map/set/vector read handlers 0e49d91 Add `makePool` method on `ThreadMap` 5519f7f test: recursive async IPC calls a29ceff ci: remove libevent from Core CIs 8412fcd Merge bitcoin-core/libmultiprocess#295: Mark Waiter m_cv as guarded by m_mutex 1593ee2 Merge bitcoin-core/libmultiprocess#294: test: Add passDouble smoke test 9885d7d Merge bitcoin-core/libmultiprocess#286: proxy-client: fix TSan data race in clientDestroy fa35501 Mark Waiter m_cv as guarded by m_mutex faaedb1 test: Add passDouble smoke test 733c643 Merge bitcoin-core/libmultiprocess#292: type-number: fix clang-tidy modernize-use-nullptr 9cc3479 Merge bitcoin-core/libmultiprocess#291: cmake: Add `mp_headers` custom target 201abd9 Merge bitcoin-core/libmultiprocess#289: cmake: make target_capnp_sources use CURRENT dirs 99820c8 Merge bitcoin-core/libmultiprocess#279: doc: Add comments to FIELD_* constants in proxy.h 73b9855 Merge bitcoin-core/libmultiprocess#278: doc: Fix and expand design.md e7e91b2 Merge bitcoin-core/libmultiprocess#277: Add std::unordered_set support and a helper BuildList to dedup list build handlers 91a951f tidy fix: modernize-use-nullptr 16362f4 cmake: Add `mp_headers` custom target 615a94f cmake: document ONLY_CAPNP option in target_capnp_sources 90982f7 mpgen: iwyu changes required by previous commit 25bb3e6 proxy-client: fix TSan data race in clientDestroy 620f297 cmake: make target_capnp_sources use CURRENT dirs 9de4b88 test: use camelCase + $Proxy.name for FooStruct fields 011b917 type: add std::unordered_set support 20d19b9 proxy: add BuildList helper and dedup map/set/vector build handlers e863c6c doc: Add comments to FIELD_* constants in proxy.h 18db0ab doc: Fix and expand design.md 61de697 Merge bitcoin-core/libmultiprocess#273: proxy-client: tolerate exceptions from remote destroy during cleanup 9cec9d6 Merge bitcoin-core/libmultiprocess#243: mpgen: support primitive std::optional struct fields 4aaff11 Merge bitcoin-core/libmultiprocess#238: cmake, ci: updates for recent nixpkgs 2ac55a5 Merge bitcoin-core/libmultiprocess#218: Better error and log messages 6de92e1 proxy-client: tolerate exceptions from remote destroy during cleanup 90be835 test: regression for ~ProxyClient destroy after peer disconnect 3c69d12 Merge bitcoin-core/libmultiprocess#260: event loop: tolerate unexpected exceptions in `post()` callbacks b8a48c6 event loop: tolerate unexpected exceptions in `post()` callbacks f787863 Merge bitcoin-core/libmultiprocess#270: doc: Bump version 10 > 11 a22f602 doc: Bump version 10 > 11 4eae445 debug: Add TypeName() function and log statements for Proxy objects being created and destroyed f326c5b logging: Add better logging on IPC server-side failures 6dbfa56 mpgen: support primitive std::optional struct fields 8d1277d mpgen refactor: add AccessorType function db716bb mpgen refactor: Move field handling code to FieldList class db7acb3 ci: Fix shell.nix compatibility with CMake 4.0 91a7759 cmake: Fix IWYU in nix by adding CMAKE_CXX_IMPLICIT_INCLUDE_DIRECTORIES git-subtree-dir: src/ipc/libmultiprocess git-subtree-split: 16bf05d
…ol` method 6b0a907 Squashed 'src/ipc/libmultiprocess/' changes from 3edbe8f..16bf05d (Ryan Ofsky) Pull request description: The changes can be verified by running `test/lint/git-subtree-check.sh src/ipc/libmultiprocess` as described in [developer notes](https://github.com/bitcoin/bitcoin/blob/master/doc/developer-notes.md#subtrees) and [lint instructions](https://github.com/bitcoin/bitcoin/tree/master/test/lint#git-subtree-checksh). Changes since last subtree update (#34977): - Adds `makePool` method on `ThreadMap` to support thread pool routing, allowing requests without a specific client thread to be dispatched to a pool using a shortest-queue strategy ([#283](bitcoin-core/libmultiprocess#283)). - Adds `std::unordered_set` support, a `BuildList` helper, and a `ReadList` helper to reduce duplication in list build and read handlers ([#277](bitcoin-core/libmultiprocess#277), [#285](bitcoin-core/libmultiprocess#285)). - Adds support for translating C++ `std::optional<T>` struct fields to pairs of `T` + `hasT :Bool` Cap'n Proto struct fields, allowing unset optional primitive fields to be represented ([#243](bitcoin-core/libmultiprocess#243)). - Produces more readable log output for Proxy object lifecycle events and IPC server-side failures ([#218](bitcoin-core/libmultiprocess#218)). - Handles exceptions thrown by `destroy` methods by logging instead of aborting ([#273](bitcoin-core/libmultiprocess#273)). This can prevent server crashes when non-libmultiprocess clients disconnect without destroying objects, in the case where a server object owns client objects and the server destructor tries to call the disconnected client to free them ([#219](bitcoin-core/libmultiprocess#219)). - Handles unexpected exceptions thrown by callbacks (that should never happen) by logging errors instead of deadlocking ([#260](bitcoin-core/libmultiprocess#260)). - Fixes a rare mptest hang on musl builds caused by a lost wakeup bug in `Waiter` ([#295](bitcoin-core/libmultiprocess#295)). - Fixes a race condition in a log print detected by TSan ([#286](bitcoin-core/libmultiprocess#286)). - Build improvements: makes `target_capnp_sources` work correctly when libmultiprocess is used as a CMake subproject ([#289](bitcoin-core/libmultiprocess#289)), adds `mp_headers` target for better lint tool support ([#291](bitcoin-core/libmultiprocess#291)), and fixes compatibility with recent Nix and CMake 4.0 ([#238](bitcoin-core/libmultiprocess#238)). - Test, CI, documentation, and minor code improvements: design document corrections ([#278](bitcoin-core/libmultiprocess#278)), field constant comments ([#279](bitcoin-core/libmultiprocess#279)), clang-tidy fix ([#292](bitcoin-core/libmultiprocess#292)), new smoke test for double-precision float values ([#294](bitcoin-core/libmultiprocess#294)), new test for recursive async IPC calls ([#301](bitcoin-core/libmultiprocess#301)), removal of libevent from Core CI builds ([#299](bitcoin-core/libmultiprocess#299)), and rename of `EventLoop::m_num_clients` to `m_num_refs` ([#302](bitcoin-core/libmultiprocess#302)). ACKs for top commit: fanquake: ACK 02afa66 hebasto: ACK 02afa66. Tree-SHA512: ef81a951c971f328a0a98436030467eeea30925eb6016eafd9bc7a25726c87628a852bbb1d84b88bce340aeea2bed25c65bc55db1168ebcb850628cd18808883
…hreadMap.makePool` method 6b0a907 Squashed 'src/ipc/libmultiprocess/' changes from 3edbe8f67c1..16bf05dea02 (Ryan Ofsky) Pull request description: The changes can be verified by running `test/lint/git-subtree-check.sh src/ipc/libmultiprocess` as described in [developer notes](https://github.com/bitcoin/bitcoin/blob/master/doc/developer-notes.md#subtrees) and [lint instructions](https://github.com/bitcoin/bitcoin/tree/master/test/lint#git-subtree-checksh). Changes since last subtree update (#34977): - Adds `makePool` method on `ThreadMap` to support thread pool routing, allowing requests without a specific client thread to be dispatched to a pool using a shortest-queue strategy ([#283](bitcoin-core/libmultiprocess#283)). - Adds `std::unordered_set` support, a `BuildList` helper, and a `ReadList` helper to reduce duplication in list build and read handlers ([#277](bitcoin-core/libmultiprocess#277), [#285](bitcoin-core/libmultiprocess#285)). - Adds support for translating C++ `std::optional<T>` struct fields to pairs of `T` + `hasT :Bool` Cap'n Proto struct fields, allowing unset optional primitive fields to be represented ([#243](bitcoin-core/libmultiprocess#243)). - Produces more readable log output for Proxy object lifecycle events and IPC server-side failures ([#218](bitcoin-core/libmultiprocess#218)). - Handles exceptions thrown by `destroy` methods by logging instead of aborting ([#273](bitcoin-core/libmultiprocess#273)). This can prevent server crashes when non-libmultiprocess clients disconnect without destroying objects, in the case where a server object owns client objects and the server destructor tries to call the disconnected client to free them ([#219](bitcoin-core/libmultiprocess#219)). - Handles unexpected exceptions thrown by callbacks (that should never happen) by logging errors instead of deadlocking ([#260](bitcoin-core/libmultiprocess#260)). - Fixes a rare mptest hang on musl builds caused by a lost wakeup bug in `Waiter` ([#295](bitcoin-core/libmultiprocess#295)). - Fixes a race condition in a log print detected by TSan ([#286](bitcoin-core/libmultiprocess#286)). - Build improvements: makes `target_capnp_sources` work correctly when libmultiprocess is used as a CMake subproject ([#289](bitcoin-core/libmultiprocess#289)), adds `mp_headers` target for better lint tool support ([#291](bitcoin-core/libmultiprocess#291)), and fixes compatibility with recent Nix and CMake 4.0 ([#238](bitcoin-core/libmultiprocess#238)). - Test, CI, documentation, and minor code improvements: design document corrections ([#278](bitcoin-core/libmultiprocess#278)), field constant comments ([#279](bitcoin-core/libmultiprocess#279)), clang-tidy fix ([#292](bitcoin-core/libmultiprocess#292)), new smoke test for double-precision float values ([#294](bitcoin-core/libmultiprocess#294)), new test for recursive async IPC calls ([#301](bitcoin-core/libmultiprocess#301)), removal of libevent from Core CI builds ([#299](bitcoin-core/libmultiprocess#299)), and rename of `EventLoop::m_num_clients` to `m_num_refs` ([#302](bitcoin-core/libmultiprocess#302)). ACKs for top commit: fanquake: ACK cd09e20 hebasto: ACK cd09e20. Tree-SHA512: ef81a951c971f328a0a98436030467eeea30925eb6016eafd9bc7a25726c87628a852bbb1d84b88bce340aeea2bed25c65bc55db1168ebcb850628cd18808883
…hreadMap.makePool` method 6b0a907 Squashed 'src/ipc/libmultiprocess/' changes from 3edbe8f67c1..16bf05dea02 (Ryan Ofsky) Pull request description: The changes can be verified by running `test/lint/git-subtree-check.sh src/ipc/libmultiprocess` as described in [developer notes](https://github.com/bitcoin/bitcoin/blob/master/doc/developer-notes.md#subtrees) and [lint instructions](https://github.com/bitcoin/bitcoin/tree/master/test/lint#git-subtree-checksh). Changes since last subtree update (#34977): - Adds `makePool` method on `ThreadMap` to support thread pool routing, allowing requests without a specific client thread to be dispatched to a pool using a shortest-queue strategy ([#283](bitcoin-core/libmultiprocess#283)). - Adds `std::unordered_set` support, a `BuildList` helper, and a `ReadList` helper to reduce duplication in list build and read handlers ([#277](bitcoin-core/libmultiprocess#277), [#285](bitcoin-core/libmultiprocess#285)). - Adds support for translating C++ `std::optional<T>` struct fields to pairs of `T` + `hasT :Bool` Cap'n Proto struct fields, allowing unset optional primitive fields to be represented ([#243](bitcoin-core/libmultiprocess#243)). - Produces more readable log output for Proxy object lifecycle events and IPC server-side failures ([#218](bitcoin-core/libmultiprocess#218)). - Handles exceptions thrown by `destroy` methods by logging instead of aborting ([#273](bitcoin-core/libmultiprocess#273)). This can prevent server crashes when non-libmultiprocess clients disconnect without destroying objects, in the case where a server object owns client objects and the server destructor tries to call the disconnected client to free them ([#219](bitcoin-core/libmultiprocess#219)). - Handles unexpected exceptions thrown by callbacks (that should never happen) by logging errors instead of deadlocking ([#260](bitcoin-core/libmultiprocess#260)). - Fixes a rare mptest hang on musl builds caused by a lost wakeup bug in `Waiter` ([#295](bitcoin-core/libmultiprocess#295)). - Fixes a race condition in a log print detected by TSan ([#286](bitcoin-core/libmultiprocess#286)). - Build improvements: makes `target_capnp_sources` work correctly when libmultiprocess is used as a CMake subproject ([#289](bitcoin-core/libmultiprocess#289)), adds `mp_headers` target for better lint tool support ([#291](bitcoin-core/libmultiprocess#291)), and fixes compatibility with recent Nix and CMake 4.0 ([#238](bitcoin-core/libmultiprocess#238)). - Test, CI, documentation, and minor code improvements: design document corrections ([#278](bitcoin-core/libmultiprocess#278)), field constant comments ([#279](bitcoin-core/libmultiprocess#279)), clang-tidy fix ([#292](bitcoin-core/libmultiprocess#292)), new smoke test for double-precision float values ([#294](bitcoin-core/libmultiprocess#294)), new test for recursive async IPC calls ([#301](bitcoin-core/libmultiprocess#301)), removal of libevent from Core CI builds ([#299](bitcoin-core/libmultiprocess#299)), and rename of `EventLoop::m_num_clients` to `m_num_refs` ([#302](bitcoin-core/libmultiprocess#302)). ACKs for top commit: fanquake: ACK 02afa66169b5dc58d0fc6f608d0c6f4facefd5ec hebasto: ACK 02afa66169b5dc58d0fc6f608d0c6f4facefd5ec. Tree-SHA512: ef81a951c971f328a0a98436030467eeea30925eb6016eafd9bc7a25726c87628a852bbb1d84b88bce340aeea2bed25c65bc55db1168ebcb850628cd18808883
Add documentation comments to the five
FIELD_*bit flag constants inproxy.h, which were previously undocumented