Lightweight error class with error context and mandatory checking.
Declared in <llvm/Support/Error.h>
class [[nodiscard]] Error;
Instances of this class wrap a ErrorInfoBase pointer. Failure states are represented by setting the pointer to a ErrorInfoBase subclass instance containing information describing the failure. Success is represented by a null pointer value.
Instances of Error also contains a 'Checked' flag, which must be set before the destructor is called, otherwise the destructor will trigger a runtime error. This enforces at runtime the requirement that all Error instances be checked or returned to the caller.
There are two ways to set the checked flag, depending on what state the Error instance is in. For Error instances indicating success, it is sufficient to invoke the boolean conversion operator. E.g.:
Error foo(<...>);
if (auto E = foo(<...>))
return E; // <- Return E if it is in the error state.
// We have verified that E was in the success state. It can now be safely
// destroyed.
A success value can not be dropped. For example, just calling 'foo(<...>)' without testing the return value will raise a runtime error, even if foo returns success.
For Error instances representing failure, you must use either the handleErrors or handleAllErrors function with a typed handler. E.g.:
class MyErrorInfo : public ErrorInfo<MyErrorInfo> {
// Custom error info.
};
Error foo(<...>) { return make_error<MyErrorInfo>(...); }
auto E = foo(<...>); // <- foo returns failure with MyErrorInfo.
auto NewE =
handleErrors(std::move(E),
[](const MyErrorInfo &M) {
// Deal with the error.
},
[](std::unique_ptr<OtherError> M) -> Error {
if (canHandle(*M)) {
// handle error.
return Error::success();
}
// Couldn't handle this error instance. Pass it up the stack.
return Error(std::move(M));
});
// Note - The error passed to handleErrors will be marked as checked. If
// there is no matched handler, a new error with the same payload is
// created and returned.
// The handlers take the error checked by handleErrors as an argument,
// which can be used to retrieve more information. If a new error is
// created by a handler, it will be passed back to the caller of
// handleErrors and needs to be checked or return up to the stack.
// Otherwise, the passed-in error is considered consumed.
The handleAllErrors function is identical to handleErrors, except that it has a void return type, and requires all errors to be handled and no new errors be returned. It prevents errors (assuming they can all be handled) from having to be bubbled all the way to the top-level.
All Error instances must be checked before destruction, even if they're moved-assigned or constructed from Success values that have already been checked. This enforces checking through all levels of the call stack.
| Name | Description |
|---|---|
Error [constructor] | Constructors |
~Error [destructor] | Destroy a Error. Fails with a call to abort() if the error is unchecked. |
operator= | Assignment operators |
dynamicClassID | Returns the dynamic class id of this error, or null if this is a success value. |
isA | Check whether one error is a subclass of another. |
operator bool | Return true if this Error holds a failure value. |
| Name | Description |
|---|---|
success | Create a success value. |
| Name | Description |
|---|---|
Error [constructor] | Create a success value. Prefer using 'Error::success()' for readability |
| Name | Description |
|---|---|
llvm::operator<< | Write a textual representation of error E to stream OS. |
llvm::wrap | Conversion from Error to LLVMErrorRef for C error bindings. |
llvm::Expected | Tagged union holding either a T or a Error. |
llvm::visitErrors | Visit all the ErrorInfo(s) contained in E by passing them to the respective handler, without consuming the error. |
llvm::handleErrors | Pass ErrorInfo payloads in E to matching handlers among Handlers. |
llvm::ErrorList | Special ErrorInfo subclass representing a list of ErrorInfos. Instances of this class are constructed by joinError. |
| Name | Description |
|---|---|
EmitImportsFiles | Emit into OutputFilename the files module ModulePath will import from. |
cantFail | Report a fatal error if Err is a failure value. |
collectGlobalObjectNameStrings | Serialize global-object name strings into a profile-ready blob. |
collectPGOFuncNameStrings | Serialize referenced PGO function-name variables into Result. |
collectVTableStrings | Serialize vtable name strings into a profile-ready blob. |
consumeError | Consume a Error without doing anything. This method should be used only where an error can be considered a reasonable and expected return value. |
createCtxProfFromYAML | Convert a YAML contextual profile in Profile into bitstream form on Out. |
createFileError | Create a StringError with the specified error code and prepend the file path to it. |
createFileError | Concatenate a source file path and/or name with line number and std::error_code to form an Error object. |
createFileError | Deleted overload: a successful Error cannot be wrapped as a FileError. |
createFileError | Concatenate a source file path and/or name with a std::error_code to form an Error object. |
createFileError | Create a StringError with the specified error code and prepend the file path to it. |
createFileError | Concatenate a source file path and/or name with an Error. The resulting Error is unchecked. |
createFileError | Concatenate a source file path and/or name with line number and an Error. The resulting Error is unchecked. |
createStringError | Create a StringError from error code EC and message Msg. |
createStringError | Create a StringError with an inconvertible error code and printf-style Fmt. |
createStringError | Create a StringError from std::errc EC and printf-style Fmt. |
createStringError | Create a StringError from error code EC and Twine message S. |
createStringError | Create a StringError with an inconvertible error code. |
createStringError | Create a StringError from error code EC and message S. |
createStringError | Create formatted StringError object. |
createStringErrorV | Create a StringError from error code EC and formatv-style Fmt. |
createStringErrorV | Create a StringError with an inconvertible error code and formatv-style Fmt. |
decodeBase64 | Decode a Base64 string into raw bytes. |
errorCodeToError | Helper for converting an std::error_code to a Error. |
errorToBool | Helper for converting an Error to a bool. |
errorToErrorCode | Helper for converting an ECError to a std::error_code. |
fmt_consume | Wrap an Error so formatv takes ownership and consumes it. |
handleAllErrors | Like handleErrors, but requires every error to be handled. |
handleAllErrors | Check that E is a non-error, then drop it. If E is an error, llvm_unreachable will be called. |
handleErrorImpl | Return an Error wrapping unhandled Payload. |
handleErrorImpl | Dispatch Payload to the first matching handler among Handler and Handlers. |
joinErrors | Concatenate errors from E1 followed by those from E2. |
logAllUnhandledErrors | Log all errors in E to OS, optionally prefixed by ErrorBanner. |
make_error | Make a Error instance representing failure using the given error info type. |
parallelForEachError | Apply Fn to each element of R in parallel and join any returned Errors. |
readAndDecodeStrings | Decode concatenated PGO name strings and invoke a callback for each name. |
readModuleSummaryIndex | Parse the specified bitcode buffer and merge the index into CombinedIndex. |
reportFatalInternalError | Report a fatal error that indicates a bug in LLVM. See ErrorHandling.h for details. |
reportFatalUsageError | Report a fatal error that does not indicate a bug in LLVM. See ErrorHandling.h for details. |
report_fatal_error | Report a fatal error from an Error value. |
setupLLVMOptimizationRemarks | Set up optimization remarks that output directly to a raw_ostream. |
splitModuleTransitiveFromEntryPoints | Splits a module into parts by transitive reachability from entry points. |
timeTraceProfilerWrite | Write profiling data to a file. |
toString | Write all error messages (if any) in E to a string. The newline character is used to separate error messages. |
toStringWithoutConsuming | Like toString(), but does not consume the error. This can be used to print a warning while retaining the original error object. |
unwrap | Conversion from LLVMErrorRef to Error for C error bindings. |
warnToStderr | Log Err to stderr as a warning. |
write | Merge split DWARF inputs into Out, optionally writing the package. |
writeArchive | Write an archive to the file named ArcName. |
writeArchiveToStream | Write an archive directly to an output stream. |
writeMemProf | Write MemProf profile data to OS in the requested indexed format version. |
writeToOutput | Create an output stream for OutputFileName and pass it to Write. |
DWARFYAML::emitDebugAbbrev | Emit the .debug_abbrev section described by DI to OS. |
DWARFYAML::emitDebugAddr | Emit the .debug_addr section described by DI to OS. |
DWARFYAML::emitDebugAranges | Emit the .debug_aranges section described by DI to OS. |
DWARFYAML::emitDebugGNUPubnames | Emit the .debug_gnu_pubnames section described by DI to OS. |
DWARFYAML::emitDebugGNUPubtypes | Emit the .debug_gnu_pubtypes section described by DI to OS. |
DWARFYAML::emitDebugInfo | Emit the .debug_info section described by DI to OS. |
DWARFYAML::emitDebugLine | Emit the .debug_line section described by DI to OS. |
DWARFYAML::emitDebugLoclists | Emit the .debug_loclists section described by DI to OS. |
DWARFYAML::emitDebugNames | Emit the .debug_names section described by DI to OS. |
DWARFYAML::emitDebugPubnames | Emit the .debug_pubnames section described by DI to OS. |
DWARFYAML::emitDebugPubtypes | Emit the .debug_pubtypes section described by DI to OS. |
DWARFYAML::emitDebugRanges | Emit the .debug_ranges section described by DI to OS. |
DWARFYAML::emitDebugRnglists | Emit the .debug_rnglists section described by DI to OS. |
DWARFYAML::emitDebugStr | Emit the .debug_str section described by DI to OS. |
DWARFYAML::emitDebugStrOffsets | Emit the .debug_str_offsets section described by DI to OS. |
DWARFYAML::getDWARFEmitterByName | Return the emitter for the DWARF section named SecName. |
RISCV::parseTuneFeatureString | Parse the tune feature string with the respective processor. If ProcName is empty, directives are not filtered by processor. |
cgdata::warn | Report a codegen-data warning derived from error E. |
codeview::consume | Decode a numeric leaf value from a string buffer into Num. |
codeview::consume | Consume a vector-tail serialization helper from Reader. |
codeview::consume | Decode a numeric leaf value from the type stream into Num. |
codeview::consume | Decode a null-terminated string. |
codeview::consume | Decode an unsigned fixed-length 32-bit integer. |
codeview::consume | Decode a signed fixed-length 32-bit integer. |
codeview::consume | Decode an unsigned 32-bit integer from a string buffer. |
codeview::consume | No-op consume that always succeeds; base case for variadic consume. |
codeview::consume | Consume an arrayref-tail serialization helper from Reader. |
codeview::consume | Consume an array serialization helper from Reader. |
codeview::consume | Consume a numeric serialization helper from Reader. |
codeview::consume | Consume a conditional serialization helper from Reader. |
codeview::consume | Decode an object whose layout matches the underlying byte sequence. |
codeview::consume | Consume a null-terminated string-array helper from Reader. |
codeview::consume | Consume multiple fields from Reader in order. |
codeview::consume_numeric | Decode a numeric leaf value that is known to be a particular type. |
codeview::forEachCodeViewRecord | Invoke F for each contiguous CodeView record in StreamBuffer. |
codeview::mergeIdRecords | Merge one set of id records into another. |
codeview::mergeIdRecords | Merge one set of id records into a global id table. |
codeview::mergeTypeAndIdRecords | Merge a unified set of type and id records into global tables, splitting them into separate output streams. |
codeview::mergeTypeAndIdRecords | Merge a unified set of type and id records, splitting them into separate output streams. |
codeview::mergeTypeRecords | Merge one set of type records into another. This method assumes that all records are type records, and there are no Id records present. |
codeview::mergeTypeRecords | Merge one set of type records into a global type table. |
codeview::visitDebugSubsection | Dispatch a single debug subsection record to the appropriate visitor method. |
codeview::visitDebugSubsections | Visit each debug subsection in FragmentRange using the given string table. |
codeview::visitDebugSubsections | Visit each debug subsection in FragmentRange. |
codeview::visitDebugSubsections | Visit each debug subsection in FragmentRange using the given string table and checksums. |
codeview::visitMemberRecord | Visit a single member record. |
codeview::visitMemberRecord | Visit a single member record from its leaf kind and raw bytes. |
codeview::visitMemberRecordStream | Visit every member record in a field-list byte stream. |
codeview::visitTypeRecord | Visit a single type record at a known type index. |
codeview::visitTypeRecord | Visit a single type record without a type index. |
codeview::visitTypeStream | Visit every type record in Types in order. |
codeview::visitTypeStream | Visit every type record in the range Types. |
codeview::visitTypeStream | Visit every type record in the collection Types. |
compression::decompress | Decompress Input using debug compression type T into Output. |
compression::decompress | Decompress Input using the debug-info compression format T into Output, which is resized to UncompressedSize bytes. |
compression::decompress | Decompress Input using compression format F into Output, which is resized to UncompressedSize bytes. |
dwarf_linker::finiteLoop | Call Iteration until it returns false, or fail if the limit is hit. |
ifs::filterIFSSyms | Filters symbols from an IFS stub by undefined status and exclude globs. |
ifs::overrideIFSTarget | Override the target platform inforation in the text stub. |
ifs::validateIFSTarget | Validate the target platform inforation in the text stub. |
ifs::writeBinaryStub | Attempt to write a binary ELF stub. |
ifs::writeIFSToOutputStream | Attempts to write an IFS interface file to a raw_ostream. |
irsymtab::build | Fills in Symtab and StrtabBuilder with a valid symbol and string table for Mods. |
jitlink::makeAlignmentError | Create an alignment error for a fixup at the given location. |
jitlink::makeTargetOutOfRangeError | Create an out of range error for the given edge in the given block. |
jitlink::markAllSymbolsLive | Marks all symbols in a graph live. This can be used as a default, conservative mark-live implementation. |
lto::backend | Runs a regular LTO backend. The regular LTO backend can also act as the regular LTO phase of ThinLTO, which may need to access the combined index. |
lto::finalizeOptimizationRemarks | Finalizes and flushes an optimization remarks output file. |
lto::thinBackend | Runs a ThinLTO backend. |
msf::validateSuperBlock | Validates that a superblock describes a well-formed MSF file. |
objcopy::executeObjcopyOnArchive | Applies the transformations described by Config to each member in archive Ar. Writes a result in a file specified by Config.OutputFilename. |
objcopy::executeObjcopyOnBinary | Applies the transformations described by Config to In and writes the result into Out. |
object::createError | Create a parse_failed StringError with message Err. |
object::decodeCrel | Decode a CREL relocation blob, invoking handlers for the header and entries. |
object::extractCodeObject | Extract code object memory from the given Buffer at Offset and of Size, and copy into OutputFileName. |
object::extractCodeObject | Extract code object memory from the given Source object file at Offset and of Size, and copy into OutputFileName. |
object::extractOffloadBinaries | Extracts embedded device offloading code from a memory Buffer to a list of Binaries. |
object::extractOffloadBundleByURI | Extracts an Offload Bundle Entry given by URI. |
object::extractOffloadBundleFatBinary | Extracts fat binary in binary clang-offload-bundler format from object Obj and return it in Bundles. |
object::isNotObjectErrorInvalidFileType | Consume Err when it is invalid_file_type; otherwise return it. |
object::writeImportLibrary | Writes a COFF import library containing entries described by the Exports array. |
object::writeUniversalBinary | Write a Mach-O universal binary containing Slices to OutputFileName. |
object::writeUniversalBinaryToStream | Write a Mach-O universal binary containing Slices to Out. |
offloading::containerizeImage | Containerizes an image within an OffloadBinary image. |
offloading::wrapCudaBinary | Wraps the input fatbinary image into the module M as global symbols and registers the images with the CUDA runtime. |
offloading::wrapHIPBinary | Wraps the input bundled image into the module M as global symbols and registers the images with the HIP runtime. |
offloading::wrapOpenMPBinaries | Wraps the input device images into the module M as global symbols and registers the images with the OpenMP Offloading runtime libomptarget. |
offloading::wrapSYCLBinaries | Wraps OffloadBinaries in the given Buffers into the module M as global symbols and registers the images with the SYCL Runtime. |
orc::addFunctionPointerRelocationsToCurrentSymbol | Introduce relocations to Sym in its own definition if there are any pointers formed via PC-relative address that do not already have a relocation. |
orc::checkMachORelocatableObject | Check that a buffer contains a MachO object compatible with a triple. |
orc::decodeHangupPayload | Decode a Hangup payload produced by encodeHangupPayload. |
orc::deregisterEHFrameSection | Unregister frames in the given eh-frame section with libunwind. |
orc::enableDebuggerSupport | Enable debugger support for the given LLJIT instance. |
orc::encodeHangupPayload | Encode an Error as the payload of a Hangup message. |
orc::lookupAndApply | Blocking version of lookupAndApply above. |
orc::lookupAndApply | lookupAndApply with a static lookup in the given JITDylib. Blocking version. |
orc::preserveDebugSections | Preserve DWARF debug sections in G so they are not pruned by JITLink. |
orc::registerEHFrameSection | Register frames in the given eh-frame section with libunwind. |
orc::setUpInProcessLCTMReentryViaEPCIU | Set up in-process lazy call-through re-entry via the given EPCIU. |
orc::setUpOrcPlatformManually | Configure the LLJIT instance to use orc runtime support. This overload assumes that the client has manually configured a Platform object. |
pdb::iterateModuleSubsections | Visit each debug subsection of type SubsectionT across filtered modules. |
pdb::iterateOneModule | Print a module header for SG and invoke Callback for that module. |
pdb::iterateSymbolGroups | Visit each filtered symbol group in Input, invoking Callback. |
pdb::loadDataForEXE | Create a PDB session by loading debug data for an executable. |
pdb::loadDataForPDB | Create a PDB session by loading debug data from a PDB file. |
pdb::readSparseBitVector | Read a SparseBitVector from a PDB binary stream. |
pdb::writeSparseBitVector | Write a SparseBitVector to a PDB binary stream. |
vfs::convertToOutputError | Return Error::success() or use OutputPath to create an OutputError, depending on EC. |
vfs::convertToTempFileOutputError | Return Error::success() or use TempPath and OutputPath to create a TempFileOutputError, depending on EC. |
compression::zlib::decompress | Decompress zlib-compressed Input into a caller-provided buffer. |
compression::zlib::decompress | Decompress zlib-compressed Input into Output. |
compression::zstd::decompress | Decompress zstd-compressed Input into a caller-provided buffer. |
compression::zstd::decompress | Decompress zstd-compressed Input into Output. |
coverage::accessors::getFuncNameViaRef | Return the PGO name of the function. Used for formats in which the name is a hash. |
jitlink::aarch32::applyFixup | Apply fixup expression for edge to block content. |
jitlink::aarch32::applyFixupArm | Helper function to apply the fixup for Arm-class relocations. |
jitlink::aarch32::applyFixupData | Helper function to apply the fixup for Data-class relocations. |
jitlink::aarch32::applyFixupThumb | Helper function to apply the fixup for Thumb-class relocations. |
jitlink::aarch64::applyFixup | Apply fixup expression for edge to block content. |
jitlink::aarch64::createEmptyPointerSigningFunction | Create an empty pointer signing function for the link graph. |
jitlink::aarch64::lowerPointer64AuthEdgesToSigningFunction | Lower Pointer64Authenticated edges into a pointer signing function. |
jitlink::hexagon::applyFixup | Apply fixup expression for edge to block content. |
jitlink::ppc64::applyFixup | Apply fixup expression for edge to block content. |
jitlink::ppc64::relocateHalf16 | Write a 16-bit half16 relocation field for edge kind K. |
jitlink::systemz::applyFixup | Apply fixup expression for edge to block content. |
jitlink::systemz::optimizeGOTAndStubAccesses | Optimize in-range GOT and stub relocations in the link graph. |
jitlink::x86::applyFixup | Apply fixup expression for edge to block content. |
jitlink::x86::optimizeGOTAndStubAccesses | Optimize GOT and stub relocations when the edge target is in range. |
jitlink::x86_64::applyFixup | Apply fixup expression for edge to block content. |
jitlink::x86_64::optimizeGOTAndStubAccesses | Optimize GOT and stub accesses when the ultimate target is in range. |
objcopy::coff::executeObjcopyOnBinary | Apply the transformations described by Config and COFFConfig to In and writes the result into Out. |
objcopy::dxbc::executeObjcopyOnBinary | Apply the transformations described by Config and DXContainerConfig to In and writes the result into Out. |
objcopy::elf::executeObjcopyOnBinary | Apply the transformations described by Config and ELFConfig to In and writes the result into Out. |
objcopy::elf::executeObjcopyOnIHex | Apply the transformations described by Config and ELFConfig to In, which must represent an IHex file, and writes the result into Out. |
objcopy::elf::executeObjcopyOnRawBinary | Apply the transformations described by Config and ELFConfig to In, which is treated as a raw binary input, and writes the result into Out. |
objcopy::macho::executeObjcopyOnBinary | Apply the transformations described by Config and MachOConfig to In and writes the result into Out. |
objcopy::macho::executeObjcopyOnMachOUniversalBinary | Apply the transformations described by Config to In and writes the result into Out. |
objcopy::wasm::executeObjcopyOnBinary | Apply the transformations described by Config and WasmConfig to In and writes the result into Out. |
objcopy::xcoff::executeObjcopyOnBinary | Apply the transformations described by Config and XCOFFConfig to In and writes the result into Out. |
offloading::amdgpu::getAMDGPUMetaDataFromImage | Reads AMDGPU specific metadata from the ELF file and propagates the KernelInfoMap. |
offloading::intel::containerizeOpenMPSPIRVImage | Containerizes an OpenMP SPIR-V image into an OffloadBinary image. |
orc::shared::runDeallocActions | Run deallocation actions. Dealloc actions will be run in reverse order (from last element of DAs to first). |
sys::fs::readNativeFileToEOF | Reads from FileHandle until EOF, appending to Buffer in chunks of size ChunkSize. |
| Name | Description |
|---|---|
ErrorSuccess | Subclass of Error that represents success in the type system. |
MSVCPError | A default-constructible Error suitable for use with MSVC's std::future. |
The return value should not be discarded.