llvm.org GIT mirror llvm / 8a6538c
docs: Update HowToSetUpLLVMStyleRTTI. Recent changes to isa<>/dyn_cast<> have made unnecessary those classof() of the form: static bool classof(const Foo *) { return true; } Accordingly, remove mention of such classof() from the documentation. git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@165766 91177308-0d34-0410-b5e6-96231b3b80d8 Sean Silva 6 years ago
1 changed file(s) with 42 addition(s) and 24 deletion(s). Raw diff Collapse all Expand all
173173
174174 Shape(ShapeKind K) : Kind(K) {}
175175 virtual double computeArea() = 0;
176 +
177 + static bool classof(const Shape *) { return true; }
178176 };
179177
180178 class Square : public Shape {
183181 Square(double S) : Shape(SquareKind), SideLength(S) {}
184182 double computeArea() /* override */;
185183 +
186 + static bool classof(const Square *) { return true; }
187184 + static bool classof(const Shape *S) {
188185 + return S->getKind() == SquareKind;
189186 + }
195192 Circle(double R) : Shape(CircleKind), Radius(R) {}
196193 double computeArea() /* override */;
197194 +
198 + static bool classof(const Circle *) { return true; }
199195 + static bool classof(const Shape *S) {
200196 + return S->getKind() == CircleKind;
201197 + }
202198 };
203199
204 Basically, the job of ``classof`` is to return ``true`` if its argument
205 is of the enclosing class's type. As you can see, there are two general
206 overloads of ``classof`` in use here.
207
208 #. The first, which just returns ``true``, means that if we know that the
209 argument of the cast is of the enclosing type *at compile time*, then
210 we don't need to bother to check anything since we already know that
211 the type is convertible. This is an optimization for the case that we
212 statically know the conversion is OK.
213
214 #. The other overload takes a pointer to an object of the base of the
215 class hierarchy: this is the "general case" of the cast. We need to
216 check the ``Kind`` to dynamically decide if the argument is of (or
217 derived from) the enclosing type.
218
219 To be more precise, let ``classof`` be inside a class ``C``. Then the
220 contract for ``classof`` is "return ``true`` if the argument is-a
221 ``C``". As long as your implementation fulfills this contract, you can
222 tweak and optimize it as much as you want.
200 The job of ``classof`` is to dynamically determine whether an object of
201 a base class is in fact of a particular derived class. The argument to
202 ``classof`` should always be an *ancestor* class because the
203 implementation has logic to allow and optimize away
204 upcasts/up-``isa<>``'s automatically. It is as though every class
205 ``Foo`` automatically has a ``classof`` like:
206
207 .. code-block:: c++
208
209 class Foo {
210 [...]
211 static bool classof(const Foo *) { return true; }
212 [...]
213 };
214
215 In order to downcast a type ``Base`` to a type ``Derived``, there needs
216 to be a ``classof`` in ``Derived`` which will accept an object of type
217 ``Base``.
218
219 To be concrete, in the following code:
220
221 .. code-block:: c++
222
223 Shape *S = ...;
224 if (isa(S)) {
225 /* do something ... */
226 }
227
228 The code of ``isa<>`` will eventually boil down---after template
229 instantiation and some other machinery---to a check roughly like
230 ``Circle::classof(S)``. For more information, see
231 :ref:`classof-contract`.
223232
224233 Although for this small example setting up LLVM-style RTTI seems like a lot
225234 of "boilerplate", if your classes are doing anything interesting then this
246255
247256 .. code-block:: c++
248257
249 static bool classof(const Square *) { return true; }
250258 - static bool classof(const Shape *S) {
251259 - return S->getKind() == SquareKind;
252260 - }
272280 | OtherSpecialSquare
273281 | Circle
274282
283 .. _classof-contract:
284
285 The Contract of ``classof``
286 ---------------------------
287
288 To be more precise, let ``classof`` be inside a class ``C``. Then the
289 contract for ``classof`` is "return ``true`` if the dynamic type of the
290 argument is-a ``C``". As long as your implementation fulfills this
291 contract, you can tweak and optimize it as much as you want.
292
275293 .. TODO::
276294
277295 Touch on some of the more advanced features, like ``isa_impl`` and