shylie/llvm-project
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

[llvm] Proofread ProgrammersManual.rst (#151853)

Browse Source 
Co-authored-by: Tim Gymnich <tim@gymni.ch>
This commit is contained in:
Kazu Hirata 2025-08-03 09:41:27 -07:00 committed by GitHub
parent 90f1e04954
commit 84fa58c5d8
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
1 changed files with 41 additions and 41 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

82
llvm/docs/ProgrammersManual.rst
View File

@ -486,7 +486,7 @@ Success values are very cheap to construct and return - they have minimal
impact on program performance.
Failure values are constructed using ``make_error<T>``, where ``T`` is any class
that inherits from the ErrorInfo utility, E.g.:
that inherits from the ``ErrorInfo`` utility, E.g.:
.. code-block:: c++
@ -1351,7 +1351,7 @@ The ``llvm/Support/DebugCounter.h`` (`doxygen
provides a class named ``DebugCounter`` that can be used to create
command-line counter options that control execution of parts of your code.
Define your DebugCounter like this:
Define your ``DebugCounter`` like this:
.. code-block:: c++
@ -1677,7 +1677,7 @@ page and one extra indirection when accessing elements with their positional
index.
In order to minimise the memory footprint of this container, it's important to
balance the PageSize so that it's not too small (otherwise the overhead of the
balance the ``PageSize`` so that it's not too small (otherwise the overhead of the
pointer per page might become too high) and not too big (otherwise the memory
is wasted if the page is not fully used).
@ -2203,17 +2203,17 @@ inserting elements into both a set-like container and the sequential container,
using the set-like container for uniquing and the sequential container for
iteration.
The difference between SetVector and other sets is that the order of iteration
is guaranteed to match the order of insertion into the SetVector. This property
The difference between ``SetVector`` and other sets is that the order of iteration
is guaranteed to match the order of insertion into the ``SetVector``. This property
is really important for things like sets of pointers. Because pointer values
are non-deterministic (e.g. vary across runs of the program on different
machines), iterating over the pointers in the set will not be in a well-defined
order.
The drawback of SetVector is that it requires twice as much space as a normal
The drawback of ``SetVector`` is that it requires twice as much space as a normal
set and has the sum of constant factors from the set-like container and the
sequential container that it uses. Use it **only** if you need to iterate over
the elements in a deterministic order. SetVector is also expensive to delete
the elements in a deterministic order. ``SetVector`` is also expensive to delete
elements out of (linear time), unless you use its "pop_back" method, which is
faster.
@ -2369,22 +2369,22 @@ llvm/IR/ValueMap.h
ValueMap is a wrapper around a :ref:`DenseMap <dss_densemap>` mapping
``Value*``\ s (or subclasses) to another type. When a Value is deleted or
RAUW'ed, ValueMap will update itself so the new version of the key is mapped to
RAUW'ed, ``ValueMap`` will update itself so the new version of the key is mapped to
the same value, just as if the key were a WeakVH. You can configure exactly how
this happens, and what else happens on these two events, by passing a ``Config``
parameter to the ValueMap template.
parameter to the ``ValueMap`` template.
.. _dss_intervalmap:
llvm/ADT/IntervalMap.h
^^^^^^^^^^^^^^^^^^^^^^
IntervalMap is a compact map for small keys and values. It maps key intervals
``IntervalMap`` is a compact map for small keys and values. It maps key intervals
instead of single keys, and it will automatically coalesce adjacent intervals.
When the map only contains a few intervals, they are stored in the map object
itself to avoid allocations.
The IntervalMap iterators are quite big, so they should not be passed around as
The ``IntervalMap`` iterators are quite big, so they should not be passed around as
STL iterators. The heavyweight iterators allow a smaller data structure.
.. _dss_intervaltree:
@ -2396,7 +2396,7 @@ llvm/ADT/IntervalTree.h
allows finding all intervals that overlap with any given point. At this time,
it does not support any deletion or rebalancing operations.
The IntervalTree is designed to be set up once, and then queried without any
The ``IntervalTree`` is designed to be set up once, and then queried without any
further additions.
.. _dss_map:
@ -2435,10 +2435,10 @@ necessary to remove elements, it's best to remove them in bulk using
llvm/ADT/IntEqClasses.h
^^^^^^^^^^^^^^^^^^^^^^^
IntEqClasses provides a compact representation of equivalence classes of small
``IntEqClasses`` provides a compact representation of equivalence classes of small
integers. Initially, each integer in the range 0..n-1 has its own equivalence
class. Classes can be joined by passing two class representatives to the
join(a, b) method. Two integers are in the same class when findLeader() returns
``join(a, b)`` method. Two integers are in the same class when ``findLeader()`` returns
the same representative.
Once all equivalence classes are formed, the map can be compressed so each
@ -2451,11 +2451,11 @@ it can be edited again.
llvm/ADT/ImmutableMap.h
^^^^^^^^^^^^^^^^^^^^^^^
ImmutableMap is an immutable (functional) map implementation based on an AVL
``ImmutableMap`` is an immutable (functional) map implementation based on an AVL
tree. Adding or removing elements is done through a Factory object and results
in the creation of a new ImmutableMap object. If an ImmutableMap already exists
in the creation of a new ``ImmutableMap`` object. If an ``ImmutableMap`` already exists
with the given key set, then the existing one is returned; equality is compared
with a FoldingSetNodeID. The time and space complexity of add or remove
with a ``FoldingSetNodeID``. The time and space complexity of add or remove
operations is logarithmic in the size of the original map.
.. _dss_othermap:
@ -2490,11 +2490,11 @@ somehow. In any case, please don't use it.
BitVector
^^^^^^^^^
The BitVector container provides a dynamic size set of bits for manipulation.
The ``BitVector`` container provides a dynamic size set of bits for manipulation.
It supports individual bit setting/testing, as well as set operations. The set
operations take time O(size of bitvector), but operations are performed one word
at a time, instead of one bit at a time. This makes the BitVector very fast for
set operations compared to other containers. Use the BitVector when you expect
at a time, instead of one bit at a time. This makes the ``BitVector`` very fast for
set operations compared to other containers. Use the ``BitVector`` when you expect
the number of set bits to be high (i.e. a dense set).
.. _dss_smallbitvector:
@ -2516,29 +2516,29 @@ its operator[] does not provide an assignable lvalue.
SparseBitVector
^^^^^^^^^^^^^^^
The SparseBitVector container is much like BitVector, with one major difference:
Only the bits that are set, are stored. This makes the SparseBitVector much
more space efficient than BitVector when the set is sparse, as well as making
The ``SparseBitVector`` container is much like ``BitVector``, with one major difference:
Only the bits that are set, are stored. This makes the ``SparseBitVector`` much
more space efficient than ``BitVector`` when the set is sparse, as well as making
set operations O(number of set bits) instead of O(size of universe). The
downside to the SparseBitVector is that setting and testing of random bits is
O(N), and on large SparseBitVectors, this can be slower than BitVector. In our
downside to the ``SparseBitVector`` is that setting and testing of random bits is
O(N), and on large ``SparseBitVectors``, this can be slower than ``BitVector``. In our
implementation, setting or testing bits in sorted order (either forwards or
reverse) is O(1) worst case. Testing and setting bits within 128 bits (depends
on size) of the current bit is also O(1). As a general statement,
testing/setting bits in a SparseBitVector is O(distance away from last set bit).
testing/setting bits in a ``SparseBitVector`` is O(distance away from last set bit).
.. _dss_coalescingbitvector:
CoalescingBitVector
^^^^^^^^^^^^^^^^^^^
The CoalescingBitVector container is similar in principle to a SparseBitVector,
The ``CoalescingBitVector`` container is similar in principle to a ``SparseBitVector``,
but is optimized to represent large contiguous ranges of set bits compactly. It
does this by coalescing contiguous ranges of set bits into intervals. Searching
for a bit in a CoalescingBitVector is O(log(gaps between contiguous ranges)).
for a bit in a ``CoalescingBitVector`` is O(log(gaps between contiguous ranges)).
CoalescingBitVector is a better choice than BitVector when gaps between ranges
of set bits are large. It's a better choice than SparseBitVector when find()
``CoalescingBitVector`` is a better choice than ``BitVector`` when gaps between ranges
of set bits are large. It's a better choice than ``SparseBitVector`` when find()
operations must have fast, predictable performance. However, it's not a good
choice for representing sets which have lots of very short ranges. E.g. the set
`{2*x : x \in [0, n)}` would be a pathological input.
@ -2773,7 +2773,7 @@ Turning an iterator into a class pointer (and vice-versa)
Sometimes, it'll be useful to grab a reference (or pointer) to a class instance
when all you've got at hand is an iterator. Well, extracting a reference or a
pointer from an iterator is very straight-forward. Assuming that ``i`` is a
pointer from an iterator is very straightforward. Assuming that ``i`` is a
``BasicBlock::iterator`` and ``j`` is a ``BasicBlock::const_iterator``:
.. code-block:: c++
@ -2805,7 +2805,7 @@ Say that you're writing a FunctionPass and would like to count all the locations
in the entire module (that is, across every ``Function``) where a certain
function (i.e., some ``Function *``) is already in scope. As you'll learn
later, you may want to use an ``InstVisitor`` to accomplish this in a much more
straight-forward manner, but this example will allow us to explore how you'd do
straightforward manner, but this example will allow us to explore how you'd do
it if you didn't have ``InstVisitor`` around. In pseudo-code, this is what we
want to do:
@ -2932,7 +2932,7 @@ Creating and inserting new ``Instruction``\ s
*Instantiating Instructions*
Creation of ``Instruction``\ s is straight-forward: simply call the constructor
Creation of ``Instruction``\ s is straightforward: simply call the constructor
for the kind of instruction to instantiate and provide the necessary parameters.
For example, an ``AllocaInst`` only *requires* a (const-ptr-to) ``Type``. Thus:
@ -3050,7 +3050,7 @@ Deleting Instructions
^^^^^^^^^^^^^^^^^^^^^
Deleting an instruction from an existing sequence of instructions that form a
BasicBlock_ is very straight-forward: just call the instruction's
``BasicBlock`` is very straightforward: just call the instruction's
``eraseFromParent()`` method. For example:
.. code-block:: c++
@ -3850,16 +3850,16 @@ Important Subclasses of Constant
any width.
* ``const APInt& getValue() const``: Returns the underlying
value of this constant, an APInt value.
value of this constant, an ``APInt`` value.
* ``int64_t getSExtValue() const``: Converts the underlying APInt value to an
int64_t via sign extension. If the value (not the bit width) of the APInt
is too large to fit in an int64_t, an assertion will result. For this
``int64_t`` via sign extension. If the value (not the bit width) of the APInt
is too large to fit in an ``int64_t``, an assertion will result. For this
reason, use of this method is discouraged.
* ``uint64_t getZExtValue() const``: Converts the underlying APInt value
to a uint64_t via zero extension. IF the value (not the bit width) of the
APInt is too large to fit in a uint64_t, an assertion will result. For this
* ``uint64_t getZExtValue() const``: Converts the underlying ``APInt`` value
to a ``uint64_t`` via zero extension. If the value (not the bit width) of the
APInt is too large to fit in a ``uint64_t``, an assertion will result. For this
reason, use of this method is discouraged.
* ``static ConstantInt* get(const APInt& Val)``: Returns the ConstantInt
@ -4148,7 +4148,7 @@ Important Public Members of the ``BasicBlock`` class
new block, and a :ref:`Function <c_Function>` to insert it into. If the
``Parent`` parameter is specified, the new ``BasicBlock`` is automatically
inserted at the end of the specified :ref:`Function <c_Function>`, if not
specified, the BasicBlock must be manually inserted into the :ref:`Function
specified, the ``BasicBlock`` must be manually inserted into the :ref:`Function
<c_Function>`.
* | ``BasicBlock::iterator`` - Typedef for instruction list iterator