CbC/CbC_llvm: docs/ProgrammersManual.rst comparison

comparison docs/ProgrammersManual.rst @ 147:c2174574ed3a

LLVM 10

author	Shinji KONO <kono@ie.u-ryukyu.ac.jp>
date	Wed, 14 Aug 2019 16:55:33 +0900
parents	3a76565eade5
children

comparison

equal deleted inserted replaced

-:3a76565eade5
+:c2174574ed3a
 ``instanceof`` operator, can be abused.  In particular, you should not use big
 chained ``if/then/else`` blocks to check for lots of different variants of
 classes.  If you find yourself wanting to do this, it is much cleaner and more
 efficient to use the ``InstVisitor`` class to dispatch over the instruction
 type directly.
+``isa_and_nonnull<>``:
+The ``isa_and_nonnull<>`` operator works just like the ``isa<>`` operator,
+except that it allows for a null pointer as an argument (which it then
+returns false).  This can sometimes be useful, allowing you to combine several
+null checks into one.
 ``cast_or_null<>``:
 The ``cast_or_null<>`` operator works just like the ``cast<>`` operator,
 except that it allows for a null pointer as an argument (which it then
 propagates).  This can sometimes be useful, allowing you to combine several
 Many kinds of errors have no recovery strategy, the only action that can be
 taken is to report them to the user so that the user can attempt to fix the
 environment. In this case representing the error as a string makes perfect
 sense. LLVM provides the ``StringError`` class for this purpose. It takes two
 arguments: A string error message, and an equivalent ``std::error_code`` for
