1 .. _how-to-set-up-llvm-style-rtti:
3 ======================================================
4 How to set up LLVM-style RTTI for your class hierarchy
5 ======================================================
7 .. sectionauthor:: Sean Silva <silvas@purdue.edu>
14 LLVM avoids using C++'s built in RTTI. Instead, it pervasively uses its
15 own hand-rolled form of RTTI which is much more efficient and flexible,
16 although it requires a bit more work from you as a class author.
18 A description of how to use LLVM-style RTTI from a client's perspective is
19 given in the `Programmer's Manual <ProgrammersManual.html#isa>`_. This
20 document, in contrast, discusses the steps you need to take as a class
21 hierarchy author to make LLVM-style RTTI available to your clients.
23 Before diving in, make sure that you are familiar with the Object Oriented
24 Programming concept of "`is-a`_".
26 .. _is-a: http://en.wikipedia.org/wiki/Is-a
31 This section describes how to set up the most basic form of LLVM-style RTTI
32 (which is sufficient for 99.9% of the cases). We will set up LLVM-style
33 RTTI for this class hierarchy:
40 virtual double computeArea() = 0;
43 class Square : public Shape {
46 Square(double S) : SideLength(S) {}
47 double computeArea() /* override */;
50 class Circle : public Shape {
53 Circle(double R) : Radius(R) {}
54 double computeArea() /* override */;
57 The most basic working setup for LLVM-style RTTI requires the following
60 #. In the header where you declare ``Shape``, you will want to ``#include
61 "llvm/Support/Casting.h"``, which declares LLVM's RTTI templates. That
62 way your clients don't even have to think about it.
66 #include "llvm/Support/Casting.h"
69 #. In the base class, introduce an enum which discriminates all of the
70 different classes in the hierarchy, and stash the enum value somewhere in
73 Here is the code after introducing this change:
79 + /// Discriminator for LLVM-style RTTI (dyn_cast<> et al.)
85 + const ShapeKind Kind;
87 + ShapeKind getKind() const { return Kind; }
90 virtual double computeArea() = 0;
93 You will usually want to keep the ``Kind`` member encapsulated and
94 private, but let the enum ``ShapeKind`` be public along with providing a
95 ``getKind()`` method. This is convenient for clients so that they can do
96 a ``switch`` over the enum.
98 A common naming convention is that these enums are "kind"s, to avoid
99 ambiguity with the words "type" or "class" which have overloaded meanings
100 in many contexts within LLVM. Sometimes there will be a natural name for
101 it, like "opcode". Don't bikeshed over this; when in doubt use ``Kind``.
103 You might wonder why the ``Kind`` enum doesn't have an entry for
104 ``Shape``. The reason for this is that since ``Shape`` is abstract
105 (``computeArea() = 0;``), you will never actually have non-derived
106 instances of exactly that class (only subclasses). See `Concrete Bases
107 and Deeper Hierarchies`_ for information on how to deal with
108 non-abstract bases. It's worth mentioning here that unlike
109 ``dynamic_cast<>``, LLVM-style RTTI can be used (and is often used) for
110 classes that don't have v-tables.
112 #. Next, you need to make sure that the ``Kind`` gets initialized to the
113 value corresponding to the dynamic type of the class. Typically, you will
114 want to have it be an argument to the constructor of the base class, and
115 then pass in the respective ``XXXKind`` from subclass constructors.
117 Here is the code after that change:
123 /// Discriminator for LLVM-style RTTI (dyn_cast<> et al.)
129 const ShapeKind Kind;
131 ShapeKind getKind() const { return Kind; }
134 + Shape(ShapeKind K) : Kind(K) {};
135 virtual double computeArea() = 0;
138 class Square : public Shape {
141 - Square(double S) : SideLength(S) {}
142 + Square(double S) : Shape(SquareKind), SideLength(S) {}
143 double computeArea() /* override */;
146 class Circle : public Shape {
149 - Circle(double R) : Radius(R) {}
150 + Circle(double R) : Shape(CircleKind), Radius(R) {}
151 double computeArea() /* override */;
154 #. Finally, you need to inform LLVM's RTTI templates how to dynamically
155 determine the type of a class (i.e. whether the ``isa<>``/``dyn_cast<>``
156 should succeed). The default "99.9% of use cases" way to accomplish this
157 is through a small static member function ``classof``. In order to have
158 proper context for an explanation, we will display this code first, and
159 then below describe each part:
165 /// Discriminator for LLVM-style RTTI (dyn_cast<> et al.)
171 const ShapeKind Kind;
173 ShapeKind getKind() const { return Kind; }
175 Shape(ShapeKind K) : Kind(K) {};
176 virtual double computeArea() = 0;
178 + static bool classof(const Shape *) { return true; }
181 class Square : public Shape {
184 Square(double S) : Shape(SquareKind), SideLength(S) {}
185 double computeArea() /* override */;
187 + static bool classof(const Square *) { return true; }
188 + static bool classof(const Shape *S) {
189 + return S->getKind() == SquareKind;
193 class Circle : public Shape {
196 Circle(double R) : Shape(CircleKind), Radius(R) {}
197 double computeArea() /* override */;
199 + static bool classof(const Circle *) { return true; }
200 + static bool classof(const Shape *S) {
201 + return S->getKind() == CircleKind;
205 Basically, the job of ``classof`` is to return ``true`` if its argument
206 is of the enclosing class's type. As you can see, there are two general
207 overloads of ``classof`` in use here.
209 #. The first, which just returns ``true``, means that if we know that the
210 argument of the cast is of the enclosing type *at compile time*, then
211 we don't need to bother to check anything since we already know that
212 the type is convertible. This is an optimization for the case that we
213 statically know the conversion is OK.
215 #. The other overload takes a pointer to an object of the base of the
216 class hierarchy: this is the "general case" of the cast. We need to
217 check the ``Kind`` to dynamically decide if the argument is of (or
218 derived from) the enclosing type.
220 To be more precise, let ``classof`` be inside a class ``C``. Then the
221 contract for ``classof`` is "return ``true`` if the argument is-a
222 ``C``". As long as your implementation fulfills this contract, you can
223 tweak and optimize it as much as you want.
225 Although for this small example setting up LLVM-style RTTI seems like a lot
226 of "boilerplate", if your classes are doing anything interesting then this
227 will end up being a tiny fraction of the code.
229 Concrete Bases and Deeper Hierarchies
230 =====================================
232 For concrete bases (i.e. non-abstract interior nodes of the inheritance
233 tree), the ``Kind`` check inside ``classof`` needs to be a bit more
234 complicated. Say that ``SpecialSquare`` and ``OtherSpecialSquare`` derive
235 from ``Square``, and so ``ShapeKind`` becomes:
242 + OtherSpecialSquareKind,
246 Then in ``Square``, we would need to modify the ``classof`` like so:
250 static bool classof(const Square *) { return true; }
251 - static bool classof(const Shape *S) {
252 - return S->getKind() == SquareKind;
254 + static bool classof(const Shape *S) {
255 + return S->getKind() >= SquareKind &&
256 + S->getKind() <= OtherSpecialSquareKind;
259 The reason that we need to test a range like this instead of just equality
260 is that both ``SpecialSquare`` and ``OtherSpecialSquare`` "is-a"
261 ``Square``, and so ``classof`` needs to return ``true`` for them.
263 This approach can be made to scale to arbitrarily deep hierarchies. The
264 trick is that you arrange the enum values so that they correspond to a
265 preorder traversal of the class hierarchy tree. With that arrangement, all
266 subclass tests can be done with two comparisons as shown above. If you just
267 list the class hierarchy like a list of bullet points, you'll get the
278 Touch on some of the more advanced features, like ``isa_impl`` and
279 ``simplify_type``. However, those two need reference documentation in
280 the form of doxygen comments as well. We need the doxygen so that we can
281 say "for full details, see http://llvm.org/doxygen/..."