llvm::Error Class Reference

Lightweight error class with error context and mandatory checking. More...

#include "llvm/Support/Error.h"

Inheritance diagram for llvm::Error:

Public Member Functions
	Error (const Error &Other)=delete
	Error (Error &&Other)
	Move-construct an error value. More...
	Error (std::unique_ptr< ErrorInfoBase > Payload)
	Create an error value. More...
Error &	operator= (const Error &Other)=delete
Error &	operator= (Error &&Other)
	Move-assign an error value. More...
	~Error ()
	Destroy a Error. More...
	operator bool ()
	Bool conversion. More...
template<typename ErrT >
bool	isA () const
	Check whether one error is a subclass of another. More...
const void *	dynamicClassID () const
	Returns the dynamic class id of this error, or null if this is a success value. More...

Static Public Member Functions
static ErrorSuccess	success ()
	Create a success value. More...

Protected Member Functions
	Error ()
	Create a success value. Prefer using 'Error::success()' for readability. More...

Friends
class	ErrorList
class	FileError
template<typename T >
class	Expected
template<typename... HandlerTs>
Error	handleErrors (Error E, HandlerTs &&... Handlers)
	Pass the ErrorInfo(s) contained in E to their respective handlers. More...
LLVMErrorRef	wrap (Error)
	Conversion from Error to LLVMErrorRef for C error bindings. More...
raw_ostream &	operator<< (raw_ostream &OS, const Error &E)

Detailed Description