-interoperability:
+interoperability. It also provides a ``createStringError`` function to simplify
+common usage of this class:
-.. code-block:: c++
+.. code-block:: c++
-make_error<StringError>("Bad executable",
-make_error_code(errc::executable_format_error"));
+// These two lines of code are equivalent:
+make_error<StringError>("Bad executable", errc::executable_format_error);
+createStringError(errc::executable_format_error, "Bad executable");
 If you're certain that the error you're building will never need to be converted
 to a ``std::error_code`` you can use the ``inconvertibleErrorCode()`` function:
 .. code-block:: c++
-make_error<StringError>("Bad executable", inconvertibleErrorCode());
+createStringError(inconvertibleErrorCode(), "Bad executable");
 This should be done only after careful consideration. If any attempt is made to
 convert this error to a ``std::error_code`` it will trigger immediate program
 termination. Unless you are certain that your errors will not need
 interoperability you should look for an existing ``std::error_code`` that you
 can convert to, and even (as painful as it is) consider introducing a new one as
 a stopgap measure.
+``createStringError`` can take ``printf`` style format specifiers to provide a
+formatted message:
+.. code-block:: c++
+createStringError(errc::executable_format_error,
+"Bad executable: %s", FileName);
 Interoperability with std::error_code and ErrorOr
 """""""""""""""""""""""""""""""""""""""""""""""""
 Many existing LLVM APIs use ``std::error_code`` and its partner ``ErrorOr<T>``
 ...
 }
 Like the ExitOnError utility, cantFail simplifies control flow. Their treatment
 of error cases is very different however: Where ExitOnError is guaranteed to
-terminate the program on an error input, cantFile simply asserts that the result
+terminate the program on an error input, cantFail simply asserts that the result
 is success. In debug builds this will result in an assertion failure if an error
 is encountered. In release builds the behavior of cantFail for failure values is
 undefined. As such, care must be taken in the use of cantFail: clients must be
 certain that a cantFail wrapped call really can not fail with the given
 arguments.
 Building fallible iterators and iterator ranges
 """""""""""""""""""""""""""""""""""""""""""""""
 The archive walking examples above retrieve archive members by index, however
 this requires considerable boiler-plate for iteration and error checking. We can
-clean this up by using ``Error`` with the "fallible iterator" pattern. The usual
+clean this up by using the "fallible iterator" pattern, which supports the
-C++ iterator patterns do not allow for failure on increment, but we can
+following natural iteration idiom for fallible containers like Archive:
-incorporate support for it by having iterators hold an Error reference through
-which they can report failure. In this pattern, if an increment operation fails
-the failure is recorded via the Error reference and the iterator value is set to
-the end of the range in order to terminate the loop. This ensures that the
-dereference operation is safe anywhere that an ordinary iterator dereference
-would be safe (i.e. when the iterator is not equal to end). Where this pattern
-is followed (as in the ``llvm::object::Archive`` class) the result is much
-cleaner iteration idiom:
 .. code-block:: c++
 Error Err;
 for (auto &Child : Ar->children(Err)) {
-// Use Child - we only enter the loop when it's valid
+// Use Child - only enter the loop when it's valid
+// Allow early exit from the loop body, since we know that Err is success
+// when we're inside the loop.
+if (BailOutOn(Child))
+return;
 ...
 }
 // Check Err after the loop to ensure it didn't break due to an error.
 if (Err)
 return Err;
+To enable this idiom, iterators over fallible containers are written in a
+natural style, with their ``++`` and ``--`` operators replaced with fallible
+``Error inc()`` and ``Error dec()`` functions. E.g.:
+.. code-block:: c++
+class FallibleChildIterator {
+public:
+FallibleChildIterator(Archive &A, unsigned ChildIdx);
+Archive::Child &operator*();
+friend bool operator==(const ArchiveIterator &LHS,
+const ArchiveIterator &RHS);
+// operator++/operator-- replaced with fallible increment / decrement:
+Error inc() {
+if (!A.childValid(ChildIdx + 1))
+return make_error<BadArchiveMember>(...);
+++ChildIdx;
+return Error::success();
+}
+Error dec() { ... }
+};
+Instances of this kind of fallible iterator interface are then wrapped with the
+fallible_iterator utility which provides ``operator++`` and ``operator--``,
+returning any errors via a reference passed in to the wrapper at construction
+time. The fallible_iterator wrapper takes care of (a) jumping to the end of the
+range on error, and (b) marking the error as checked whenever an iterator is
+compared to ``end`` and found to be inequal (in particular: this marks the
+error as checked throughout the body of a range-based for loop), enabling early
+exit from the loop without redundant error checking.
+Instances of the fallible iterator interface (e.g. FallibleChildIterator above)
+are wrapped using the ``make_fallible_itr`` and ``make_fallible_end``
+functions. E.g.:
+.. code-block:: c++
+class Archive {
+public:
+using child_iterator = fallible_iterator<FallibleChildIterator>;
+child_iterator child_begin(Error &Err) {
+return make_fallible_itr(FallibleChildIterator(*this, 0), Err);
+}
+child_iterator child_end() {
+return make_fallible_end(FallibleChildIterator(*this, size()));
+}
+iterator_range<child_iterator> children(Error &Err) {
+return make_range(child_begin(Err), child_end());
+}
+};
+Using the fallible_iterator utility allows for both natural construction of
+fallible iterators (using failing ``inc`` and ``dec`` operations) and
+relatively natural use of c++ iterator/loop idioms.
 .. _function_apis:
 More information on Error and its related utilities can be found in the
 Error.h header file.
 using ``std::function``. ``function_ref`` is small enough that it should always
 be passed by value.
 .. _DEBUG:
-The ``DEBUG()`` macro and ``-debug`` option
+The ``LLVM_DEBUG()`` macro and ``-debug`` option
--------------------------------------------
+------------------------------------------------
 Often when working on your pass you will put a bunch of debugging printouts and
 other code into your pass.  After you get it working, you want to remove it, but
 you may need it again in the future (to work out new bugs that you run across).
 you don't want them to always be noisy.  A standard compromise is to comment
 them out, allowing you to enable them if you need them in the future.
 The ``llvm/Support/Debug.h`` (`doxygen
 <http://llvm.org/doxygen/Debug_8h_source.html>`__) file provides a macro named
-``DEBUG()`` that is a much nicer solution to this problem.  Basically, you can
+``LLVM_DEBUG()`` that is a much nicer solution to this problem.  Basically, you can
-put arbitrary code into the argument of the ``DEBUG`` macro, and it is only
+put arbitrary code into the argument of the ``LLVM_DEBUG`` macro, and it is only
 executed if '``opt``' (or any other tool) is run with the '``-debug``' command
 line argument:
 .. code-block:: c++
-DEBUG(dbgs() << "I am here!\n");
+LLVM_DEBUG(dbgs() << "I am here!\n");
 Then you can run your pass like this:
 .. code-block:: none
 $ opt < a.bc > /dev/null -mypass
 <no output>
 $ opt < a.bc > /dev/null -mypass -debug
 I am here!
-Using the ``DEBUG()`` macro instead of a home-brewed solution allows you to not
+Using the ``LLVM_DEBUG()`` macro instead of a home-brewed solution allows you to not
 have to create "yet another" command line option for the debug output for your
-pass.  Note that ``DEBUG()`` macros are disabled for non-asserts builds, so they
+pass.  Note that ``LLVM_DEBUG()`` macros are disabled for non-asserts builds, so they
 do not cause a performance impact at all (for the same reason, they should also
 not contain side-effects!).
-One additional nice thing about the ``DEBUG()`` macro is that you can enable or
+One additional nice thing about the ``LLVM_DEBUG()`` macro is that you can enable or
 disable it directly in gdb.  Just use "``set DebugFlag=0``" or "``set
 DebugFlag=1``" from the gdb if the program is running.  If the program hasn't
 been started yet, you can always just run it with ``-debug``.
 .. _DEBUG_TYPE:
 follows:
 .. code-block:: c++
 #define DEBUG_TYPE "foo"
-DEBUG(dbgs() << "'foo' debug type\n");
+LLVM_DEBUG(dbgs() << "'foo' debug type\n");
 #undef  DEBUG_TYPE
 #define DEBUG_TYPE "bar"
-DEBUG(dbgs() << "'bar' debug type\n");
+LLVM_DEBUG(dbgs() << "'bar' debug type\n");
 #undef  DEBUG_TYPE
 Then you can run your pass like this:
 .. code-block:: none
 DAG.viewGraph()`` to pop up a window.  Alternatively, you can sprinkle calls to
 these functions in your code in places you want to debug.
 Getting this to work requires a small amount of setup.  On Unix systems
 with X11, install the `graphviz <http://www.graphviz.org>`_ toolkit, and make
-sure 'dot' and 'gv' are in your path.  If you are running on Mac OS X, download
+sure 'dot' and 'gv' are in your path.  If you are running on macOS, download
-and install the Mac OS X `Graphviz program
+and install the macOS `Graphviz program
 <http://www.pixelglow.com/graphviz/>`_ and add
 ``/Applications/Graphviz.app/Contents/MacOS/`` (or wherever you install it) to
 your path. The programs need not be present when configuring, building or
 running LLVM and can simply be installed when needed during an active debug
 session.
 ``vector<Type>``: it supports efficient iteration, lays out elements in memory
 order (so you can do pointer arithmetic between elements), supports efficient
 push_back/pop_back operations, supports efficient random access to its elements,
 etc.
-The advantage of SmallVector is that it allocates space for some number of
+The main advantage of SmallVector is that it allocates space for some number of
 elements (N) **in the object itself**.  Because of this, if the SmallVector is
 dynamically smaller than N, no malloc is performed.  This can be a big win in
 cases where the malloc/free call is far more expensive than the code that
 fiddles around with the elements.
 SmallVectors are most useful when on the stack.
 SmallVector also provides a nice portable and efficient replacement for
 ``alloca``.
+SmallVector has grown a few other minor advantages over std::vector, causing
+``SmallVector<Type, 0>`` to be preferred over ``std::vector<Type>``.
+#. std::vector is exception-safe, and some implementations have pessimizations
+that copy elements when SmallVector would move them.
+#. SmallVector understands ``llvm::is_trivially_copyable<Type>`` and uses realloc aggressively.
+#. Many LLVM APIs take a SmallVectorImpl as an out parameter (see the note
+below).
+#. SmallVector with N equal to 0 is smaller than std::vector on 64-bit
+platforms, since it uses ``unsigned`` (instead of ``void*``) for its size
+and capacity.
 .. note::
 Prefer to use ``SmallVectorImpl<T>`` as a parameter type.
 In APIs that don't care about the "small size" (most?), prefer to use
 .. _dss_vector:
 <vector>
 ^^^^^^^^
-``std::vector`` is well loved and respected.  It is useful when SmallVector
+``std::vector<T>`` is well loved and respected.  However, ``SmallVector<T, 0>``
-isn't: when the size of the vector is often large (thus the small optimization
+is often a better option due to the advantages listed above.  std::vector is
-will rarely be a benefit) or if you will be allocating many instances of the
+still useful when you need to store more than ``UINT32_MAX`` elements or when
-vector itself (which would waste space for elements that aren't in the
+interfacing with code that expects vectors :).
-container).  vector is also useful when interfacing with code that expects
-vectors :).
 One worthwhile note about std::vector: avoid code like this:
 .. code-block:: c++
 A sorted 'vector'
 ^^^^^^^^^^^^^^^^^
 If you intend to insert a lot of elements, then do a lot of queries, a great
-approach is to use a vector (or other sequential container) with
+approach is to use an std::vector (or other sequential container) with
 std::sort+std::unique to remove duplicates.  This approach works really well if
 your usage pattern has these two distinct phases (insert then query), and can be
 coupled with a good choice of :ref:`sequential container <ds_sequential>`.
 This combination provides the several nice properties: the result data is
 representation that guarantees efficient access (for most types, it falls back
 to :ref:`std::set <dss_set>`, but for pointers it uses something far better,
 :ref:`SmallPtrSet <dss_smallptrset>`.
 The magic of this class is that it handles small sets extremely efficiently, but
-gracefully handles extremely large sets without loss of efficiency.  The
+gracefully handles extremely large sets without loss of efficiency.
-drawback is that the interface is quite small: it supports insertion, queries
-and erasing, but does not support iteration.
 .. _dss_smallptrset:
 llvm/ADT/SmallPtrSet.h
 ^^^^^^^^^^^^^^^^^^^^^^
 ``SmallPtrSet`` has all the advantages of ``SmallSet`` (and a ``SmallSet`` of
-pointers is transparently implemented with a ``SmallPtrSet``), but also supports
+pointers is transparently implemented with a ``SmallPtrSet``). If more than N
-iterators.  If more than N insertions are performed, a single quadratically
+insertions are performed, a single quadratically probed hash table is allocated
-probed hash table is allocated and grows as needed, providing extremely
+and grows as needed, providing extremely efficient access (constant time
-efficient access (constant time insertion/deleting/queries with low constant
+insertion/deleting/queries with low constant factors) and is very stingy with
-factors) and is very stingy with malloc traffic.
+malloc traffic.
 Note that, unlike :ref:`std::set <dss_set>`, the iterators of ``SmallPtrSet``
 are invalidated whenever an insertion occurs.  Also, the values visited by the
 iterators are not visited in sorted order.
 Iterating over def-use & use-def chains
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 Frequently, we might have an instance of the ``Value`` class (`doxygen
 <http://llvm.org/doxygen/classllvm_1_1Value.html>`__) and we want to determine
-which ``User`` s use the ``Value``.  The list of all ``User``\ s of a particular
+which ``User``\ s use the ``Value``.  The list of all ``User``\ s of a particular
 ``Value`` is called a *def-use* chain.  For example, let's say we have a
 ``Function*`` named ``F`` to a particular function ``foo``.  Finding all of the
 instructions that *use* ``foo`` is as simple as iterating over the *def-use*
 chain of ``F``:
 GlobalVariable *GV = .. ;
 GV->eraseFromParent();
-.. _create_types:
-How to Create Types
--------------------
-In generating IR, you may need some complex types.  If you know these types
-statically, you can use ``TypeBuilder<...>::get()``, defined in
-``llvm/Support/TypeBuilder.h``, to retrieve them.  ``TypeBuilder`` has two forms
-depending on whether you're building types for cross-compilation or native
-library use.  ``TypeBuilder<T, true>`` requires that ``T`` be independent of the
-host environment, meaning that it's built out of types from the ``llvm::types``
-(`doxygen <http://llvm.org/doxygen/namespacellvm_1_1types.html>`__) namespace
-and pointers, functions, arrays, etc. built of those.  ``TypeBuilder<T, false>``
-additionally allows native C types whose size may depend on the host compiler.
-For example,
-.. code-block:: c++
-FunctionType *ft = TypeBuilder<types::i<8>(types::i<32>*), true>::get();
-is easier to read and write than the equivalent
-.. code-block:: c++
-std::vector<const Type*> params;
-params.push_back(PointerType::getUnqual(Type::Int32Ty));
-FunctionType *ft = FunctionType::get(Type::Int8Ty, params, false);
-See the `class comment
-<http://llvm.org/doxygen/TypeBuilder_8h_source.html#l00001>`_ for more details.
 .. _threading:
 Threads and LLVM
 ================
 Conceptually, ``LLVMContext`` provides isolation.  Every LLVM entity
 (``Module``\ s, ``Value``\ s, ``Type``\ s, ``Constant``\ s, etc.) in LLVM's
 in-memory IR belongs to an ``LLVMContext``.  Entities in different contexts
 *cannot* interact with each other: ``Module``\ s in different contexts cannot be
 linked together, ``Function``\ s cannot be added to ``Module``\ s in different
-contexts, etc.  What this means is that is is safe to compile on multiple
+contexts, etc.  What this means is that is safe to compile on multiple
 threads simultaneously, as long as no two threads operate on entities within the
 same context.
 In practice, very few places in the API require the explicit specification of a
 ``LLVMContext``, other than the ``Type`` creation/lookup APIs.  Because every
 libraries built with `LLVM_ENABLE_ABI_BREAKING_CHECKS` are not ABI
 compatible LLVM libraries built without it defined.  By default,
 turning on assertions also turns on `LLVM_ENABLE_ABI_BREAKING_CHECKS`
 so a default +Asserts build is not ABI compatible with a
 default -Asserts build.  Clients that want ABI compatibility
-between +Asserts and -Asserts builds should use the CMake or autoconf
+between +Asserts and -Asserts builds should use the CMake build system
-build systems to set `LLVM_ENABLE_ABI_BREAKING_CHECKS` independently
+to set `LLVM_ENABLE_ABI_BREAKING_CHECKS` independently
 of `LLVM_ENABLE_ASSERTIONS`.
 .. _coreclasses:
 The Core LLVM Class Hierarchy Reference
 * ``Function *getFunction(StringRef Name) const``
 Look up the specified function in the ``Module`` SymbolTable_.  If it does not
 exist, return ``null``.
-* ``Function *getOrInsertFunction(const std::string &Name, const FunctionType
+* ``FunctionCallee getOrInsertFunction(const std::string &Name,
-*T)``
+const FunctionType *T)``
-Look up the specified function in the ``Module`` SymbolTable_.  If it does not
+Look up the specified function in the ``Module`` SymbolTable_.  If
-exist, add an external declaration for the function and return it.
+it does not exist, add an external declaration for the function and
+return it. Note that the function signature already present may not
+match the requested signature. Thus, in order to enable the common
+usage of passing the result directly to EmitCall, the return type is
+a struct of ``{FunctionType *T, Constant *FunctionPtr}``, rather
+than simply the ``Function*`` with potentially an unexpected
+signature.
 * ``std::string getTypeName(const Type *Ty)``
 If there is at least one entry in the SymbolTable_ for the specified Type_,
 return it.  Otherwise return the empty string.
 .. _CmpInst:
 * ``CmpInst``
-This subclass respresents the two comparison instructions,
+This subclass represents the two comparison instructions,
 `ICmpInst <LangRef.html#i_icmp>`_ (integer opreands), and
 `FCmpInst <LangRef.html#i_fcmp>`_ (floating point operands).
-.. _TerminatorInst:
-* ``TerminatorInst``
-This subclass is the parent of all terminator instructions (those which can
-terminate a block).
 .. _m_Instruction:
 Important Public Members of the ``Instruction`` class
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 This class represents a single entry single exit section of the code, commonly
 known as a basic block by the compiler community.  The ``BasicBlock`` class
 maintains a list of Instruction_\ s, which form the body of the block.  Matching
 the language definition, the last element of this list of instructions is always
-a terminator instruction (a subclass of the TerminatorInst_ class).
+a terminator instruction.
 In addition to tracking the list of instructions that make up the block, the
 ``BasicBlock`` class also keeps track of the :ref:`Function <c_Function>` that
 it is embedded into.
 * ``Function *getParent()``
 Returns a pointer to :ref:`Function <c_Function>` the block is embedded into,
 or a null pointer if it is homeless.
-* ``TerminatorInst *getTerminator()``
+* ``Instruction *getTerminator()``
 Returns a pointer to the terminator instruction that appears at the end of the
 ``BasicBlock``.  If there is no terminator instruction, or if the last
 instruction in the block is not a terminator, then a null pointer is returned.

Mercurial > hg > CbC > CbC_llvm

comparison docs/ProgrammersManual.rst @ 147:c2174574ed3a