Mercurial > hg > Members > tobaru > cbc > CbC_llvm

comparison docs/ProgrammersManual.rst @ 83:60c9769439b8

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
LLVM 3.7
author Tatsuki IHA <e125716@ie.u-ryukyu.ac.jp>
date Wed, 18 Feb 2015 14:55:36 +0900
parents 54457678186b
children afa8332a0e37
comparison
equal deleted inserted replaced
78:af83660cff7b 83:60c9769439b8
422 because there is no system in place to ensure that names do not conflict. If 422 because there is no system in place to ensure that names do not conflict. If
423 two different modules use the same string, they will all be turned on when the 423 two different modules use the same string, they will all be turned on when the
424 name is specified. This allows, for example, all debug information for 424 name is specified. This allows, for example, all debug information for
425 instruction scheduling to be enabled with ``-debug-only=InstrSched``, even if 425 instruction scheduling to be enabled with ``-debug-only=InstrSched``, even if
426 the source lives in multiple files. 426 the source lives in multiple files.
427
428 For performance reasons, -debug-only is not available in optimized build
429 (``--enable-optimized``) of LLVM.
427 430
428 The ``DEBUG_WITH_TYPE`` macro is also available for situations where you would 431 The ``DEBUG_WITH_TYPE`` macro is also available for situations where you would
429 like to set ``DEBUG_TYPE``, but only for one specific ``DEBUG`` statement. It 432 like to set ``DEBUG_TYPE``, but only for one specific ``DEBUG`` statement. It
430 takes an additional first parameter, which is the type to use. For example, the 433 takes an additional first parameter, which is the type to use. For example, the
431 preceding example could be written as: 434 preceding example could be written as:
1403 llvm/ADT/IntervalMap.h 1406 llvm/ADT/IntervalMap.h
1404 ^^^^^^^^^^^^^^^^^^^^^^ 1407 ^^^^^^^^^^^^^^^^^^^^^^
1405 1408
1406 IntervalMap is a compact map for small keys and values. It maps key intervals 1409 IntervalMap is a compact map for small keys and values. It maps key intervals
1407 instead of single keys, and it will automatically coalesce adjacent intervals. 1410 instead of single keys, and it will automatically coalesce adjacent intervals.
1408 When then map only contains a few intervals, they are stored in the map object 1411 When the map only contains a few intervals, they are stored in the map object
1409 itself to avoid allocations. 1412 itself to avoid allocations.
1410 1413
1411 The IntervalMap iterators are quite big, so they should not be passed around as 1414 The IntervalMap iterators are quite big, so they should not be passed around as
1412 STL iterators. The heavyweight iterators allow a smaller data structure. 1415 STL iterators. The heavyweight iterators allow a smaller data structure.
1413 1416
2475 set). Following this pointer brings us to the ``User``. A portable trick 2478 set). Following this pointer brings us to the ``User``. A portable trick
2476 ensures that the first bytes of ``User`` (if interpreted as a pointer) never has 2479 ensures that the first bytes of ``User`` (if interpreted as a pointer) never has
2477 the LSBit set. (Portability is relying on the fact that all known compilers 2480 the LSBit set. (Portability is relying on the fact that all known compilers
2478 place the ``vptr`` in the first word of the instances.) 2481 place the ``vptr`` in the first word of the instances.)
2479 2482
2483 .. _polymorphism:
2484
2485 Designing Type Hiercharies and Polymorphic Interfaces
2486 -----------------------------------------------------
2487
2488 There are two different design patterns that tend to result in the use of
2489 virtual dispatch for methods in a type hierarchy in C++ programs. The first is
2490 a genuine type hierarchy where different types in the hierarchy model
2491 a specific subset of the functionality and semantics, and these types nest
2492 strictly within each other. Good examples of this can be seen in the ``Value``
2493 or ``Type`` type hierarchies.
2494
2495 A second is the desire to dispatch dynamically across a collection of
2496 polymorphic interface implementations. This latter use case can be modeled with
2497 virtual dispatch and inheritance by defining an abstract interface base class
2498 which all implementations derive from and override. However, this
2499 implementation strategy forces an **"is-a"** relationship to exist that is not
2500 actually meaningful. There is often not some nested hierarchy of useful
2501 generalizations which code might interact with and move up and down. Instead,
2502 there is a singular interface which is dispatched across a range of
2503 implementations.
2504
2505 The preferred implementation strategy for the second use case is that of
2506 generic programming (sometimes called "compile-time duck typing" or "static
2507 polymorphism"). For example, a template over some type parameter ``T`` can be
2508 instantiated across any particular implementation that conforms to the
2509 interface or *concept*. A good example here is the highly generic properties of
2510 any type which models a node in a directed graph. LLVM models these primarily
2511 through templates and generic programming. Such templates include the
2512 ``LoopInfoBase`` and ``DominatorTreeBase``. When this type of polymorphism
2513 truly needs **dynamic** dispatch you can generalize it using a technique
2514 called *concept-based polymorphism*. This pattern emulates the interfaces and
2515 behaviors of templates using a very limited form of virtual dispatch for type
2516 erasure inside its implementation. You can find examples of this technique in
2517 the ``PassManager.h`` system, and there is a more detailed introduction to it
2518 by Sean Parent in several of his talks and papers:
2519
2520 #. `Inheritance Is The Base Class of Evil
2521 <http://channel9.msdn.com/Events/GoingNative/2013/Inheritance-Is-The-Base-Class-of-Evil>`_
2522 - The GoingNative 2013 talk describing this technique, and probably the best
2523 place to start.
2524 #. `Value Semantics and Concepts-based Polymorphism
2525 <http://www.youtube.com/watch?v=_BpMYeUFXv8>`_ - The C++Now! 2012 talk
2526 describing this technique in more detail.
2527 #. `Sean Parent's Papers and Presentations
2528 <http://github.com/sean-parent/sean-parent.github.com/wiki/Papers-and-Presentations>`_
2529 - A Github project full of links to slides, video, and sometimes code.
2530
2531 When deciding between creating a type hierarchy (with either tagged or virtual
2532 dispatch) and using templates or concepts-based polymorphism, consider whether
2533 there is some refinement of an abstract base class which is a semantically
2534 meaningful type on an interface boundary. If anything more refined than the
2535 root abstract interface is meaningless to talk about as a partial extension of
2536 the semantic model, then your use case likely fits better with polymorphism and
2537 you should avoid using virtual dispatch. However, there may be some exigent
2538 circumstances that require one technique or the other to be used.
2539
2540 If you do need to introduce a type hierarchy, we prefer to use explicitly
2541 closed type hierarchies with manual tagged dispatch and/or RTTI rather than the
2542 open inheritance model and virtual dispatch that is more common in C++ code.
2543 This is because LLVM rarely encourages library consumers to extend its core
2544 types, and leverages the closed and tag-dispatched nature of its hierarchies to
2545 generate significantly more efficient code. We have also found that a large
2546 amount of our usage of type hierarchies fits better with tag-based pattern
2547 matching rather than dynamic dispatch across a common interface. Within LLVM we
2548 have built custom helpers to facilitate this design. See this document's
2549 section on :ref:`isa and dyn_cast <isa>` and our :doc:`detailed document
2550 <HowToSetUpLLVMStyleRTTI>` which describes how you can implement this
2551 pattern for use with the LLVM helpers.
2552
2480 .. _coreclasses: 2553 .. _coreclasses:
2481 2554
2482 The Core LLVM Class Hierarchy Reference 2555 The Core LLVM Class Hierarchy Reference
2483 ======================================= 2556 =======================================
2484 2557