llvm dev - Feb 2019 - How to understand LLVM-C API?

Hi,

I am learning LLVM-C API (I don't plan to learn the C++ API at this
moment.). I am able to get this example to compile and run.

http://www.duskborn.com/posts/optimizing-llvm-ir-from-the-c-api/

However, I don't understand the usage of LLVMReplaceAllUsesWith().

    // replace all uses of the old instruction with the new one
    LLVMReplaceAllUsesWith(instruction, replacementValue);

How can a value replace an instruction?

The reference is not helpful either. It shows both OldVal, NewVal are
just LLVMValueRef,  why an instruction can be used as a value?

http://llvm.org/doxygen/group__LLVMCCoreValueGeneral.html#ga5180328ab0b7fd00cd814304a33c0b0e

In general, the reference generated by doxygen is not good for
learning and the type hierarchy is too complex. Is there any more
effective materials for learning the C API.

Thanks.

-- 
Regards,
Peng

On Mon, 18 Feb 2019 at 08:53, Peng Yu via llvm-dev
<llvm-dev at lists.llvm.org> wrote:
> How can a value replace an instruction?
This API doesn't remove (or really touch) the instruction itself, just
any other instructions that use its output. And because of the way the
class hierarchy works, any Instruction is already a Value,
representing its result.

In IR we write (for example):

    %val = add i32 %l, %r
    %val1 = mul i32 %val, 42

but the assignment is just a notational convenience to help us read.
What's really happening is that the first operand of the "mul" is
a
pointer to the "add" instruction itself, casted to a Value *.

That API takes a Value because you might want to replace all uses with
something else (most likely a Constant, but perhaps a Global). That
wouldn't work if you could only replace uses with another instruction.

Cheers.

Tim.