dptr.h

   1 //d-ptr header
   2 //
   3 // (c) Konrad Rosenbaum, 2010-2011
   4 // Copying and distribution of this file, with or without modification,
   5 // are permitted in any medium without royalty provided the copyright
   6 // notice and this notice are preserved.  This file is offered as-is,
   7 // without any warranty.
   8
   9 #include "dptr_base.h"
  10
  11
  12 #ifndef DPTR_CLASS_H
  13 #define DPTR_CLASS_H
  14
  15 /** \mainpage Chester - d-pointers
  16
  17 Chester is an implementation of the Cheshire Cat idiom - also known as
  18 d-pointer, PImpl (Pointer IMPLementation), or opaqua data pointer.
  19 It hides the data of a class behind a "d" pointer.
  20
  21 This implementation takes away much of the bookkeeping work, like allocating
  22 and de-allocating the pointer.
  23
  24 All the files of Chester are copyrighted under a permissive license:
  25  Copying and distribution of this file, with or without modification,
  26  are permitted in any medium without royalty provided the copyright
  27  notice and this notice are preserved.  This file is offered as-is,
  28  without any warranty.
  29
  30 So, you are free to use this implementation in any project under any kind of
  31 license as long as you do not remove my copyright notice.
  32
  33 Although I do not require it, I would appreciate feedback on problems, bugs,
  34 and the occasional code improvement - if you feel like it...
  35
  36 Different versions of Chester can be mixed for different classes, but the same version must be used both in the header file and in the implementation of the same class.
  37
  38 \section kinds Kinds of D-Pointers
  39
  40 Cheshire cats or d-pointers allow you to hide the data members (and if you want some of the implementation) of a class and also allow (within some constraints) to maintain ABI compatibility (ABI=Application Binary Interface) while adding or removing hidden data members.
  41
  42 Chester defines three different kinds of d-pointers: non-copy, non-shared, and shared. Those three define different access patterns to the d-pointer.
  43
  44 Non-copy d-pointers cannot be copied directly, if you want to make your main class copyable you have to explicitly create a copy constructor and/or an assignment operator. Those should be used with main classes and data objects that cannot be copied (like Qt's QObject and its subclasses).
  45
  46 Non-shared d-pointers can be copied - if you copy an instance of the main class, the content of the d-pointer gets copied automatically (at least if you use the automatic copy constructor or call the copy constructor of the d-pointer). Each copy acts independently. This version produces the same behavior as if the data was defined directly in the main class instead of inside the d-pointer.
  47
  48 Shared d-pointers can also be copied, but copying shares the data between instances of the main class. This can be used to create interface classes in which all copied instances share their data.
  49
  50 All three kinds share the usage pattern. The header file and class interface declaration is declared like this (this example uses non-shared d-pointers):
  51 \code
  52 //file: myclass.h
  53
  54 #include <DPtrBase>
  55
  56 class MyClass
  57 {
  58   DECLARE_DPTR(d)
  59   public:
  60     void myFunction();
  61 };
  62 \endcode
  63
  64 The actual implementation file then declares and defines the d-pointer class:
  65 \code
  66 //file: myclass.cpp
  67
  68 #include "myclass.h"
  69 #include <DPtr>
  70
  71 class DPTR_CLASS_NAME(MyClass):public DPtr
  72 {
  73   public:
  74     int myint;
  75 };
  76 DEFINE_DPTR(MyClass)
  77
  78 void MyClass::myFunction()
  79 {
  80   d->myint = 99;
  81 }
  82
  83 main()
  84 {
  85   MyClass myinst;
  86   myinst.myFunction();
  87   MyClass otherinst(myinst);
  88 }
  89 \endcode
  90
  91 Which actual kind of d-pointer behavior is declared is decided by using different macros and base classes for the d-pointer class. The argument to the DECLARE_* macro defines the name of the d-pointer variable, usually this will be "d", but you can chose any other name (except "Private" and "DPrivate", which are used as wrapper class names).
  92
  93 The DPTR_CLASS_NAME macro returns the class name of the d-pointer class relative to the main class, which is given as argument. The DEFINE_* macro defines the logic that automatically instantiates, deletes and copies the d-pointer when the main class is instantiated, deleted, and copied. The d-pointer class must be derived from one of the DPtr classes, since these implement some functionality complementing the DEFINE_* macro.
  94
  95 The header file should only include \<DPtrBase> - this file contains the DECLARE_* macros, which is the only thing needed for the header. If you include any other file, this makes mixing versions of Chester impossible in some situations. The implementation file must include one of the d-pointer implementation variants.
  96
  97 \section table Comparison Table
  98
  99 The macros, classes, \#include statements above need to be replaced with different ones if you want one of the other kinds of d-pointers:
 100
 101 <table>
 102 <tr>
 103  <td><b>Type</b><td><b>Pointer Declaration (1)</b><td><b>Declaration Include (1)</b>
 104  <td><b>Base Class(2, 3)</b><td><b>Definition (2)</b><td><b>Implementation Include (2)</b></tr>
 105 <tr>
 106  <td>Non-Shared, Copyable<td>DECLARE_DPTR(Class)<td>\#include \<\link dptr_base.h DPtrBase \endlink >
 107  <td>DPtr<td>DEFINE_DPTR(Class)
 108  <td>\#include \<\link dptr.h DPtr \endlink >
 109  </tr>
 110 <tr>
 111  <td>Shared<td>DECLARE_SHARED_DPTR(Class)<td>\#include \<\link dptr_base.h DPtrBase \endlink >
 112  <td>SharedDPtr<td>DEFINE_SHARED_DPTR(Class)
 113  <td>\#include \<\link dptr_shared.h SharedDPtr \endlink >
 114  </tr>
 115 <tr>
 116  <td>Non-Copyable<td>DECLARE_NONCOPY_DPTR(Class)<td>\#include \<\link dptr_base.h DPtrBase \endlink >
 117  <td>NonCopyDPtr<td>DEFINE_NONCOPY_DPTR(Class)
 118  <td>\#include \<\link dptr_noncopy.h NonCopyDPtr \endlink >
 119  </tr>
 120 </table>
 121
 122 (1) The DECLARE_* macro and declartion include directive are supposed to be used in the header file of the main class.
 123
 124 (2) The implementation include directive should only be used in the main class'es implementation file - use the DEFINE_* macro to create the glue code that connects the d-pointer class with the main class.
 125
 126 (3) The base class must be used to derive the d-pointer class in the implementation file. It contains some functionality that the DEFINE_* macro relies on.
 127 */
 128
 129 //hide the namespace
 130 /// \cond never
 131 namespace Chester_0_1{
 132 /// \endcond
 133
 134 /** \brief Base class of non-shared d-pointers.
 135
 136 Use in conjunction with DECLARE_DPTR and DEFINE_DPTR */
 137 class DPtr
 138 {
 139         public:
 140                 ///instantiates a non-shared d-pointer
 141                 DPtr(){}
 142                 ///deletes a non-shared d-pointer
 143                 virtual ~DPtr(){}
 144 };
 145
 146 //hide the namespace
 147 /// \cond never
 148 };
 149 using namespace Chester_0_1;
 150 /// \endcond
 151 #endif
 152
 153 #ifdef DEFINE_DPTR
 154 #undef DEFINE_DPTR
 155 #endif
 156
 157 /** \brief Creates definitions for methods of the non-shared d-pointer wrapper.
 158
 159 This variant is not shared between instances of the containing class, but it is able to copy its content (using the contents copy constructor and assignment operator). You cannot use this variant if any of the content classes have inaccessable copy constructors or assignment operators (like Qt's QObject and its subclasses).
 160
 161 To be used in implementation where the actual d-pointer class is implemented.
 162
 163 \param Class the base class within which the d-pointer was declared*/
 164 #define DEFINE_DPTR(Class) \
 165  Class::DPrivate::DPrivate(){d=new Class::Private;}\
 166  Class::DPrivate::DPrivate(const Class::DPrivate&dp){d=new Class::Private(*(dp.d));}\
 167  Class::DPrivate::~DPrivate(){delete d;}\
 168  Class::DPrivate Class::DPrivate::clone()const{DPrivate r;*(r.d)=*d;return r;}\
 169  Class::DPrivate& Class::DPrivate::operator=(const Class::DPrivate&dp)\
 170  {*d=*(dp.d);return *this;}
 171