<div dir="ltr">This is great!</div><div class="gmail_extra"><br><div class="gmail_quote">On Wed, Jan 28, 2015 at 3:04 AM, Chandler Carruth <span dir="ltr"><<a href="mailto:chandlerc@gmail.com" target="_blank">chandlerc@gmail.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">Author: chandlerc<br>
Date: Tue Jan 27 21:04:54 2015<br>
New Revision: 227292<br>
<br>
URL: <a href="http://llvm.org/viewvc/llvm-project?rev=227292&view=rev" target="_blank">http://llvm.org/viewvc/llvm-project?rev=227292&view=rev</a><br>
Log:<br>
Introduce a section to the programmers manual about type hierarchies,<br>
polymorphism, and virtual dispatch.<br>
<br>
This is essentially trying to explain the emerging design techniques<br>
being used in LLVM these days somewhere more accessible than the<br>
comments on a particular piece of infrastructure. It covers the<br>
"concepts-based polymorphism" that caused some confusion during initial<br>
reviews of the new pass manager as well as the tagged-dispatch mechanism<br>
used pervasively in LLVM and Clang.<br>
<br>
Perhaps most notably, I've tried to provide some criteria to help<br>
developers choose between these options when designing new pieces of<br>
infrastructure.<br>
<br>
Differential Revision: <a href="http://reviews.llvm.org/D7191" target="_blank">http://reviews.llvm.org/D7191</a><br>
<br>
Modified:<br>
llvm/trunk/docs/ProgrammersManual.rst<br>
<br>
Modified: llvm/trunk/docs/ProgrammersManual.rst<br>
URL: <a href="http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/ProgrammersManual.rst?rev=227292&r1=227291&r2=227292&view=diff" target="_blank">http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/ProgrammersManual.rst?rev=227292&r1=227291&r2=227292&view=diff</a><br>
==============================================================================<br>
--- llvm/trunk/docs/ProgrammersManual.rst (original)<br>
+++ llvm/trunk/docs/ProgrammersManual.rst Tue Jan 27 21:04:54 2015<br>
@@ -2480,6 +2480,76 @@ ensures that the first bytes of ``User``<br>
the LSBit set. (Portability is relying on the fact that all known compilers<br>
place the ``vptr`` in the first word of the instances.)<br>
<br>
+.. _polymorphism:<br>
+<br>
+Designing Type Hiercharies and Polymorphic Interfaces<br>
+-----------------------------------------------------<br>
+<br>
+There are two different design patterns that tend to result in the use of<br>
+virtual dispatch for methods in a type hierarchy in C++ programs. The first is<br>
+a genuine type hierarchy where different types in the hierarchy model<br>
+a specific subset of the functionality and semantics, and these types nest<br>
+strictly within each other. Good examples of this can be seen in the ``Value``<br>
+or ``Type`` type hierarchies.<br>
+<br>
+A second is the desire to dispatch dynamically across a collection of<br>
+polymorphic interface implementations. This latter use case can be modeled with<br>
+virtual dispatch and inheritance by defining an abstract interface base class<br>
+which all implementations derive from and override. However, this<br>
+implementation strategy forces an **"is-a"** relationship to exist that is not<br>
+actually meaningful. There is often not some nested hierarchy of useful<br>
+generalizations which code might interact with and move up and down. Instead,<br>
+there is a singular interface which is dispatched across a range of<br>
+implementations.<br>
+<br>
+The preferred implementation strategy for the second use case is that of<br>
+generic programming (sometimes called "compile-time duck typing" or "static<br>
+polymorphism"). For example, a template over some type parameter ``T`` can be<br>
+instantiated across any particular implementation that conforms to the<br>
+interface or *concept*. A good example here is the highly generic properties of<br>
+any type which models a node in a directed graph. LLVM models these primarily<br>
+through templates and generic programming. Such templates include the<br>
+``LoopInfoBase`` and ``DominatorTreeBase``. When this type of polymorphism<br>
+truly needs **dynamic** dispatch you can generalize it using a technique<br>
+called *concept-based polymorphism*. This pattern emulates the interfaces and<br>
+behaviors of templates using a very limited form of virtual dispatch for type<br>
+erasure inside its implementation. You can find examples of this technique in<br>
+the ``PassManager.h`` system, and there is a more detailed introduction to it<br>
+by Sean Parent in several of his talks and papers:<br>
+<br>
+#. `Inheritance Is The Base Class of Evil<br>
+ <<a href="http://channel9.msdn.com/Events/GoingNative/2013/Inheritance-Is-The-Base-Class-of-Evil" target="_blank">http://channel9.msdn.com/Events/GoingNative/2013/Inheritance-Is-The-Base-Class-of-Evil</a>>`_<br>
+ - The GoingNative 2013 talk describing this technique, and probably the best<br>
+ place to start.<br>
+#. `Value Semantics and Concepts-based Polymorphism<br>
+ <<a href="http://www.youtube.com/watch?v=_BpMYeUFXv8" target="_blank">http://www.youtube.com/watch?v=_BpMYeUFXv8</a>>`_ - The C++Now! 2012 talk<br>
+ describing this technique in more detail.<br>
+#. `Sean Parent's Papers and Presentations<br>
+ <<a href="http://github.com/sean-parent/sean-parent.github.com/wiki/Papers-and-Presentations" target="_blank">http://github.com/sean-parent/sean-parent.github.com/wiki/Papers-and-Presentations</a>>`_<br>
+ - A Github project full of links to slides, video, and sometimes code.<br>
+<br>
+When deciding between creating a type hierarchy (with either tagged or virtual<br>
+dispatch) and using templates or concepts-based polymorphism, consider whether<br>
+there is some refinement of an abstract base class which is a semantically<br>
+meaningful type on an interface boundary. If anything more refined than the<br>
+root abstract interface is meaningless to talk about as a partial extension of<br>
+the semantic model, then your use case likely fits better with polymorphism and<br>
+you should avoid using virtual dispatch. However, there may be some exigent<br>
+circumstances that require one technique or the other to be used.<br>
+<br>
+If you do need to introduce a type hierarchy, we prefer to use explicitly<br>
+closed type hierarchies with manual tagged dispatch and/or RTTI rather than the<br>
+open inheritance model and virtual dispatch that is more common in C++ code.<br>
+This is because LLVM rarely encourages library consumers to extend its core<br>
+types, and leverages the closed and tag-dispatched nature of its hierarchies to<br>
+generate significantly more efficient code. We have also found that a large<br>
+amount of our usage of type hierarchies fits better with tag-based pattern<br>
+matching rather than dynamic dispatch across a common interface. Within LLVM we<br>
+have built custom helpers to facilitate this design. See this document's<br>
+section on `isa and dyn_cast <isa>`_ and our `detailed document<br>
+<<a href="http://llvm.org/docs/HowToSetUpLLVMStyleRTTI.html" target="_blank">http://llvm.org/docs/HowToSetUpLLVMStyleRTTI.html</a>>`_ which describes how you<br>
+can implement this pattern for use with the LLVM helpers.<br>
+<br>
.. _coreclasses:<br>
<br>
The Core LLVM Class Hierarchy Reference<br>
<br>
<br>
_______________________________________________<br>
llvm-commits mailing list<br>
<a href="mailto:llvm-commits@cs.uiuc.edu">llvm-commits@cs.uiuc.edu</a><br>
<a href="http://lists.cs.uiuc.edu/mailman/listinfo/llvm-commits" target="_blank">http://lists.cs.uiuc.edu/mailman/listinfo/llvm-commits</a><br>
</blockquote></div><br></div>