Debian Codegraph @

Documentation/Overview/pointers.xml

raw
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>