refactor: move index class members from protected to private #24150

pull jonatack wants to merge 8 commits into bitcoin:master from jonatack:move-index-class-members-from-protected-to-private changing 8 files +83 −76
  1. jonatack commented at 12:45 pm on January 25, 2022: contributor

    Simplify the index base and child classes and improve encapsulation and clarity by making fully overridden virtual member functions private. In the child classes, this allows having only public and private members. This change also help contributors add virtual functions into the correct section. Also rename the GetName() getters to GetIndexName() for clarity and easier grepping/reviewing.

    Some context:

    A base class virtual function doesn’t need to be accessible to be overridden, but it can only be private if fully overridden, e.g. no inherited base implementation is used by the child classes.

    References:

    • https://en.cppreference.com/w/cpp/language/virtual: “Base::vf does not need to be accessible or visible to be overridden. (Base::vf can be declared private, or Base can be inherited using private inheritance.)”

    • “An implementation member should be protected if it provides an operation or data that a derived class will need to use in its own implementation. Otherwise, implementation members should be private.” - C++ Primer (Lippman, Lajoie, Moo)

    • Herb Sutter in http://www.gotw.ca/publications/mill18.htm: “Make virtual functions private, and only if derived classes need to invoke the base implementation of a virtual function, make the virtual function protected. Prefer to make interfaces non-virtual using the Template pattern.”

  2. DrahtBot added the label Refactoring on Jan 25, 2022
  3. DrahtBot added the label UTXO Db and Indexes on Jan 25, 2022
  4. DrahtBot commented at 0:13 am on January 26, 2022: contributor

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

    Reviews

    See the guideline for information on the review process.

    Type Reviewers
    Concept ACK PastaPastaPasta, aureleoules
    Stale ACK RandyMcMillan, w0xlt, brunoerg

    If your review is incorrectly listed, please react with 👎 to this comment and the bot will ignore it on the next update.

    Conflicts

    Reviewers, this pull request conflicts with the following ones:

    • #25494 (indexes: Stop using node internal types 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.

  5. PastaPastaPasta approved
  6. PastaPastaPasta commented at 4:34 am on February 1, 2022: contributor
    utACK 732fafc975aaaabaf9373b8c31cb0952698fee60, it makes sense to me to make stuff private instead of protected where possible
  7. RandyMcMillan commented at 2:17 am on February 12, 2022: contributor
    commit 7a8d2c0 scripted-diff tACK Recreated here: https://cirrus-ci.com/build/4937613508345856 (with gsed on macOS) Tested on macOS (Darwin ₿ 19.6.0 Darwin Kernel Version 19.6.0: x86_64)
  8. RandyMcMillan commented at 2:39 am on February 12, 2022: contributor

    commit 5743fa6 - Approach ACK https://cirrus-ci.com/build/6508504977506304

    NIT: since this is a refactor - Can we bring base.h into clang-format compliance? https://cirrus-ci.com/build/5869934608646144 commit https://github.com/RandyMcMillan/bitcoin/commit/22f74b83bf568d3e9e93814a4634f5ec304208ba

     0diff --git a/src/index/base.h b/src/index/base.h
     1index 9c4d67865a..44d87f8556 100644
     2--- a/src/index/base.h
     3+++ b/src/index/base.h
     4@@ -33,7 +33,7 @@ protected:
     5      * A locator is used instead of a simple hash of the chain tip because blocks
     6      * and block index entries may not be flushed to disk until after this database
     7      * is updated.
     8-    */
     9+     */
    10     class DB : public CDBWrapper
    11     {
    12     public:
    
  9. jonatack commented at 5:04 pm on February 13, 2022: contributor
    Thanks for reviewing @RandyMcMillan. It isn’t part of the changes here but happy to if I have to repush. Edit: done.
  10. DrahtBot added the label Needs rebase on Mar 9, 2022
  11. jonatack force-pushed on Mar 9, 2022
  12. jonatack force-pushed on Mar 9, 2022
  13. jonatack commented at 2:13 pm on March 9, 2022: contributor

    Rebased per git range-diff 7003b6a 732fafc 7785095 and took suggestion in #24150 (comment).

    Invalidates previous ACKs by @PastaPastaPasta and @RandyMcMillan; mind re-ACKing?

  14. DrahtBot removed the label Needs rebase on Mar 9, 2022
  15. jonatack commented at 9:31 am on April 15, 2022: contributor
    @PastaPastaPasta and @RandyMcMillan, would you mind re-ACKing here?
  16. PastaPastaPasta approved
  17. PastaPastaPasta commented at 7:09 pm on April 15, 2022: contributor
    re-utACK
  18. RandyMcMillan commented at 10:25 pm on April 15, 2022: contributor

    tACK 77850955b8504638ebcbe8368078c0531ebfc24a

    tested on

    Darwin ₿ 19.6.0 Darwin Kernel Version 19.6.0: Sun Nov 14 19:58:51 PST 2021; root:xnu-6153.141.50~1/RELEASE_X86_64 x86_64

  19. brunoerg approved
  20. brunoerg commented at 7:47 pm on April 18, 2022: contributor

    ACK 77850955b8504638ebcbe8368078c0531ebfc24a

    Agreed on updating them to private and changing from GetName to GetIndexName seems better to understand it.

  21. DrahtBot added the label Needs rebase on Apr 26, 2022
  22. jonatack force-pushed on Apr 28, 2022
  23. DrahtBot removed the label Needs rebase on Apr 28, 2022
  24. jonatack force-pushed on Apr 28, 2022
  25. scripted-diff: rename GetName() to GetIndexName() in src/index
    to improve grepping for a more specific function name.
    
    -BEGIN VERIFY SCRIPT-
    sed -i 's/GetName/GetIndexName/g' ./src/index/*
    -END VERIFY SCRIPT-
    51d043fa2e
  26. index, refactor: move GetIndexName() getters from protected to private
    and add doxygen comments
    dcce3efc6c
  27. index, refactor: move WriteBlock() from protected to private
    and add doxygen comments, and touch up doxygen indentation on one line per
    review request
    92856cf638
  28. index, refactor: move GetDB() from protected to private ef0636f89c
  29. index, refactor: move TxIndex::DB from protected to private 2dc442fd84
  30. index, refactor: move Init(), CommitInternal() and Rewind() to private 400cac1c34
  31. index, refactor: move SetBestBlockIndex() to private
    and fix some clang formatting
    4fdd404e65
  32. jonatack force-pushed on Apr 28, 2022
  33. jonatack force-pushed on Apr 28, 2022
  34. jonatack commented at 7:34 pm on April 28, 2022: contributor
    Rebased (see git range-diff dabec990 cff04a7 4fdd404) and added 4fdd404e652ca6443f666c05341ccb775f461350 left over from an unintentional reverted change in #21726. @PastaPastaPasta, @RandyMcMillan and @brunoerg, mind re-ACKing? Thanks :heart:
  35. brunoerg approved
  36. brunoerg commented at 7:37 pm on April 28, 2022: contributor
    re-ACK 4fdd404e652ca6443f666c05341ccb775f461350
  37. in src/index/base.h:89 in 4fdd404e65 outdated
    84+    virtual bool WriteBlock(const CBlock& block, const CBlockIndex* pindex) { return true; }
    85+
    86+    /// Update the internal best block index as well as the prune lock.
    87+    void SetBestBlockIndex(const CBlockIndex* block);
    88+
    89+    /// Get the name of the index for display in logs.
    


    laanwj commented at 12:11 pm on May 9, 2022:
    I’m kind of confused by this; it’s (like GetDB()) a method that child classes are supposed to override. What does it mean for it to be private?

    jonatack commented at 9:05 am on May 10, 2022:

    Thanks for reviewing! Great question. It looks to me that a base class virtual method doesn’t need to be accessible to be overridden, but it can only be private if fully overridden, e.g. no inherited base implementation is used by the child classes. I’m no OOP guru but noticed it while working on this change and looked around the literature a bit.

    References:

    • https://en.cppreference.com/w/cpp/language/virtual: “Base::vf does not need to be accessible or visible to be overridden”

    • “An implementation member should be protected if it provides an operation or data that a derived class will need to use in its own implementation. Otherwise, implementation members should be private.” - C++ Primer (Lippman, Lajoie, Moo)


    jonatack commented at 9:12 am on May 10, 2022:
    Updated the OP with this context.

    laanwj commented at 9:14 am on May 10, 2022:

    Thanks for looking it up! I have no objection to doing it this way, but it’s a dusty corner of C++ to me.

    We might want to move the methods that are intended to (or, must) be overridden by child classes together in the class declaration, for documentation purposes.


    jonatack commented at 9:39 am on May 10, 2022:

    Thanks for looking it up! I have no objection to doing it this way, but it’s a dusty corner of C++ to me.

    We might want to move the methods that are intended to (or, must) be overridden by child classes together in the class declaration, for documentation purposes.

    Done!

  38. w0xlt approved
  39. brunoerg commented at 9:08 pm on May 19, 2022: contributor
    re-ACK f5e985b4b5fcaf6b6341156b00725e8f32373ac4
  40. index, refactor: document and group BaseIndex virtual functions
    in the class declaration by access and characteristic
    for clarity and documentation purposes.
    3f26a3666c
  41. jonatack force-pushed on May 20, 2022
  42. jonatack commented at 10:07 am on May 20, 2022: contributor

    Updated the motivation in the PR description and simplified the last commit by dropping the class-to-struct change, per git diff f5e985b 3f26a36

     0--- a/src/index/base.h
     1+++ b/src/index/base.h
     2@@ -57,8 +57,9 @@ protected:
     3      * and block index entries may not be flushed to disk until after this database
     4      * is updated.
     5      */
     6-    struct DB : public CDBWrapper
     7+    class DB : public CDBWrapper
     8     {
     9+    public:
    10         DB(const fs::path& path, size_t n_cache_size,
    11            bool f_memory = false, bool f_wipe = false, bool f_obfuscate = false);
    
  43. in src/index/base.h:31 in 3f26a3666c
    25@@ -26,14 +26,37 @@ struct IndexSummary {
    26  */
    27 class BaseIndex : public CValidationInterface
    28 {
    29+public:
    30+    /// Destructor interrupts sync thread if running and blocks until it exits.
    31+    virtual ~BaseIndex();
    


    bvbfan commented at 4:23 pm on June 24, 2022:
    You don’t need to mark it virtual, there is a bug and it is destructor of CValidationInterface should marked as virtual
  44. DrahtBot added the label Needs rebase on Jul 19, 2022
  45. DrahtBot commented at 9:16 pm on July 19, 2022: contributor

    🐙 This pull request conflicts with the target branch and needs rebase.

    Want to unsubscribe from rebase notifications on this pull request? Just convert this pull request to a “draft”.

  46. achow101 commented at 6:58 pm on October 12, 2022: member
    Are you still working on this?
  47. achow101 commented at 5:13 pm on November 10, 2022: member
    Closing this as it has not had any activity in a while. If you are interested in continuing work on this, please leave a comment so that it can be reopened.
  48. achow101 closed this on Nov 10, 2022

  49. jonatack commented at 5:15 pm on November 10, 2022: contributor

    Are you still working on this?

    Yes. Might be useful to re-open rather than opening a new one, as there is discussion and some feedback to address.

  50. achow101 reopened this on Nov 10, 2022

  51. aureleoules commented at 12:44 pm on November 11, 2022: member
    Concept ACK
  52. fanquake marked this as a draft on Feb 6, 2023
  53. fanquake commented at 2:58 pm on February 6, 2023: member
    Moved to draft for now. Was reopened 3 months ago to continue work / follow up on discussion, but hasn’t been touched. Has needed rebase for 6 months.
  54. jonatack commented at 11:08 am on April 25, 2023: contributor
    Closing temporarily so that I can re-open it – am still interested to work on this.
  55. jonatack closed this on Apr 25, 2023

  56. bitcoin locked this on Apr 24, 2024

github-metadata-mirror

This is a metadata mirror of the GitHub repository bitcoin/bitcoin. This site is not affiliated with GitHub. Content is generated from a GitHub metadata backup.
generated: 2024-07-05 19:13 UTC

This site is hosted by @0xB10C
More mirrored repositories can be found on mirror.b10c.me