what does "materialize" mean in llvm GlobalValue.h

Question

I'm a beginner of LLVM. When I go through the LLVM's API, I have a naive question:

what does the "materialize" mean in llvm GlobalValue.h

in the doxygen: http://llvm.org/doxygen/classllvm_1_1GlobalValue.html#ac1b5643f40dd3c7b92a548027eb13de0

it says: Error GlobalValue::materialize ()

Make sure this GlobalValue is fully read.

But, what does it really mean? Does it mean that this function will make the GlobalValue be fully read? And what does "fully read" mean?

Thanks in advance!

Answer 1

When you load LLVM IR from bitcode or textual IR, you may choose to use a "lazy" loader (see include/llvm/IRReader/IRReader.h or include/llvm/Bitcode/BitcodeReader.h in the LLVM 4.0 sources) that loads only the "declaration" of globals/functions. Whenever you need the "definition", you will have to materialize what you need.

This is an optimization that avoids parsing and loading unnecessary code from bitcode or IR files.

You will still get an llvm::Module, but the globals (which include functions) are not "materialized", i.e. you can look at the type, but for a function you cannot access the actual function body until you called materialize. Before you pass a function or a module to LLVM API functions that need the code you have to call materialize() or for a module materializeAll().

If you do not need this behaviour you can just as well use non-lazy versions of the loaders and do not have to worry about this. In particular if you create the module yourself via the API rather than loading it from somewhere there is no need to worry about materialization.