572 lines · plain
1======================================================2How to set up LLVM-style RTTI for your class hierarchy3======================================================4 5.. contents::6 7Background8==========9 10LLVM avoids using C++'s built in RTTI. Instead, it pervasively uses its11own hand-rolled form of RTTI which is much more efficient and flexible,12although it requires a bit more work from you as a class author.13 14A description of how to use LLVM-style RTTI from a client's perspective is15given in the `Programmer's Manual <ProgrammersManual.html#isa>`_. This16document, in contrast, discusses the steps you need to take as a class17hierarchy author to make LLVM-style RTTI available to your clients.18 19Before diving in, make sure that you are familiar with the Object Oriented20Programming concept of "`is-a`_".21 22.. _is-a: http://en.wikipedia.org/wiki/Is-a23 24Basic Setup25===========26 27This section describes how to set up the most basic form of LLVM-style RTTI28(which is sufficient for 99.9% of the cases). We will set up LLVM-style29RTTI for this class hierarchy:30 31.. code-block:: c++32 33 class Shape {34 public:35 Shape() {}36 virtual double computeArea() = 0;37 };38 39 class Square : public Shape {40 double SideLength;41 public:42 Square(double S) : SideLength(S) {}43 double computeArea() override;44 };45 46 class Circle : public Shape {47 double Radius;48 public:49 Circle(double R) : Radius(R) {}50 double computeArea() override;51 };52 53The most basic working setup for LLVM-style RTTI requires the following54steps:55 56#. In the header where you declare ``Shape``, you will want to ``#include57 "llvm/Support/Casting.h"``, which declares LLVM's RTTI templates. That58 way your clients don't even have to think about it.59 60 .. code-block:: c++61 62 #include "llvm/Support/Casting.h"63 64#. In the base class, introduce an enum which discriminates all of the65 different concrete classes in the hierarchy, and stash the enum value66 somewhere in the base class.67 68 Here is the code after introducing this change:69 70 .. code-block:: c++71 72 class Shape {73 public:74 + /// Discriminator for LLVM-style RTTI (dyn_cast<> et al.)75 + enum ShapeKind {76 + SK_Square,77 + SK_Circle78 + };79 +private:80 + const ShapeKind Kind;81 +public:82 + ShapeKind getKind() const { return Kind; }83 +84 Shape() {}85 virtual double computeArea() = 0;86 };87 88 You will usually want to keep the ``Kind`` member encapsulated and89 private, but let the enum ``ShapeKind`` be public along with providing a90 ``getKind()`` method. This is convenient for clients so that they can do91 a ``switch`` over the enum.92 93 A common naming convention is that these enums are "kind"s, to avoid94 ambiguity with the words "type" or "class" which have overloaded meanings95 in many contexts within LLVM. Sometimes there will be a natural name for96 it, like "opcode". Don't bikeshed over this; when in doubt use ``Kind``.97 98 You might wonder why the ``Kind`` enum doesn't have an entry for99 ``Shape``. The reason for this is that since ``Shape`` is abstract100 (``computeArea() = 0;``), you will never actually have non-derived101 instances of exactly that class (only subclasses). See `Concrete Bases102 and Deeper Hierarchies`_ for information on how to deal with103 non-abstract bases. It's worth mentioning here that unlike104 ``dynamic_cast<>``, LLVM-style RTTI can be used (and is often used) for105 classes that don't have v-tables.106 107#. Next, you need to make sure that the ``Kind`` gets initialized to the108 value corresponding to the dynamic type of the class. Typically, you will109 want to have it be an argument to the constructor of the base class, and110 then pass in the respective ``XXXKind`` from subclass constructors.111 112 Here is the code after that change:113 114 .. code-block:: c++115 116 class Shape {117 public:118 /// Discriminator for LLVM-style RTTI (dyn_cast<> et al.)119 enum ShapeKind {120 SK_Square,121 SK_Circle122 };123 private:124 const ShapeKind Kind;125 public:126 ShapeKind getKind() const { return Kind; }127 128 - Shape() {}129 + Shape(ShapeKind K) : Kind(K) {}130 virtual double computeArea() = 0;131 };132 133 class Square : public Shape {134 double SideLength;135 public:136 - Square(double S) : SideLength(S) {}137 + Square(double S) : Shape(SK_Square), SideLength(S) {}138 double computeArea() override;139 };140 141 class Circle : public Shape {142 double Radius;143 public:144 - Circle(double R) : Radius(R) {}145 + Circle(double R) : Shape(SK_Circle), Radius(R) {}146 double computeArea() override;147 };148 149#. Finally, you need to inform LLVM's RTTI templates how to dynamically150 determine the type of a class (i.e. whether the ``isa<>``/``dyn_cast<>``151 should succeed). The default "99.9% of use cases" way to accomplish this152 is through a small static member function ``classof``. In order to have153 proper context for an explanation, we will display this code first, and154 then below describe each part:155 156 .. code-block:: c++157 158 class Shape {159 public:160 /// Discriminator for LLVM-style RTTI (dyn_cast<> et al.)161 enum ShapeKind {162 SK_Square,163 SK_Circle164 };165 private:166 const ShapeKind Kind;167 public:168 ShapeKind getKind() const { return Kind; }169 170 Shape(ShapeKind K) : Kind(K) {}171 virtual double computeArea() = 0;172 };173 174 class Square : public Shape {175 double SideLength;176 public:177 Square(double S) : Shape(SK_Square), SideLength(S) {}178 double computeArea() override;179 +180 + static bool classof(const Shape *S) {181 + return S->getKind() == SK_Square;182 + }183 };184 185 class Circle : public Shape {186 double Radius;187 public:188 Circle(double R) : Shape(SK_Circle), Radius(R) {}189 double computeArea() override;190 +191 + static bool classof(const Shape *S) {192 + return S->getKind() == SK_Circle;193 + }194 };195 196 The job of ``classof`` is to dynamically determine whether an object of197 a base class is in fact of a particular derived class. In order to198 downcast a type ``Base`` to a type ``Derived``, there needs to be a199 ``classof`` in ``Derived`` which will accept an object of type ``Base``.200 201 To be concrete, consider the following code:202 203 .. code-block:: c++204 205 Shape *S = ...;206 if (isa<Circle>(S)) {207 /* do something ... */208 }209 210 The code of the ``isa<>`` test in this code will eventually boil211 down---after template instantiation and some other machinery---to a212 check roughly like ``Circle::classof(S)``. For more information, see213 :ref:`classof-contract`.214 215 The argument to ``classof`` should always be an *ancestor* class because216 the implementation has logic to allow and optimize away217 upcasts/up-``isa<>``'s automatically. It is as though every class218 ``Foo`` automatically has a ``classof`` like:219 220 .. code-block:: c++221 222 class Foo {223 [...]224 template <class T>225 static bool classof(const T *,226 ::std::enable_if<227 ::std::is_base_of<Foo, T>::value228 >::type* = 0) { return true; }229 [...]230 };231 232 Note that this is the reason that we did not need to introduce a233 ``classof`` into ``Shape``: all relevant classes derive from ``Shape``,234 and ``Shape`` itself is abstract (has no entry in the ``Kind`` enum),235 so this notional inferred ``classof`` is all we need. See `Concrete236 Bases and Deeper Hierarchies`_ for more information about how to extend237 this example to more general hierarchies.238 239Although for this small example setting up LLVM-style RTTI seems like a lot240of "boilerplate", if your classes are doing anything interesting then this241will end up being a tiny fraction of the code.242 243Concrete Bases and Deeper Hierarchies244=====================================245 246For concrete bases (i.e. non-abstract interior nodes of the inheritance247tree), the ``Kind`` check inside ``classof`` needs to be a bit more248complicated. The situation differs from the example above in that249 250* Since the class is concrete, it must itself have an entry in the ``Kind``251 enum because it is possible to have objects with this class as a dynamic252 type.253 254* Since the class has children, the check inside ``classof`` must take them255 into account.256 257Say that ``SpecialSquare`` and ``OtherSpecialSquare`` derive258from ``Square``, and so ``ShapeKind`` becomes:259 260.. code-block:: c++261 262 enum ShapeKind {263 SK_Square,264 + SK_SpecialSquare,265 + SK_OtherSpecialSquare,266 SK_Circle267 }268 269Then in ``Square``, we would need to modify the ``classof`` like so:270 271.. code-block:: c++272 273 - static bool classof(const Shape *S) {274 - return S->getKind() == SK_Square;275 - }276 + static bool classof(const Shape *S) {277 + return S->getKind() >= SK_Square &&278 + S->getKind() <= SK_OtherSpecialSquare;279 + }280 281The reason that we need to test a range like this instead of just equality282is that both ``SpecialSquare`` and ``OtherSpecialSquare`` "is-a"283``Square``, and so ``classof`` needs to return ``true`` for them.284 285This approach can be made to scale to arbitrarily deep hierarchies. The286trick is that you arrange the enum values so that they correspond to a287preorder traversal of the class hierarchy tree. With that arrangement, all288subclass tests can be done with two comparisons as shown above. If you just289list the class hierarchy like a list of bullet points, you'll get the290ordering right::291 292 | Shape293 | Square294 | SpecialSquare295 | OtherSpecialSquare296 | Circle297 298A Bug to be Aware Of299--------------------300 301The example just given opens the door to bugs where the ``classof``\s are302not updated to match the ``Kind`` enum when adding (or removing) classes to303(from) the hierarchy.304 305Continuing the example above, suppose we add a ``SomewhatSpecialSquare`` as306a subclass of ``Square``, and update the ``ShapeKind`` enum like so:307 308.. code-block:: c++309 310 enum ShapeKind {311 SK_Square,312 SK_SpecialSquare,313 SK_OtherSpecialSquare,314 + SK_SomewhatSpecialSquare,315 SK_Circle316 }317 318Now, suppose that we forget to update ``Square::classof()``, so it still319looks like:320 321.. code-block:: c++322 323 static bool classof(const Shape *S) {324 // BUG: Returns false when S->getKind() == SK_SomewhatSpecialSquare,325 // even though SomewhatSpecialSquare "is a" Square.326 return S->getKind() >= SK_Square &&327 S->getKind() <= SK_OtherSpecialSquare;328 }329 330As the comment indicates, this code contains a bug. A straightforward and331non-clever way to avoid this is to introduce an explicit ``SK_LastSquare``332entry in the enum when adding the first subclass(es). For example, we could333rewrite the example at the beginning of `Concrete Bases and Deeper334Hierarchies`_ as:335 336.. code-block:: c++337 338 enum ShapeKind {339 SK_Square,340 + SK_SpecialSquare,341 + SK_OtherSpecialSquare,342 + SK_LastSquare,343 SK_Circle344 }345 ...346 // Square::classof()347 - static bool classof(const Shape *S) {348 - return S->getKind() == SK_Square;349 - }350 + static bool classof(const Shape *S) {351 + return S->getKind() >= SK_Square &&352 + S->getKind() <= SK_LastSquare;353 + }354 355Then, adding new subclasses is easy:356 357.. code-block:: c++358 359 enum ShapeKind {360 SK_Square,361 SK_SpecialSquare,362 SK_OtherSpecialSquare,363 + SK_SomewhatSpecialSquare,364 SK_LastSquare,365 SK_Circle366 }367 368Notice that ``Square::classof`` does not need to be changed.369 370.. _classof-contract:371 372The Contract of ``classof``373---------------------------374 375To be more precise, let ``classof`` be inside a class ``C``. Then the376contract for ``classof`` is "return ``true`` if the dynamic type of the377argument is-a ``C``". As long as your implementation fulfills this378contract, you can tweak and optimize it as much as you want.379 380For example, LLVM-style RTTI can work fine in the presence of381multiple-inheritance by defining an appropriate ``classof``.382An example of this in practice is383`Decl <https://clang.llvm.org/doxygen/classclang_1_1Decl.html>`_ vs.384`DeclContext <https://clang.llvm.org/doxygen/classclang_1_1DeclContext.html>`_385inside Clang.386The ``Decl`` hierarchy is done very similarly to the example setup387demonstrated in this tutorial.388The key part is how to then incorporate ``DeclContext``: all that is needed389is in ``bool DeclContext::classof(const Decl *)``, which asks the question390"Given a ``Decl``, how can I determine if it is-a ``DeclContext``?".391It answers this with a simple switch over the set of ``Decl`` "kinds", and392returning true for ones that are known to be ``DeclContext``'s.393 394.. TODO::395 396 Touch on some of the more advanced features, like ``isa_impl`` and397 ``simplify_type``. However, those two need reference documentation in398 the form of doxygen comments as well. We need the doxygen so that we can399 say "for full details, see https://llvm.org/doxygen/..."400 401Rules of Thumb402==============403 404#. The ``Kind`` enum should have one entry per concrete class, ordered405 according to a preorder traversal of the inheritance tree.406#. The argument to ``classof`` should be a ``const Base *``, where ``Base``407 is some ancestor in the inheritance hierarchy. The argument should408 *never* be a derived class or the class itself: the template machinery409 for ``isa<>`` already handles this case and optimizes it.410#. For each class in the hierarchy that has no children, implement a411 ``classof`` that checks only against its ``Kind``.412#. For each class in the hierarchy that has children, implement a413 ``classof`` that checks a range of the first child's ``Kind`` and the414 last child's ``Kind``.415 416RTTI for Open Class Hierarchies417===============================418 419Sometimes it is not possible to know all types in a hierarchy ahead of time.420For example, in the shapes hierarchy described above the authors may have421wanted their code to work for user defined shapes too. To support use cases422that require open hierarchies LLVM provides the ``RTTIRoot`` and423``RTTIExtends`` utilities.424 425The ``RTTIRoot`` class describes an interface for performing RTTI checks. The426``RTTIExtends`` class template provides an implementation of this interface427for classes derived from ``RTTIRoot``. ``RTTIExtends`` uses the "`Curiously428Recurring Template Idiom`_", taking the class being defined as its first429template argument and the parent class as the second argument. Any class that430uses ``RTTIExtends`` must define a ``static char ID`` member, the address of431which will be used to identify the type.432 433This open-hierarchy RTTI support should only be used if your use case requires434it. Otherwise the standard LLVM RTTI system should be preferred.435 436.. _`Curiously Recurring Template Idiom`:437 https://en.wikipedia.org/wiki/Curiously_recurring_template_pattern438 439E.g.440 441.. code-block:: c++442 443 class Shape : public RTTIExtends<Shape, RTTIRoot> {444 public:445 static char ID;446 virtual double computeArea() = 0;447 };448 449 class Square : public RTTIExtends<Square, Shape> {450 double SideLength;451 public:452 static char ID;453 454 Square(double S) : SideLength(S) {}455 double computeArea() override;456 };457 458 class Circle : public RTTIExtends<Circle, Shape> {459 double Radius;460 public:461 static char ID;462 463 Circle(double R) : Radius(R) {}464 double computeArea() override;465 };466 467 char Shape::ID = 0;468 char Square::ID = 0;469 char Circle::ID = 0;470 471Advanced Use Cases472==================473 474The underlying implementation of isa/cast/dyn_cast is all controlled through a475struct called ``CastInfo``. ``CastInfo`` provides 4 methods, ``isPossible``,476``doCast``, ``castFailed``, and ``doCastIfPossible``. These are for ``isa``,477``cast``, and ``dyn_cast``, in order. You can control the way your cast is478performed by creating a specialization of the ``CastInfo`` struct (to your479desired types) that provides the same static methods as the base ``CastInfo``480struct.481 482This can be a lot of boilerplate, so we also have what we call Cast Traits.483These are structs that provide one or more of the above methods so you can484factor out common casting patterns in your project. We provide a few in the485header file ready to be used, and we'll show a few examples motivating their486usage. These examples are not exhaustive, and adding new cast traits is easy487so users should feel free to add them to their project, or contribute them if488they're particularly useful!489 490Value to value casting491----------------------492In this case, we have a struct that is what we call 'nullable' - i.e. it is493constructible from ``nullptr`` and that results in a value you can tell is494invalid.495 496.. code-block:: c++497 498 class SomeValue {499 public:500 SomeValue(void *ptr) : ptr(ptr) {}501 void *getPointer() const { return ptr; }502 bool isValid() const { return ptr != nullptr; }503 private:504 void *ptr;505 };506 507Given something like this, we want to pass this object around by value, and we508would like to cast from objects of this type to some other set of objects. For509now, we assume that the types we want to cast *to* all provide ``classof``. So510we can use some provided cast traits like so:511 512.. code-block:: c++513 514 template <typename T>515 struct CastInfo<T, SomeValue>516 : CastIsPossible<T, SomeValue>, NullableValueCastFailed<T>,517 DefaultDoCastIfPossible<T, SomeValue, CastInfo<T, SomeValue>> {518 static T doCast(SomeValue v) {519 return T(v.getPointer());520 }521 };522 523Pointer to value casting524------------------------525Now given the value above ``SomeValue``, maybe we'd like to be able to cast to526that type from a char pointer type. So what we would do in that case is:527 528.. code-block:: c++529 530 template <typename T>531 struct CastInfo<SomeValue, T *>532 : NullableValueCastFailed<SomeValue>,533 DefaultDoCastIfPossible<SomeValue, T *, CastInfo<SomeValue, T *>> {534 static bool isPossible(const T *t) {535 return std::is_same<T, char>::value;536 }537 static SomeValue doCast(const T *t) {538 return SomeValue((void *)t);539 }540 };541 542This would enable us to cast from a ``char *`` to a SomeValue, if we wanted to.543 544Optional value casting545----------------------546When your types are not constructible from ``nullptr`` or there isn't a simple547way to tell when an object is invalid, you may want to use ``std::optional``.548In those cases, you probably want something like this:549 550.. code-block:: c++551 552 template <typename T>553 struct CastInfo<T, SomeValue> : OptionalValueCast<T, SomeValue> {};554 555That cast trait requires that ``T`` is constructible from ``const SomeValue &``556but it enables casting like so:557 558.. code-block:: c++559 560 SomeValue someVal = ...;561 std::optional<AnotherValue> valOr = dyn_cast<AnotherValue>(someVal);562 563With the ``_if_present`` variants, you can even do optional chaining like this:564 565.. code-block:: c++566 567 std::optional<SomeValue> someVal = ...;568 std::optional<AnotherValue> valOr = dyn_cast_if_present<AnotherValue>(someVal);569 570and ``valOr`` will be ``std::nullopt`` if either ``someVal`` cannot be converted *or*571if ``someVal`` was also ``std::nullopt``.572