diff options
author | m-holger <m-holger@kubitscheck.org> | 2023-06-13 11:53:35 +0200 |
---|---|---|
committer | m-holger <m-holger@kubitscheck.org> | 2023-06-17 15:38:20 +0200 |
commit | d8bbe46eaa6386ac3900a8d75ce7621889bca1f6 (patch) | |
tree | e77ac81ca2cdc9ad7b2ef2d70a7513c5a8b283a4 | |
parent | 8cb89529bd52ab40f5cf93024f6fbf6c0ef52f56 (diff) | |
download | qpdf-d8bbe46eaa6386ac3900a8d75ce7621889bca1f6.tar.zst |
Update README-maintainer section on use of Member pattern
-rw-r--r-- | README-maintainer.md | 30 |
1 files changed, 20 insertions, 10 deletions
diff --git a/README-maintainer.md b/README-maintainer.md index 4f11fdcf..254c248f 100644 --- a/README-maintainer.md +++ b/README-maintainer.md @@ -235,16 +235,26 @@ Building docs from pull requests is also enabled. // README-maintainer ``` -* Put private member variables in std::shared_ptr<Members> for all - public classes. Remember to use QPDF_DLL on ~Members(). Exception: - indirection through std::shared_ptr<Members> is expensive, so don't - do it for classes that are copied a lot, like QPDFObjectHandle and - QPDFObject. It may be possible to declare - std::shared_ptr<Members> m_ph; - Member* m; - with m = m_ph.get(), and then indirect through m in - performance-critical settings, though in 2022, std::shared_ptr is - sufficiently performant that this may not be worth it. +* Put private member variables in std::unique_ptr<Members> for all + public classes. Forward declare Members in the header file and define + Members in the implementation file. One of the major benefits of + defining Members in the implementation file is that it makes it easier + to use private classes as data members and simplifies the include order. + Remember that Members must be fully defined before the destructor of the + main class. For an example of this pattern see class JSONHandler. + + Exception: indirection through std::unique_ptr<Members> incurs an overhead, + so don't do it for: + * (especially private) classes that are copied a lot, like QPDFObjectHandle + and QPDFObject. + * classes that are a shared pointer to another class, such as QPDFObjectHandle + or JSON. + + For exported classes that do not use the member pattern for performance + reasons it is worth considering adding a std::unique_ptr to an empty Members + class initialized to nullptr to give the flexibility to add data members + without breaking the ABI. + * Traversal of objects is expensive. It's worth adding some complexity to avoid needless traversals of objects. |