| 1 |
<xml> |
| 2 |
<head> |
| 3 |
<title>Using ClanLib's smart pointers</title> |
| 4 |
</head> |
| 5 |
<body> |
| 6 |
|
| 7 |
<p>ClanLib has a set of smart pointer template classes which it uses internally, and which you |
| 8 |
can also use in your own game code. They make it easier to manage memory in cases where you |
| 9 |
don't want to use the stack due to a need for polymorphism, shared data, implementation-pointers, |
| 10 |
or lazy copying.</p> |
| 11 |
|
| 12 |
<p>Smart pointers can be used as members of classes and work fine with compiler-supplied |
| 13 |
destructors, default constructors, copy constructors, and copy assignment operators. They can |
| 14 |
also be used as function temporaries, they safely handle data deletion when they go out of scope, |
| 15 |
and they can also be used inside STL containers.</p> |
| 16 |
|
| 17 |
<h3>CL_SharedPtr : Sharing Pointer</h3> |
| 18 |
|
| 19 |
<p>The simplest smart pointer is CL_SharedPtr. CL_SharedPtr will share the same data among one or more instances of the pointer:</p> |
| 20 |
|
| 21 |
<code> |
| 22 |
CL_SharedPtr<Thing> a = new Thing; |
| 23 |
CL_SharedPtr<Thing> b = a; //There's only one instance of Thing being pointed to by both a and b |
| 24 |
CL_SharedPtr<Thing> c = b; //Still only one instance of Thing, being pointed to by all three pointers |
| 25 |
|
| 26 |
a->some_method(); //You can access indirect methods with '->', just like a regular pointer |
| 27 |
some_func(*a); //You can dereference it with '*', just like a regular pointer |
| 28 |
|
| 29 |
a = 0; //Now a is a null pointer (as it would be when just constructed), but b and c still point to that same data |
| 30 |
b = 0; |
| 31 |
c = 0; //Now the data is safely destroyed, and all three pointers are null |
| 32 |
</code> |
| 33 |
|
| 34 |
<p>When all the CL_SharedPtrs pointing to a particular piece of data are gone or not pointing to it anymore, the data is automatically destroyed. Keep |
| 35 |
in mind that CL_SharedPtr uses a simple reference counting system; circular loops will result in memory leaks, |
| 36 |
since the data won't ever be destroyed. However, situations where such circular loops |
| 37 |
arise are pretty rare and convoluted.</p> |
| 38 |
|
| 39 |
<p>Like a regular pointer, a CL_SharedPtr can also point to derivations of its supplied type. But make sure that you |
| 40 |
give the classes you plan to do this with virtual destructors. Assuming MaBob is a derivation of Thing:</p> |
| 41 |
|
| 42 |
<code> |
| 43 |
CL_SharedPtr<Thing> d = new MaBob; //Works just like it would with a regular Thing* |
| 44 |
</code> |
| 45 |
|
| 46 |
<h3>Preparing classes for use in CL_LazyCopyPtr and CL_OwningPtr</h3> |
| 47 |
|
| 48 |
<p>To make your classes usable in the other two ClanLib smart pointer types, it's important that the classes you |
| 49 |
use in the smart pointers descend (directly or indirectly) from CL_Clonable, and implement a |
| 50 |
very specific clone() method at the start of their definitions. For example, if you have a class called Thing, and intended to use |
| 51 |
it in a smart pointer, it would look like so:</p> |
| 52 |
|
| 53 |
<code> |
| 54 |
class Thing : public CL_Clonable |
| 55 |
{ |
| 56 |
CL_Clonable* clone() const {return new Thing(*this);} |
| 57 |
|
| 58 |
/* here is the regular definition of Thing */ |
| 59 |
}; |
| 60 |
</code> |
| 61 |
|
| 62 |
<p>If you want to derive from Thing, then each child class must reimplement clone(), substituting |
| 63 |
their own class name for Thing:</p> |
| 64 |
|
| 65 |
<code> |
| 66 |
class MaBob : public Thing |
| 67 |
{ |
| 68 |
CL_Clonable* clone() const {return new MaBob(*this);} |
| 69 |
|
| 70 |
/* here is the regular definition of MaBob */ |
| 71 |
}; |
| 72 |
</code> |
| 73 |
|
| 74 |
<p>It's important that you reimplement clone() in every derivation of a CL_Clonable class, otherwise slicing |
| 75 |
will occur. The compiler won't warn you of this, it'll just happen, so watch out!</p> |
| 76 |
|
| 77 |
<h3>CL_OwningPtr : Possessive Pointer</h3> |
| 78 |
|
| 79 |
<p>CL_OwningPtr acts like a regular stack instance of a class: whenever CL_OwningPtr is copied, then the pointed-to class is |
| 80 |
copied as well:</p> |
| 81 |
|
| 82 |
<code> |
| 83 |
CL_OwningPtr<Thing> a = new Thing; //Assign the result of 'new' to the pointer |
| 84 |
CL_OwningPtr<Thing> b = a; //After this statement, there are two instances of Thing |
| 85 |
</code> |
| 86 |
|
| 87 |
<p>In this example, possessive a and b both refer to entirely different instances of Thing, which you can access |
| 88 |
by dereferencing the respective pointer. The instance of Thing pointed to by b was made by calling the copy constructor on the |
| 89 |
Thing instance pointed to by b. When the possessive pointers are destroyed, then the things they point to are automatically |
| 90 |
destroyed as well:</p> |
| 91 |
|
| 92 |
<code> |
| 93 |
CL_OwningPtr<Thing> a = new Thing(1); |
| 94 |
a = new Thing(2); //The older Thing(1) is safely deleted here |
| 95 |
a = 0; //Now the Thing(2) is also safely destroyed |
| 96 |
</code> |
| 97 |
|
| 98 |
<h3>CL_LazyCopyPtr : Copy-on-write Pointer</h3> |
| 99 |
|
| 100 |
<p>CL_LazyCopyPtr has the same usage semantics as CL_OwningPtr; you can replace the text CL_OwningPtr with CL_LazyCopyPtr in your |
| 101 |
code and everything will continue to work. The difference is that copying a CL_OwningPtr results in an immediate |
| 102 |
copy of the pointed-to data, while copying a CL_LazyCopyPtr will not result in a copy of the pointed-to data until |
| 103 |
the CL_LazyCopyPtr is dereferenced in a non-const way:</p> |
| 104 |
|
| 105 |
<code> |
| 106 |
CL_LazyCopyPtr<Thing> a = new Thing; |
| 107 |
CL_LazyCopyPtr<Thing> b = a; //There's still only one instance of Thing |
| 108 |
b->some_member = 3; //Before the assignment, another instance of Thing is made for b to point to |
| 109 |
</code> |
| 110 |
|
| 111 |
<p>If the CL_LazyCopyPtr is a member of a class and the using code is a const method of that class, or if the CL_LazyCopyPtr |
| 112 |
is being passed to a function by const reference, then no copy of the data is made, since it's impossible |
| 113 |
for you to call a non-const method of Thing in those situations. However, in a case where you would be allowed |
| 114 |
to call a non-const method of Thing, the copy will still be made, even if you're only calling a const method. |
| 115 |
To avoid this, you can call the cd() method of CL_LazyCopyPtr, which stands for 'const dereference':</p> |
| 116 |
|
| 117 |
<code> |
| 118 |
CL_LazyCopyPtr<Thing> a = new Thing; |
| 119 |
CL_LazyCopyPtr<Thing> b = a; |
| 120 |
b.cd().some_const_method(); //There still is only one instance of Thing |
| 121 |
b->some_const_method(); //Now there are two instances of Thing, even though some_method() is a const method |
| 122 |
</code> |
| 123 |
|
| 124 |
<h3>Ownership Transfer</h3> |
| 125 |
|
| 126 |
<p>It's important to remember that when you assign something to any ClanLib smart pointer, then the smart pointer |
| 127 |
gets control over that data. From that point, you shouldn't attempt to access the data except directly through the smart pointer:</p> |
| 128 |
|
| 129 |
<code> |
| 130 |
Thing* a = new Thing; |
| 131 |
CL_SharedPtr<Thing> b = a; //Should be no direct use of a after this statement |
| 132 |
|
| 133 |
/* Stuff happens here */ |
| 134 |
|
| 135 |
some_func(*a); //EVIL BAD CODE : Should've dereferenced b instead |
| 136 |
</code> |
| 137 |
|
| 138 |
<p>The insidious thing about the above code is that it might work or it might segfault, depending on |
| 139 |
what happens at the 'Stuff happens here' comment.</p> |
| 140 |
|
| 141 |
<h3>Autocasting</h3> |
| 142 |
|
| 143 |
<p>When using a smart pointer as a pointer-to-implementation, it's often useful to have the pointer automatically |
| 144 |
cast dereferences to some type that has only been forward declared. For example, let's say you've got a CL_OwningPtr |
| 145 |
in your class Narf, with an implementation class called NarfImpl. Inside Narf's header, NarfImpl has only been forward |
| 146 |
declared. Since NarfImpl has to be derived from CL_Clonable to be in a CL_OwningPtr anyways, it's convienent |
| 147 |
to use that as the template parameter to CL_OwningPtr:</p> |
| 148 |
|
| 149 |
<code> |
| 150 |
class NarfImpl; |
| 151 |
class Narf { |
| 152 |
CL_OwningPtr<CL_Clonable> pimpl; |
| 153 |
}; |
| 154 |
</code> |
| 155 |
|
| 156 |
<p>This works, but there's an annoying problem. In Narf's implementation file, you're forced to cast |
| 157 |
to NarfImpl* or NarfImpl& evrey time you want to call any of NarfImpl's methods. Although you know that pimpl is under your |
| 158 |
strict control and will never have any derivative of CL_Clonable besides NarfImpl in it, C++ isn't convinced |
| 159 |
and requires you do all that casting.</p> |
| 160 |
|
| 161 |
<p>However, ClanLib's smart pointers can automatically do this casting for you, when you specify a second template |
| 162 |
parameter as the cast-to type:</p> |
| 163 |
|
| 164 |
<code> |
| 165 |
class NarfImpl; |
| 166 |
class Narf { |
| 167 |
CL_OwningPtr<CL_Clonable, NarfImpl> pimpl; |
| 168 |
}; |
| 169 |
</code> |
| 170 |
|
| 171 |
<p>Now, every time you dereference, do an indirect member access, or call get() on pimpl, the result will be a NarfImpl& or a NarfImpl* instead of a CL_Clonable& or CL_Clonable*.</p> |
| 172 |
|
| 173 |
</body> |
| 174 |
</xml> |