diff options
-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. |