Lightweight error class with error context and mandatory checking.

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(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 - we must check or return NewE in case any of the handlers
// returned a new error.

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.

Definition at line 158 of file Error.h.

Constructor & Destructor Documentation

Error() [1/4]

llvm::Error::Error ( )

inlineprotected

Create a success value. Prefer using 'Error::success()' for readability.

Definition at line 177 of file Error.h.

References llvm::Error, Other, and llvm::success.

Error() [2/4]

llvm::Error::Error ( const Error &  Other )

delete

Error() [3/4]

llvm::Error::Error ( Error &&  Other )

inline

Move-construct an error value.

The newly constructed error is considered unchecked, even if the source error had been checked. The original error becomes a checked Success value, regardless of its original state.

Definition at line 192 of file Error.h.

Error() [4/4]

llvm::Error::Error ( std::unique_ptr< ErrorInfoBase >  Payload )

inline

Create an error value.

Prefer using the 'make_error' function, but this constructor can be useful when "re-throwing" errors from handlers.

Definition at line 199 of file Error.h.

~Error()

llvm::Error::~Error ( )

inline

Destroy a Error.

Fails with a call to abort() if the error is unchecked.

Definition at line 228 of file Error.h.

References getPtr().

Member Function Documentation

dynamicClassID()

const void* llvm::Error::dynamicClassID ( ) const

inline

Returns the dynamic class id of this error, or null if this is a success value.

Definition at line 248 of file Error.h.

References getPtr(), LLVM_ATTRIBUTE_NORETURN, and LLVM_UNLIKELY.

isA()

template<typename ErrT >

bool llvm::Error::isA ( ) const

inline

Check whether one error is a subclass of another.

Definition at line 242 of file Error.h.

References getPtr().

operator bool()

llvm::Error::operator bool ( )

inlineexplicit

Bool conversion.

Returns true if this Error is in a failure state, and false if it is in an accept state. If the error is in a Success state it will be considered checked.

Definition at line 236 of file Error.h.

References getPtr().

operator=() [1/2]

Error& llvm::Error::operator= ( const Error &  Other )

delete

Referenced by llvm::MSVCPError::operator=().

operator=() [2/2]

Error& llvm::Error::operator= ( Error &&  Other )

inline

Move-assign an error value.

The current error must represent success, you you cannot overwrite an unhandled error. The current error is then considered unchecked. The source error becomes a checked success value, regardless of its original state.

Definition at line 211 of file Error.h.

success()

ErrorSuccess llvm::Error::success ( )

inlinestatic

Create a success value.

Definition at line 327 of file Error.h.

Referenced by llvm::xray::Profile::addBlock(), llvm::pdb::DbiStreamBuilder::addDbgStream(), llvm::InstrProfSymtab::addFuncName(), llvm::pdb::PDBFileBuilder::addInjectedSource(), llvm::orc::LazyEmittingLayer< CompileLayerT >::addModule(), llvm::pdb::DbiStreamBuilder::addModuleSourceFile(), llvm::pdb::PDBFileBuilder::addNamedStream(), llvm::orc::LegacyRTDyldObjectLinkingLayer::addObject(), llvm::lto::Config::addSaveTemps(), llvm::pdb::TpiStreamBuilder::addTypeRecord(), llvm::allocValueProfData(), llvm::ErrorHandlerTraits< void(&)(ErrT &)>::apply(), llvm::ErrorHandlerTraits< void(&)(std::unique_ptr< ErrT >)>::apply(), llvm::orc::LLJIT::applyDataLayout(), llvm::codeview::CodeViewRecordIO::beginRecord(), llvm::codeview::LazyRandomTypeCollection::capacity(), checkDyldCommand(), checkDylibCommand(), checkEncryptCommand(), checkHashHdrVersion(), checkLinkerOptCommand(), llvm::BinaryStream::checkOffsetForRead(), llvm::BinaryStreamRefBase< WritableBinaryStreamRef, WritableBinaryStream >::checkOffsetForRead(), llvm::WritableBinaryStream::checkOffsetForWrite(), checkOverlappingElement(), checkRpathCommand(), checkSubCommand(), llvm::object::MachOObjectFile::checkSymbolTable(), checkThreadCommand(), checkVersCommand(), llvm::collectPGOFuncNameStrings(), llvm::pdb::SymbolStream::commit(), llvm::codeview::DebugSymbolsSubsection::commit(), llvm::pdb::NamedStreamMap::commit(), llvm::codeview::DebugFrameDataSubsection::commit(), llvm::pdb::GSIStreamBuilder::commit(), llvm::pdb::PDBStringTableBuilder::commit(), llvm::pdb::InfoStreamBuilder::commit(), llvm::codeview::DebugCrossModuleExportsSubsection::commit(), llvm::pdb::GSIHashStreamBuilder::commit(), llvm::pdb::TpiStreamBuilder::commit(), llvm::pdb::ModuleDebugStreamRef::commit(), llvm::codeview::DebugSubsectionRecordBuilder::commit(), llvm::pdb::TpiStream::commit(), llvm::pdb::DbiModuleDescriptorBuilder::commit(), llvm::pdb::DbiStreamBuilder::commit(), llvm::codeview::DebugCrossModuleImportsSubsection::commit(), llvm::codeview::DebugChecksumsSubsection::commit(), llvm::codeview::DebugInlineeLinesSubsection::commit(), llvm::MutableBinaryByteStream::commit(), llvm::codeview::DebugLinesSubsection::commit(), llvm::pdb::HashTable< llvm::pdb::SrcHeaderBlockEntry, llvm::pdb::StringTableHashTraits >::commit(), llvm::AppendingBinaryByteStream::commit(), llvm::zlib::compress(), llvm::RuntimeDyldImpl::computeTotalAllocSize(), llvm::xray::LogBuilderConsumer::consume(), llvm::codeview::consume(), llvm::xray::PipelineConsumer::consume(), llvm::codeview::consume_numeric(), llvm::orc::rpc::SequenceTraits< ChannelT >::consumeSeparator(), llvm::coverage::BinaryCoverageReader::create(), llvm::InstrProfSymtab::create(), llvm::pdb::DIASession::createFromExe(), llvm::pdb::DIASession::createFromPdb(), llvm::pdb::NativeSession::createFromPdb(), llvm::lto::createWriteIndexesThinBackend(), decodeLLVMAttributesForBitcode(), llvm::DWARFContext::defaultErrorHandler(), llvm::codeview::serialize_conditional_impl< T, U >::deserialize(), llvm::codeview::serialize_vector_tail_impl< T >::deserialize(), llvm::orc::rpc::SequenceSerialization< ChannelT >::deserialize(), llvm::codeview::SymbolDeserializer::deserializeAs(), llvm::codeview::TypeDeserializer::deserializeAs(), llvm::orc::JITDylib::dump(), llvm::RuntimeDyldImpl::emitCommonSymbols(), llvm::orc::OrcAArch64::emitIndirectStubsBlock(), llvm::orc::OrcX86_64_Base::emitIndirectStubsBlock(), llvm::orc::OrcI386::emitIndirectStubsBlock(), llvm::orc::OrcMips32_Base::emitIndirectStubsBlock(), llvm::orc::OrcMips64::emitIndirectStubsBlock(), llvm::orc::rpc::SequenceTraits< ChannelT >::emitSeparator(), llvm::orc::rpc::RawByteChannel::endReceiveMessage(), llvm::codeview::CodeViewRecordIO::endRecord(), llvm::orc::rpc::RawByteChannel::endSendMessage(), llvm::coverage::CounterMappingContext::evaluate(), llvm::DWARFDebugRangeList::extract(), llvm::AppleAcceleratorTable::extract(), llvm::DWARFDebugNames::Header::extract(), llvm::DWARFDebugNames::NameIndex::extract(), llvm::DWARFDebugNames::extract(), llvm::RuntimeDyldImpl::finalizeAsync(), llvm::RuntimeDyldELF::finalizeLoad(), llvm::RuntimeDyldCOFFX86_64::finalizeLoad(), llvm::RuntimeDyldImpl::finalizeLoad(), llvm::pdb::GSIStreamBuilder::finalizeMsfLayout(), llvm::pdb::InfoStreamBuilder::finalizeMsfLayout(), llvm::pdb::TpiStreamBuilder::finalizeMsfLayout(), llvm::pdb::DbiModuleDescriptorBuilder::finalizeMsfLayout(), llvm::pdb::DbiStreamBuilder::finalizeMsfLayout(), finalizeOptimizationRemarks(), llvm::RuntimeDyldMachOX86_64::finalizeSection(), llvm::RuntimeDyldMachOI386::finalizeSection(), llvm::RuntimeDyldMachOARM::finalizeSection(), llvm::RuntimeDyldMachOAArch64::finalizeSection(), finishVisitation(), llvm::xray::TraceExpander::flush(), llvm::xray::BlockIndexer::flush(), llvm::codeview::forEachCodeViewRecord(), llvm::CodeViewYAML::detail::UnknownSymbolRecord::fromCodeViewSymbol(), getAttrFromCode(), llvm::pdb::DbiStream::getECName(), llvm::pdb::DbiStream::getECSubstreamData(), llvm::InstrProfReader::getError(), llvm::coverage::CovMapFunctionRecordV1< IntPtrT >::getFuncName(), llvm::coverage::CovMapFunctionRecord::getFuncName(), llvm::msf::MappedBlockStream::getLength(), llvm::windows_manifest::WindowsManifestMerger::getMergedManifest(), llvm::getOffset(), llvm::InstrProfReaderIndex< HashTableImpl >::getRecords(), llvm::pdb::PDBStringTable::getSignature(), llvm::pdb::DbiStreamBuilder::getSourceFileNameIndex(), llvm::pdb::PDBStringTable::getStringTable(), getSymbolKindName(), llvm::lto::getThinLTOOutputFile(), llvm::handleErrors(), llvm::orc::AsynchronousSymbolQuery::handleFullyReady(), llvm::orc::rpc::detail::ResponseHandlerImpl< ChannelT, Error, HandlerT >::handleResponse(), llvm::codeview::DebugFrameDataSubsectionRef::initialize(), llvm::pdb::DbiModuleDescriptor::initialize(), llvm::codeview::DebugStringTableSubsectionRef::initialize(), llvm::codeview::DebugSubsectionRecord::initialize(), llvm::pdb::PDBFileBuilder::initialize(), llvm::codeview::DebugChecksumsSubsectionRef::initialize(), llvm::pdb::DbiModuleList::initialize(), llvm::codeview::DebugInlineeLinesSubsectionRef::initialize(), llvm::codeview::DebugLinesSubsectionRef::initialize(), jumpToValueSymbolTable(), llvm::sys::fs::TempFile::keep(), llvm::orc::ExecutionSession::legacyLookup(), llvm::pdb::HashTable< llvm::pdb::SrcHeaderBlockEntry, llvm::pdb::StringTableHashTraits >::load(), loadBinaryFormat(), LoadDIA(), loadObj(), llvm::RuntimeDyldELF::loadObject(), llvm::DWARFContext::loadRegisterInfo(), loadSectionContribs(), loadTestingFormat(), loadYAML(), llvm::lto::localCache(), llvm::orc::ExecutionSession::lookup(), llvm::codeview::CodeViewRecordIO::mapByteVectorTail(), llvm::codeview::CodeViewRecordIO::mapEncodedInteger(), llvm::codeview::CodeViewRecordIO::mapEnum(), llvm::codeview::CodeViewRecordIO::mapGuid(), llvm::codeview::CodeViewRecordIO::mapInteger(), mapLocalVariableAddrRange(), mapNameAndUniqueName(), llvm::codeview::CodeViewRecordIO::mapObject(), llvm::codeview::CodeViewRecordIO::mapStringZ(), llvm::codeview::CodeViewRecordIO::mapStringZVectorZ(), llvm::codeview::CodeViewRecordIO::mapVectorN(), llvm::codeview::CodeViewRecordIO::mapVectorTail(), llvm::Module::materialize(), llvm::Module::materializeAll(), llvm::Module::materializeMetadata(), llvm::orc::rpc::APICalls< Funcs >::negotiate(), llvm::VarStreamArrayExtractor< CrossModuleImportItem >::operator()(), llvm::VarStreamArrayExtractor< pdb::DbiModuleDescriptor >::operator()(), llvm::codeview::LineColumnExtractor::operator()(), llvm::VarStreamArrayExtractor< codeview::DebugSubsectionRecord >::operator()(), llvm::VarStreamArrayExtractor< codeview::CVRecord< Kind > >::operator()(), llvm::orc::ReexportsGenerator::operator()(), llvm::orc::rpc::detail::ReadArgs< ArgTs... >::operator()(), llvm::BinaryStreamWriter::padToAlignment(), llvm::dwarf::CFIProgram::parse(), llvm::DWARFDebugLine::Prologue::parse(), llvm::object::WindowsResourceParser::parse(), llvm::DWARFDebugLine::LineTable::parse(), llvm::PassBuilder::parseAAPipeline(), llvm::pdb::PDBFile::parseFileHeaders(), llvm::MetadataLoader::MetadataLoaderImpl::parseMetadata(), llvm::MetadataLoader::MetadataLoaderImpl::parseMetadataAttachment(), llvm::MetadataLoader::MetadataLoaderImpl::parseMetadataKinds(), llvm::PassBuilder::parsePassPipeline(), llvm::pdb::PDBFile::parseStreamData(), llvm::RuntimeDyldMachO::populateIndirectSymbolPointersSection(), llvm::InstrProfReaderRemapper::populateRemappings(), llvm::InstrProfReaderItaniumRemapper< HashTableImpl >::populateRemappings(), llvm::pdb::GSIHashTable::read(), llvm::SymbolRemappingReader::read(), llvm::BinaryStreamReader::readArray(), llvm::BinaryByteStream::readBytes(), llvm::BinaryItemStream< T, Traits >::readBytes(), llvm::msf::MappedBlockStream::readBytes(), llvm::BinaryStreamReader::readBytes(), llvm::AppendingBinaryByteStream::readBytes(), llvm::BinaryStreamReader::readCString(), llvm::BinaryStreamReader::readEnum(), llvm::BinaryStreamReader::readFixedString(), readGSIHashBuckets(), readGSIHashHeader(), readGSIHashRecords(), readInitExpr(), llvm::BinaryStreamReader::readInteger(), llvm::BinaryByteStream::readLongestContiguousChunk(), llvm::BinaryItemStream< T, Traits >::readLongestContiguousChunk(), llvm::BinaryStreamReader::readLongestContiguousChunk(), llvm::msf::MappedBlockStream::readLongestContiguousChunk(), llvm::AppendingBinaryByteStream::readLongestContiguousChunk(), llvm::BinaryStreamRef::readLongestContiguousChunk(), llvm::BinaryStreamReader::readObject(), llvm::readPGOFuncNameStrings(), readSection(), llvm::pdb::readSparseBitVector(), llvm::BinaryStreamReader::readStreamRef(), llvm::object::readStringOrId(), llvm::coverage::RawCoverageReader::readULEB128(), readWideAPInt(), llvm::BinaryStreamReader::readWideString(), llvm::pdb::SymbolStream::reload(), llvm::pdb::PublicsStream::reload(), llvm::pdb::InfoStream::reload(), llvm::pdb::PDBStringTable::reload(), llvm::pdb::ModuleDebugStreamRef::reload(), llvm::pdb::TpiStream::reload(), llvm::pdb::DbiStream::reload(), llvm::pdb::GlobalsStream::reload(), llvm::orc::JITDylib::remove(), llvm::orc::LegacyRTDyldObjectLinkingLayer::removeObject(), llvm::RuntimeDyldImpl::resolveExternalSymbols(), llvm::orc::CtorDtorRunner::run(), llvm::orc::rpc::detail::HandlerTraits< RetT(ArgTs...)>::run(), llvm::orc::rpc::SequenceSerialization< ChannelT >::serialize(), llvm::msf::MSFBuilder::setBlockMapAddr(), llvm::msf::MSFBuilder::setDirectoryBlocksHint(), setImmutableRefs(), llvm::InstrProfWriter::setIsIRLevelProfile(), llvm::msf::MSFBuilder::setStreamSize(), llvm::pdb::PDBStringTableBuilder::setStrings(), llvm::BinaryStreamReader::skip(), llvm::codeview::CodeViewRecordIO::skipPadding(), llvm::SoftInstrProfErrors::takeError(), llvm::Expected< T >::takeError(), llvm::CodeViewYAML::toCodeViewSubsectionList(), llvm::zlib::uncompress(), llvm::orc::LocalIndirectStubsManager< TargetT >::updatePointer(), llvm::orc::remote::OrcRemoteTargetClient::RemoteIndirectStubsManager::updatePointer(), llvm::msf::validateSuperBlock(), llvm::xray::BlockVerifier::verify(), llvm::xray::RecordPrinter::visit(), llvm::xray::FDRTraceWriter::visit(), llvm::xray::TraceExpander::visit(), llvm::xray::BlockIndexer::visit(), llvm::xray::RecordInitializer::visit(), llvm::codeview::detail::visitDebugSubsections(), visitKnownMember(), visitKnownRecord(), llvm::codeview::TypeRecordMapping::visitMemberBegin(), llvm::codeview::TypeVisitorCallbacks::visitMemberBegin(), llvm::codeview::TypeDumpVisitor::visitMemberBegin(), llvm::codeview::TypeVisitorCallbackPipeline::visitMemberBegin(), llvm::codeview::TypeRecordMapping::visitMemberEnd(), llvm::codeview::TypeVisitorCallbacks::visitMemberEnd(), llvm::codeview::TypeDumpVisitor::visitMemberEnd(), llvm::codeview::TypeVisitorCallbackPipeline::visitMemberEnd(), llvm::codeview::FieldListDeserializer::visitMemberEnd(), visitMemberRecord(), llvm::codeview::SymbolRecordMapping::visitSymbolBegin(), llvm::codeview::SymbolVisitorCallbackPipeline::visitSymbolBegin(), llvm::codeview::SymbolVisitorCallbacks::visitSymbolBegin(), llvm::codeview::SymbolSerializer::visitSymbolBegin(), llvm::codeview::SymbolRecordMapping::visitSymbolEnd(), llvm::codeview::SymbolVisitorCallbacks::visitSymbolEnd(), llvm::codeview::SymbolVisitorCallbackPipeline::visitSymbolEnd(), llvm::codeview::SymbolSerializer::visitSymbolEnd(), llvm::codeview::CVSymbolVisitor::visitSymbolStream(), llvm::codeview::TypeRecordMapping::visitTypeBegin(), llvm::codeview::TypeVisitorCallbacks::visitTypeBegin(), llvm::codeview::TypeVisitorCallbackPipeline::visitTypeBegin(), llvm::codeview::TypeDumpVisitor::visitTypeBegin(), llvm::codeview::TypeRecordMapping::visitTypeEnd(), llvm::codeview::TypeVisitorCallbacks::visitTypeEnd(), llvm::codeview::TypeDumpVisitor::visitTypeEnd(), llvm::codeview::TypeVisitorCallbackPipeline::visitTypeEnd(), llvm::codeview::DebugSubsectionVisitor::visitUnknown(), llvm::codeview::TypeVisitorCallbackPipeline::visitUnknownMember(), llvm::codeview::TypeVisitorCallbacks::visitUnknownMember(), llvm::codeview::TypeDumpVisitor::visitUnknownMember(), llvm::codeview::SymbolVisitorCallbackPipeline::visitUnknownSymbol(), llvm::codeview::SymbolVisitorCallbacks::visitUnknownSymbol(), llvm::codeview::TypeVisitorCallbacks::visitUnknownType(), llvm::codeview::TypeVisitorCallbackPipeline::visitUnknownType(), llvm::codeview::TypeDumpVisitor::visitUnknownType(), llvm::BinaryStreamWriter::writeArray(), llvm::BinaryStreamWriter::writeBytes(), llvm::MutableBinaryByteStream::writeBytes(), llvm::msf::WritableMappedBlockStream::writeBytes(), llvm::AppendingBinaryByteStream::writeBytes(), llvm::BinaryStreamWriter::writeCString(), writeRecords(), llvm::pdb::writeSparseBitVector(), llvm::BinaryStreamWriter::writeStreamRef(), llvm::elfabi::writeTBEToOutputStream(), llvm::InstrProfWriter::writeText(), and llvm::object::writeWindowsResourceCOFF().

Friends And Related Function Documentation

ErrorList

friend class ErrorList

friend

Definition at line 161 of file Error.h.

Expected

template<typename T >

friend class Expected

friend

Definition at line 170 of file Error.h.

FileError

friend class FileError

friend

Definition at line 162 of file Error.h.

handleErrors

template<typename... HandlerTs>

Error handleErrors ( Error  E, HandlerTs &&...  Handlers  )

friend

Pass the ErrorInfo(s) contained in E to their respective handlers.

Any unhandled errors (or Errors returned by handlers) are re-concatenated and returned. Because this function returns an error, its result must also be checked or returned. If you intend to handle all errors use handleAllErrors (which returns void, and will abort() on unhandled errors) instead.

Definition at line 882 of file Error.h.

operator<<

raw_ostream& operator<< ( raw_ostream &  OS, const Error &  E  )

friend

Definition at line 311 of file Error.h.

wrap

LLVMErrorRef wrap ( Error  Err )

friend

Conversion from Error to LLVMErrorRef for C error bindings.

Definition at line 1271 of file Error.h.

---

The documentation for this class was generated from the following file:

• include/llvm/Support/Error.h