1 //===- llvm/Support/Error.h - Recoverable error handling --------*- C++ -*-===//
3 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
4 // See https://llvm.org/LICENSE.txt for license information.
5 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
7 //===----------------------------------------------------------------------===//
9 // This file defines an API used to report recoverable errors.
11 //===----------------------------------------------------------------------===//
13 #ifndef LLVM_SUPPORT_ERROR_H
14 #define LLVM_SUPPORT_ERROR_H
16 #include "llvm-c/Error.h"
17 #include "llvm/ADT/STLExtras.h"
18 #include "llvm/ADT/SmallVector.h"
19 #include "llvm/ADT/StringExtras.h"
20 #include "llvm/ADT/Twine.h"
21 #include "llvm/Config/abi-breaking.h"
22 #include "llvm/Support/AlignOf.h"
23 #include "llvm/Support/Compiler.h"
24 #include "llvm/Support/Debug.h"
25 #include "llvm/Support/ErrorHandling.h"
26 #include "llvm/Support/ErrorOr.h"
27 #include "llvm/Support/Format.h"
28 #include "llvm/Support/raw_ostream.h"
37 #include <system_error>
38 #include <type_traits>
46 /// Base class for error info classes. Do not extend this directly: Extend
47 /// the ErrorInfo template subclass instead.
50 virtual ~ErrorInfoBase() = default;
52 /// Print an error message to an output stream.
53 virtual void log(raw_ostream
&OS
) const = 0;
55 /// Return the error message as a string.
56 virtual std::string
message() const {
58 raw_string_ostream
OS(Msg
);
63 /// Convert this error to a std::error_code.
65 /// This is a temporary crutch to enable interaction with code still
66 /// using std::error_code. It will be removed in the future.
67 virtual std::error_code
convertToErrorCode() const = 0;
69 // Returns the class ID for this type.
70 static const void *classID() { return &ID
; }
72 // Returns the class ID for the dynamic type of this ErrorInfoBase instance.
73 virtual const void *dynamicClassID() const = 0;
75 // Check whether this instance is a subclass of the class identified by
77 virtual bool isA(const void *const ClassID
) const {
78 return ClassID
== classID();
81 // Check whether this instance is a subclass of ErrorInfoT.
82 template <typename ErrorInfoT
> bool isA() const {
83 return isA(ErrorInfoT::classID());
87 virtual void anchor();
92 /// Lightweight error class with error context and mandatory checking.
94 /// Instances of this class wrap a ErrorInfoBase pointer. Failure states
95 /// are represented by setting the pointer to a ErrorInfoBase subclass
96 /// instance containing information describing the failure. Success is
97 /// represented by a null pointer value.
99 /// Instances of Error also contains a 'Checked' flag, which must be set
100 /// before the destructor is called, otherwise the destructor will trigger a
101 /// runtime error. This enforces at runtime the requirement that all Error
102 /// instances be checked or returned to the caller.
104 /// There are two ways to set the checked flag, depending on what state the
105 /// Error instance is in. For Error instances indicating success, it
106 /// is sufficient to invoke the boolean conversion operator. E.g.:
109 /// Error foo(<...>);
111 /// if (auto E = foo(<...>))
112 /// return E; // <- Return E if it is in the error state.
113 /// // We have verified that E was in the success state. It can now be safely
117 /// A success value *can not* be dropped. For example, just calling 'foo(<...>)'
118 /// without testing the return value will raise a runtime error, even if foo
121 /// For Error instances representing failure, you must use either the
122 /// handleErrors or handleAllErrors function with a typed handler. E.g.:
125 /// class MyErrorInfo : public ErrorInfo<MyErrorInfo> {
126 /// // Custom error info.
129 /// Error foo(<...>) { return make_error<MyErrorInfo>(...); }
131 /// auto E = foo(<...>); // <- foo returns failure with MyErrorInfo.
134 /// [](const MyErrorInfo &M) {
135 /// // Deal with the error.
137 /// [](std::unique_ptr<OtherError> M) -> Error {
138 /// if (canHandle(*M)) {
140 /// return Error::success();
142 /// // Couldn't handle this error instance. Pass it up the stack.
143 /// return Error(std::move(M));
145 /// // Note - we must check or return NewE in case any of the handlers
146 /// // returned a new error.
149 /// The handleAllErrors function is identical to handleErrors, except
150 /// that it has a void return type, and requires all errors to be handled and
151 /// no new errors be returned. It prevents errors (assuming they can all be
152 /// handled) from having to be bubbled all the way to the top-level.
154 /// *All* Error instances must be checked before destruction, even if
155 /// they're moved-assigned or constructed from Success values that have already
156 /// been checked. This enforces checking through all levels of the call stack.
157 class LLVM_NODISCARD Error
{
158 // Both ErrorList and FileError need to be able to yank ErrorInfoBase
159 // pointers out of this class to add to the error list.
160 friend class ErrorList
;
161 friend class FileError
;
163 // handleErrors needs to be able to set the Checked flag.
164 template <typename
... HandlerTs
>
165 friend Error
handleErrors(Error E
, HandlerTs
&&... Handlers
);
167 // Expected<T> needs to be able to steal the payload when constructed from an
169 template <typename T
> friend class Expected
;
171 // wrap needs to be able to steal the payload.
172 friend LLVMErrorRef
wrap(Error
);
175 /// Create a success value. Prefer using 'Error::success()' for readability
182 /// Create a success value.
183 static ErrorSuccess
success();
185 // Errors are not copy-constructable.
186 Error(const Error
&Other
) = delete;
188 /// Move-construct an error value. The newly constructed error is considered
189 /// unchecked, even if the source error had been checked. The original error
190 /// becomes a checked Success value, regardless of its original state.
191 Error(Error
&&Other
) {
193 *this = std::move(Other
);
196 /// Create an error value. Prefer using the 'make_error' function, but
197 /// this constructor can be useful when "re-throwing" errors from handlers.
198 Error(std::unique_ptr
<ErrorInfoBase
> Payload
) {
199 setPtr(Payload
.release());
203 // Errors are not copy-assignable.
204 Error
&operator=(const Error
&Other
) = delete;
206 /// Move-assign an error value. The current error must represent success, you
207 /// you cannot overwrite an unhandled error. The current error is then
208 /// considered unchecked. The source error becomes a checked success value,
209 /// regardless of its original state.
210 Error
&operator=(Error
&&Other
) {
211 // Don't allow overwriting of unchecked values.
213 setPtr(Other
.getPtr());
215 // This Error is unchecked, even if the source error was checked.
218 // Null out Other's payload and set its checked bit.
219 Other
.setPtr(nullptr);
220 Other
.setChecked(true);
225 /// Destroy a Error. Fails with a call to abort() if the error is
232 /// Bool conversion. Returns true if this Error is in a failure state,
233 /// and false if it is in an accept state. If the error is in a Success state
234 /// it will be considered checked.
235 explicit operator bool() {
236 setChecked(getPtr() == nullptr);
237 return getPtr() != nullptr;
240 /// Check whether one error is a subclass of another.
241 template <typename ErrT
> bool isA() const {
242 return getPtr() && getPtr()->isA(ErrT::classID());
245 /// Returns the dynamic class id of this error, or null if this is a success
247 const void* dynamicClassID() const {
250 return getPtr()->dynamicClassID();
254 #if LLVM_ENABLE_ABI_BREAKING_CHECKS
255 // assertIsChecked() happens very frequently, but under normal circumstances
256 // is supposed to be a no-op. So we want it to be inlined, but having a bunch
257 // of debug prints can cause the function to be too large for inlining. So
258 // it's important that we define this function out of line so that it can't be
260 LLVM_ATTRIBUTE_NORETURN
261 void fatalUncheckedError() const;
264 void assertIsChecked() {
265 #if LLVM_ENABLE_ABI_BREAKING_CHECKS
266 if (LLVM_UNLIKELY(!getChecked() || getPtr()))
267 fatalUncheckedError();
271 ErrorInfoBase
*getPtr() const {
272 return reinterpret_cast<ErrorInfoBase
*>(
273 reinterpret_cast<uintptr_t>(Payload
) &
274 ~static_cast<uintptr_t>(0x1));
277 void setPtr(ErrorInfoBase
*EI
) {
278 #if LLVM_ENABLE_ABI_BREAKING_CHECKS
279 Payload
= reinterpret_cast<ErrorInfoBase
*>(
280 (reinterpret_cast<uintptr_t>(EI
) &
281 ~static_cast<uintptr_t>(0x1)) |
282 (reinterpret_cast<uintptr_t>(Payload
) & 0x1));
288 bool getChecked() const {
289 #if LLVM_ENABLE_ABI_BREAKING_CHECKS
290 return (reinterpret_cast<uintptr_t>(Payload
) & 0x1) == 0;
296 void setChecked(bool V
) {
297 Payload
= reinterpret_cast<ErrorInfoBase
*>(
298 (reinterpret_cast<uintptr_t>(Payload
) &
299 ~static_cast<uintptr_t>(0x1)) |
303 std::unique_ptr
<ErrorInfoBase
> takePayload() {
304 std::unique_ptr
<ErrorInfoBase
> Tmp(getPtr());
310 friend raw_ostream
&operator<<(raw_ostream
&OS
, const Error
&E
) {
311 if (auto P
= E
.getPtr())
318 ErrorInfoBase
*Payload
= nullptr;
321 /// Subclass of Error for the sole purpose of identifying the success path in
322 /// the type system. This allows to catch invalid conversion to Expected<T> at
324 class ErrorSuccess final
: public Error
{};
326 inline ErrorSuccess
Error::success() { return ErrorSuccess(); }
328 /// Make a Error instance representing failure using the given error info
330 template <typename ErrT
, typename
... ArgTs
> Error
make_error(ArgTs
&&... Args
) {
331 return Error(std::make_unique
<ErrT
>(std::forward
<ArgTs
>(Args
)...));
334 /// Base class for user error types. Users should declare their error types
337 /// class MyError : public ErrorInfo<MyError> {
341 /// This class provides an implementation of the ErrorInfoBase::kind
342 /// method, which is used by the Error RTTI system.
343 template <typename ThisErrT
, typename ParentErrT
= ErrorInfoBase
>
344 class ErrorInfo
: public ParentErrT
{
346 using ParentErrT::ParentErrT
; // inherit constructors
348 static const void *classID() { return &ThisErrT::ID
; }
350 const void *dynamicClassID() const override
{ return &ThisErrT::ID
; }
352 bool isA(const void *const ClassID
) const override
{
353 return ClassID
== classID() || ParentErrT::isA(ClassID
);
357 /// Special ErrorInfo subclass representing a list of ErrorInfos.
358 /// Instances of this class are constructed by joinError.
359 class ErrorList final
: public ErrorInfo
<ErrorList
> {
360 // handleErrors needs to be able to iterate the payload list of an
362 template <typename
... HandlerTs
>
363 friend Error
handleErrors(Error E
, HandlerTs
&&... Handlers
);
365 // joinErrors is implemented in terms of join.
366 friend Error
joinErrors(Error
, Error
);
369 void log(raw_ostream
&OS
) const override
{
370 OS
<< "Multiple errors:\n";
371 for (auto &ErrPayload
: Payloads
) {
377 std::error_code
convertToErrorCode() const override
;
379 // Used by ErrorInfo::classID.
383 ErrorList(std::unique_ptr
<ErrorInfoBase
> Payload1
,
384 std::unique_ptr
<ErrorInfoBase
> Payload2
) {
385 assert(!Payload1
->isA
<ErrorList
>() && !Payload2
->isA
<ErrorList
>() &&
386 "ErrorList constructor payloads should be singleton errors");
387 Payloads
.push_back(std::move(Payload1
));
388 Payloads
.push_back(std::move(Payload2
));
391 static Error
join(Error E1
, Error E2
) {
396 if (E1
.isA
<ErrorList
>()) {
397 auto &E1List
= static_cast<ErrorList
&>(*E1
.getPtr());
398 if (E2
.isA
<ErrorList
>()) {
399 auto E2Payload
= E2
.takePayload();
400 auto &E2List
= static_cast<ErrorList
&>(*E2Payload
);
401 for (auto &Payload
: E2List
.Payloads
)
402 E1List
.Payloads
.push_back(std::move(Payload
));
404 E1List
.Payloads
.push_back(E2
.takePayload());
408 if (E2
.isA
<ErrorList
>()) {
409 auto &E2List
= static_cast<ErrorList
&>(*E2
.getPtr());
410 E2List
.Payloads
.insert(E2List
.Payloads
.begin(), E1
.takePayload());
413 return Error(std::unique_ptr
<ErrorList
>(
414 new ErrorList(E1
.takePayload(), E2
.takePayload())));
417 std::vector
<std::unique_ptr
<ErrorInfoBase
>> Payloads
;
420 /// Concatenate errors. The resulting Error is unchecked, and contains the
421 /// ErrorInfo(s), if any, contained in E1, followed by the
422 /// ErrorInfo(s), if any, contained in E2.
423 inline Error
joinErrors(Error E1
, Error E2
) {
424 return ErrorList::join(std::move(E1
), std::move(E2
));
427 /// Tagged union holding either a T or a Error.
429 /// This class parallels ErrorOr, but replaces error_code with Error. Since
430 /// Error cannot be copied, this class replaces getError() with
431 /// takeError(). It also adds an bool errorIsA<ErrT>() method for testing the
432 /// error class type.
433 template <class T
> class LLVM_NODISCARD Expected
{
434 template <class T1
> friend class ExpectedAsOutParameter
;
435 template <class OtherT
> friend class Expected
;
437 static const bool isRef
= std::is_reference
<T
>::value
;
439 using wrap
= std::reference_wrapper
<typename
std::remove_reference
<T
>::type
>;
441 using error_type
= std::unique_ptr
<ErrorInfoBase
>;
444 using storage_type
= typename
std::conditional
<isRef
, wrap
, T
>::type
;
445 using value_type
= T
;
448 using reference
= typename
std::remove_reference
<T
>::type
&;
449 using const_reference
= const typename
std::remove_reference
<T
>::type
&;
450 using pointer
= typename
std::remove_reference
<T
>::type
*;
451 using const_pointer
= const typename
std::remove_reference
<T
>::type
*;
454 /// Create an Expected<T> error value from the given Error.
457 #if LLVM_ENABLE_ABI_BREAKING_CHECKS
458 // Expected is unchecked upon construction in Debug builds.
462 assert(Err
&& "Cannot create Expected<T> from Error success value.");
463 new (getErrorStorage()) error_type(Err
.takePayload());
466 /// Forbid to convert from Error::success() implicitly, this avoids having
467 /// Expected<T> foo() { return Error::success(); } which compiles otherwise
468 /// but triggers the assertion above.
469 Expected(ErrorSuccess
) = delete;
471 /// Create an Expected<T> success value from the given OtherT value, which
472 /// must be convertible to T.
473 template <typename OtherT
>
474 Expected(OtherT
&&Val
,
475 typename
std::enable_if
<std::is_convertible
<OtherT
, T
>::value
>::type
478 #if LLVM_ENABLE_ABI_BREAKING_CHECKS
479 // Expected is unchecked upon construction in Debug builds.
483 new (getStorage()) storage_type(std::forward
<OtherT
>(Val
));
486 /// Move construct an Expected<T> value.
487 Expected(Expected
&&Other
) { moveConstruct(std::move(Other
)); }
489 /// Move construct an Expected<T> value from an Expected<OtherT>, where OtherT
490 /// must be convertible to T.
491 template <class OtherT
>
492 Expected(Expected
<OtherT
> &&Other
,
493 typename
std::enable_if
<std::is_convertible
<OtherT
, T
>::value
>::type
495 moveConstruct(std::move(Other
));
498 /// Move construct an Expected<T> value from an Expected<OtherT>, where OtherT
499 /// isn't convertible to T.
500 template <class OtherT
>
502 Expected
<OtherT
> &&Other
,
503 typename
std::enable_if
<!std::is_convertible
<OtherT
, T
>::value
>::type
* =
505 moveConstruct(std::move(Other
));
508 /// Move-assign from another Expected<T>.
509 Expected
&operator=(Expected
&&Other
) {
510 moveAssign(std::move(Other
));
514 /// Destroy an Expected<T>.
518 getStorage()->~storage_type();
520 getErrorStorage()->~error_type();
523 /// Return false if there is an error.
524 explicit operator bool() {
525 #if LLVM_ENABLE_ABI_BREAKING_CHECKS
526 Unchecked
= HasError
;
531 /// Returns a reference to the stored T value.
534 return *getStorage();
537 /// Returns a const reference to the stored T value.
538 const_reference
get() const {
540 return const_cast<Expected
<T
> *>(this)->get();
543 /// Check that this Expected<T> is an error of type ErrT.
544 template <typename ErrT
> bool errorIsA() const {
545 return HasError
&& (*getErrorStorage())->template isA
<ErrT
>();
548 /// Take ownership of the stored error.
549 /// After calling this the Expected<T> is in an indeterminate state that can
550 /// only be safely destructed. No further calls (beside the destructor) should
551 /// be made on the Expected<T> value.
553 #if LLVM_ENABLE_ABI_BREAKING_CHECKS
556 return HasError
? Error(std::move(*getErrorStorage())) : Error::success();
559 /// Returns a pointer to the stored T value.
560 pointer
operator->() {
562 return toPointer(getStorage());
565 /// Returns a const pointer to the stored T value.
566 const_pointer
operator->() const {
568 return toPointer(getStorage());
571 /// Returns a reference to the stored T value.
572 reference
operator*() {
574 return *getStorage();
577 /// Returns a const reference to the stored T value.
578 const_reference
operator*() const {
580 return *getStorage();
585 static bool compareThisIfSameType(const T1
&a
, const T1
&b
) {
589 template <class T1
, class T2
>
590 static bool compareThisIfSameType(const T1
&a
, const T2
&b
) {
594 template <class OtherT
> void moveConstruct(Expected
<OtherT
> &&Other
) {
595 HasError
= Other
.HasError
;
596 #if LLVM_ENABLE_ABI_BREAKING_CHECKS
598 Other
.Unchecked
= false;
602 new (getStorage()) storage_type(std::move(*Other
.getStorage()));
604 new (getErrorStorage()) error_type(std::move(*Other
.getErrorStorage()));
607 template <class OtherT
> void moveAssign(Expected
<OtherT
> &&Other
) {
610 if (compareThisIfSameType(*this, Other
))
614 new (this) Expected(std::move(Other
));
617 pointer
toPointer(pointer Val
) { return Val
; }
619 const_pointer
toPointer(const_pointer Val
) const { return Val
; }
621 pointer
toPointer(wrap
*Val
) { return &Val
->get(); }
623 const_pointer
toPointer(const wrap
*Val
) const { return &Val
->get(); }
625 storage_type
*getStorage() {
626 assert(!HasError
&& "Cannot get value when an error exists!");
627 return reinterpret_cast<storage_type
*>(TStorage
.buffer
);
630 const storage_type
*getStorage() const {
631 assert(!HasError
&& "Cannot get value when an error exists!");
632 return reinterpret_cast<const storage_type
*>(TStorage
.buffer
);
635 error_type
*getErrorStorage() {
636 assert(HasError
&& "Cannot get error when a value exists!");
637 return reinterpret_cast<error_type
*>(ErrorStorage
.buffer
);
640 const error_type
*getErrorStorage() const {
641 assert(HasError
&& "Cannot get error when a value exists!");
642 return reinterpret_cast<const error_type
*>(ErrorStorage
.buffer
);
645 // Used by ExpectedAsOutParameter to reset the checked flag.
646 void setUnchecked() {
647 #if LLVM_ENABLE_ABI_BREAKING_CHECKS
652 #if LLVM_ENABLE_ABI_BREAKING_CHECKS
653 LLVM_ATTRIBUTE_NORETURN
654 LLVM_ATTRIBUTE_NOINLINE
655 void fatalUncheckedExpected() const {
656 dbgs() << "Expected<T> must be checked before access or destruction.\n";
658 dbgs() << "Unchecked Expected<T> contained error:\n";
659 (*getErrorStorage())->log(dbgs());
661 dbgs() << "Expected<T> value was in success state. (Note: Expected<T> "
662 "values in success mode must still be checked prior to being "
668 void assertIsChecked() {
669 #if LLVM_ENABLE_ABI_BREAKING_CHECKS
670 if (LLVM_UNLIKELY(Unchecked
))
671 fatalUncheckedExpected();
676 AlignedCharArrayUnion
<storage_type
> TStorage
;
677 AlignedCharArrayUnion
<error_type
> ErrorStorage
;
680 #if LLVM_ENABLE_ABI_BREAKING_CHECKS
685 /// Report a serious error, calling any installed error handler. See
687 LLVM_ATTRIBUTE_NORETURN
void report_fatal_error(Error Err
,
688 bool gen_crash_diag
= true);
690 /// Report a fatal error if Err is a failure value.
692 /// This function can be used to wrap calls to fallible functions ONLY when it
693 /// is known that the Error will always be a success value. E.g.
696 /// // foo only attempts the fallible operation if DoFallibleOperation is
697 /// // true. If DoFallibleOperation is false then foo always returns
698 /// // Error::success().
699 /// Error foo(bool DoFallibleOperation);
701 /// cantFail(foo(false));
703 inline void cantFail(Error Err
, const char *Msg
= nullptr) {
706 Msg
= "Failure value returned from cantFail wrapped call";
707 llvm_unreachable(Msg
);
711 /// Report a fatal error if ValOrErr is a failure value, otherwise unwraps and
712 /// returns the contained value.
714 /// This function can be used to wrap calls to fallible functions ONLY when it
715 /// is known that the Error will always be a success value. E.g.
718 /// // foo only attempts the fallible operation if DoFallibleOperation is
719 /// // true. If DoFallibleOperation is false then foo always returns an int.
720 /// Expected<int> foo(bool DoFallibleOperation);
722 /// int X = cantFail(foo(false));
724 template <typename T
>
725 T
cantFail(Expected
<T
> ValOrErr
, const char *Msg
= nullptr) {
727 return std::move(*ValOrErr
);
730 Msg
= "Failure value returned from cantFail wrapped call";
731 llvm_unreachable(Msg
);
735 /// Report a fatal error if ValOrErr is a failure value, otherwise unwraps and
736 /// returns the contained reference.
738 /// This function can be used to wrap calls to fallible functions ONLY when it
739 /// is known that the Error will always be a success value. E.g.
742 /// // foo only attempts the fallible operation if DoFallibleOperation is
743 /// // true. If DoFallibleOperation is false then foo always returns a Bar&.
744 /// Expected<Bar&> foo(bool DoFallibleOperation);
746 /// Bar &X = cantFail(foo(false));
748 template <typename T
>
749 T
& cantFail(Expected
<T
&> ValOrErr
, const char *Msg
= nullptr) {
754 Msg
= "Failure value returned from cantFail wrapped call";
755 llvm_unreachable(Msg
);
759 /// Helper for testing applicability of, and applying, handlers for
761 template <typename HandlerT
>
762 class ErrorHandlerTraits
763 : public ErrorHandlerTraits
<decltype(
764 &std::remove_reference
<HandlerT
>::type::operator())> {};
766 // Specialization functions of the form 'Error (const ErrT&)'.
767 template <typename ErrT
> class ErrorHandlerTraits
<Error (&)(ErrT
&)> {
769 static bool appliesTo(const ErrorInfoBase
&E
) {
770 return E
.template isA
<ErrT
>();
773 template <typename HandlerT
>
774 static Error
apply(HandlerT
&&H
, std::unique_ptr
<ErrorInfoBase
> E
) {
775 assert(appliesTo(*E
) && "Applying incorrect handler");
776 return H(static_cast<ErrT
&>(*E
));
780 // Specialization functions of the form 'void (const ErrT&)'.
781 template <typename ErrT
> class ErrorHandlerTraits
<void (&)(ErrT
&)> {
783 static bool appliesTo(const ErrorInfoBase
&E
) {
784 return E
.template isA
<ErrT
>();
787 template <typename HandlerT
>
788 static Error
apply(HandlerT
&&H
, std::unique_ptr
<ErrorInfoBase
> E
) {
789 assert(appliesTo(*E
) && "Applying incorrect handler");
790 H(static_cast<ErrT
&>(*E
));
791 return Error::success();
795 /// Specialization for functions of the form 'Error (std::unique_ptr<ErrT>)'.
796 template <typename ErrT
>
797 class ErrorHandlerTraits
<Error (&)(std::unique_ptr
<ErrT
>)> {
799 static bool appliesTo(const ErrorInfoBase
&E
) {
800 return E
.template isA
<ErrT
>();
803 template <typename HandlerT
>
804 static Error
apply(HandlerT
&&H
, std::unique_ptr
<ErrorInfoBase
> E
) {
805 assert(appliesTo(*E
) && "Applying incorrect handler");
806 std::unique_ptr
<ErrT
> SubE(static_cast<ErrT
*>(E
.release()));
807 return H(std::move(SubE
));
811 /// Specialization for functions of the form 'void (std::unique_ptr<ErrT>)'.
812 template <typename ErrT
>
813 class ErrorHandlerTraits
<void (&)(std::unique_ptr
<ErrT
>)> {
815 static bool appliesTo(const ErrorInfoBase
&E
) {
816 return E
.template isA
<ErrT
>();
819 template <typename HandlerT
>
820 static Error
apply(HandlerT
&&H
, std::unique_ptr
<ErrorInfoBase
> E
) {
821 assert(appliesTo(*E
) && "Applying incorrect handler");
822 std::unique_ptr
<ErrT
> SubE(static_cast<ErrT
*>(E
.release()));
824 return Error::success();
828 // Specialization for member functions of the form 'RetT (const ErrT&)'.
829 template <typename C
, typename RetT
, typename ErrT
>
830 class ErrorHandlerTraits
<RetT (C::*)(ErrT
&)>
831 : public ErrorHandlerTraits
<RetT (&)(ErrT
&)> {};
833 // Specialization for member functions of the form 'RetT (const ErrT&) const'.
834 template <typename C
, typename RetT
, typename ErrT
>
835 class ErrorHandlerTraits
<RetT (C::*)(ErrT
&) const>
836 : public ErrorHandlerTraits
<RetT (&)(ErrT
&)> {};
838 // Specialization for member functions of the form 'RetT (const ErrT&)'.
839 template <typename C
, typename RetT
, typename ErrT
>
840 class ErrorHandlerTraits
<RetT (C::*)(const ErrT
&)>
841 : public ErrorHandlerTraits
<RetT (&)(ErrT
&)> {};
843 // Specialization for member functions of the form 'RetT (const ErrT&) const'.
844 template <typename C
, typename RetT
, typename ErrT
>
845 class ErrorHandlerTraits
<RetT (C::*)(const ErrT
&) const>
846 : public ErrorHandlerTraits
<RetT (&)(ErrT
&)> {};
848 /// Specialization for member functions of the form
849 /// 'RetT (std::unique_ptr<ErrT>)'.
850 template <typename C
, typename RetT
, typename ErrT
>
851 class ErrorHandlerTraits
<RetT (C::*)(std::unique_ptr
<ErrT
>)>
852 : public ErrorHandlerTraits
<RetT (&)(std::unique_ptr
<ErrT
>)> {};
854 /// Specialization for member functions of the form
855 /// 'RetT (std::unique_ptr<ErrT>) const'.
856 template <typename C
, typename RetT
, typename ErrT
>
857 class ErrorHandlerTraits
<RetT (C::*)(std::unique_ptr
<ErrT
>) const>
858 : public ErrorHandlerTraits
<RetT (&)(std::unique_ptr
<ErrT
>)> {};
860 inline Error
handleErrorImpl(std::unique_ptr
<ErrorInfoBase
> Payload
) {
861 return Error(std::move(Payload
));
864 template <typename HandlerT
, typename
... HandlerTs
>
865 Error
handleErrorImpl(std::unique_ptr
<ErrorInfoBase
> Payload
,
866 HandlerT
&&Handler
, HandlerTs
&&... Handlers
) {
867 if (ErrorHandlerTraits
<HandlerT
>::appliesTo(*Payload
))
868 return ErrorHandlerTraits
<HandlerT
>::apply(std::forward
<HandlerT
>(Handler
),
870 return handleErrorImpl(std::move(Payload
),
871 std::forward
<HandlerTs
>(Handlers
)...);
874 /// Pass the ErrorInfo(s) contained in E to their respective handlers. Any
875 /// unhandled errors (or Errors returned by handlers) are re-concatenated and
877 /// Because this function returns an error, its result must also be checked
878 /// or returned. If you intend to handle all errors use handleAllErrors
879 /// (which returns void, and will abort() on unhandled errors) instead.
880 template <typename
... HandlerTs
>
881 Error
handleErrors(Error E
, HandlerTs
&&... Hs
) {
883 return Error::success();
885 std::unique_ptr
<ErrorInfoBase
> Payload
= E
.takePayload();
887 if (Payload
->isA
<ErrorList
>()) {
888 ErrorList
&List
= static_cast<ErrorList
&>(*Payload
);
890 for (auto &P
: List
.Payloads
)
893 handleErrorImpl(std::move(P
), std::forward
<HandlerTs
>(Hs
)...));
897 return handleErrorImpl(std::move(Payload
), std::forward
<HandlerTs
>(Hs
)...);
900 /// Behaves the same as handleErrors, except that by contract all errors
901 /// *must* be handled by the given handlers (i.e. there must be no remaining
902 /// errors after running the handlers, or llvm_unreachable is called).
903 template <typename
... HandlerTs
>
904 void handleAllErrors(Error E
, HandlerTs
&&... Handlers
) {
905 cantFail(handleErrors(std::move(E
), std::forward
<HandlerTs
>(Handlers
)...));
908 /// Check that E is a non-error, then drop it.
909 /// If E is an error, llvm_unreachable will be called.
910 inline void handleAllErrors(Error E
) {
911 cantFail(std::move(E
));
914 /// Handle any errors (if present) in an Expected<T>, then try a recovery path.
916 /// If the incoming value is a success value it is returned unmodified. If it
917 /// is a failure value then it the contained error is passed to handleErrors.
918 /// If handleErrors is able to handle the error then the RecoveryPath functor
919 /// is called to supply the final result. If handleErrors is not able to
920 /// handle all errors then the unhandled errors are returned.
922 /// This utility enables the follow pattern:
925 /// enum FooStrategy { Aggressive, Conservative };
926 /// Expected<Foo> foo(FooStrategy S);
928 /// auto ResultOrErr =
931 /// []() { return foo(Conservative); },
932 /// [](AggressiveStrategyError&) {
933 /// // Implicitly conusme this - we'll recover by using a conservative
938 template <typename T
, typename RecoveryFtor
, typename
... HandlerTs
>
939 Expected
<T
> handleExpected(Expected
<T
> ValOrErr
, RecoveryFtor
&&RecoveryPath
,
940 HandlerTs
&&... Handlers
) {
944 if (auto Err
= handleErrors(ValOrErr
.takeError(),
945 std::forward
<HandlerTs
>(Handlers
)...))
946 return std::move(Err
);
948 return RecoveryPath();
951 /// Log all errors (if any) in E to OS. If there are any errors, ErrorBanner
952 /// will be printed before the first one is logged. A newline will be printed
953 /// after each error.
955 /// This function is compatible with the helpers from Support/WithColor.h. You
956 /// can pass any of them as the OS. Please consider using them instead of
957 /// including 'error: ' in the ErrorBanner.
959 /// This is useful in the base level of your program to allow clean termination
960 /// (allowing clean deallocation of resources, etc.), while reporting error
961 /// information to the user.
962 void logAllUnhandledErrors(Error E
, raw_ostream
&OS
, Twine ErrorBanner
= {});
964 /// Write all error messages (if any) in E to a string. The newline character
965 /// is used to separate error messages.
966 inline std::string
toString(Error E
) {
967 SmallVector
<std::string
, 2> Errors
;
968 handleAllErrors(std::move(E
), [&Errors
](const ErrorInfoBase
&EI
) {
969 Errors
.push_back(EI
.message());
971 return join(Errors
.begin(), Errors
.end(), "\n");
974 /// Consume a Error without doing anything. This method should be used
975 /// only where an error can be considered a reasonable and expected return
978 /// Uses of this method are potentially indicative of design problems: If it's
979 /// legitimate to do nothing while processing an "error", the error-producer
980 /// might be more clearly refactored to return an Optional<T>.
981 inline void consumeError(Error Err
) {
982 handleAllErrors(std::move(Err
), [](const ErrorInfoBase
&) {});
985 /// Convert an Expected to an Optional without doing anything. This method
986 /// should be used only where an error can be considered a reasonable and
987 /// expected return value.
989 /// Uses of this method are potentially indicative of problems: perhaps the
990 /// error should be propagated further, or the error-producer should just
991 /// return an Optional in the first place.
992 template <typename T
> Optional
<T
> expectedToOptional(Expected
<T
> &&E
) {
994 return std::move(*E
);
995 consumeError(E
.takeError());
999 /// Helper for converting an Error to a bool.
1001 /// This method returns true if Err is in an error state, or false if it is
1002 /// in a success state. Puts Err in a checked state in both cases (unlike
1003 /// Error::operator bool(), which only does this for success states).
1004 inline bool errorToBool(Error Err
) {
1005 bool IsError
= static_cast<bool>(Err
);
1007 consumeError(std::move(Err
));
1011 /// Helper for Errors used as out-parameters.
1013 /// This helper is for use with the Error-as-out-parameter idiom, where an error
1014 /// is passed to a function or method by reference, rather than being returned.
1015 /// In such cases it is helpful to set the checked bit on entry to the function
1016 /// so that the error can be written to (unchecked Errors abort on assignment)
1017 /// and clear the checked bit on exit so that clients cannot accidentally forget
1018 /// to check the result. This helper performs these actions automatically using
1022 /// Result foo(Error &Err) {
1023 /// ErrorAsOutParameter ErrAsOutParam(&Err); // 'Checked' flag set
1024 /// // <body of foo>
1025 /// // <- 'Checked' flag auto-cleared when ErrAsOutParam is destructed.
1029 /// ErrorAsOutParameter takes an Error* rather than Error& so that it can be
1030 /// used with optional Errors (Error pointers that are allowed to be null). If
1031 /// ErrorAsOutParameter took an Error reference, an instance would have to be
1032 /// created inside every condition that verified that Error was non-null. By
1033 /// taking an Error pointer we can just create one instance at the top of the
1035 class ErrorAsOutParameter
{
1037 ErrorAsOutParameter(Error
*Err
) : Err(Err
) {
1038 // Raise the checked bit if Err is success.
1043 ~ErrorAsOutParameter() {
1044 // Clear the checked bit.
1046 *Err
= Error::success();
1053 /// Helper for Expected<T>s used as out-parameters.
1055 /// See ErrorAsOutParameter.
1056 template <typename T
>
1057 class ExpectedAsOutParameter
{
1059 ExpectedAsOutParameter(Expected
<T
> *ValOrErr
)
1060 : ValOrErr(ValOrErr
) {
1065 ~ExpectedAsOutParameter() {
1067 ValOrErr
->setUnchecked();
1071 Expected
<T
> *ValOrErr
;
1074 /// This class wraps a std::error_code in a Error.
1076 /// This is useful if you're writing an interface that returns a Error
1077 /// (or Expected) and you want to call code that still returns
1078 /// std::error_codes.
1079 class ECError
: public ErrorInfo
<ECError
> {
1080 friend Error
errorCodeToError(std::error_code
);
1082 virtual void anchor() override
;
1085 void setErrorCode(std::error_code EC
) { this->EC
= EC
; }
1086 std::error_code
convertToErrorCode() const override
{ return EC
; }
1087 void log(raw_ostream
&OS
) const override
{ OS
<< EC
.message(); }
1089 // Used by ErrorInfo::classID.
1093 ECError() = default;
1094 ECError(std::error_code EC
) : EC(EC
) {}
1099 /// The value returned by this function can be returned from convertToErrorCode
1100 /// for Error values where no sensible translation to std::error_code exists.
1101 /// It should only be used in this situation, and should never be used where a
1102 /// sensible conversion to std::error_code is available, as attempts to convert
1103 /// to/from this error will result in a fatal error. (i.e. it is a programmatic
1104 ///error to try to convert such a value).
1105 std::error_code
inconvertibleErrorCode();
1107 /// Helper for converting an std::error_code to a Error.
1108 Error
errorCodeToError(std::error_code EC
);
1110 /// Helper for converting an ECError to a std::error_code.
1112 /// This method requires that Err be Error() or an ECError, otherwise it
1113 /// will trigger a call to abort().
1114 std::error_code
errorToErrorCode(Error Err
);
1116 /// Convert an ErrorOr<T> to an Expected<T>.
1117 template <typename T
> Expected
<T
> errorOrToExpected(ErrorOr
<T
> &&EO
) {
1118 if (auto EC
= EO
.getError())
1119 return errorCodeToError(EC
);
1120 return std::move(*EO
);
1123 /// Convert an Expected<T> to an ErrorOr<T>.
1124 template <typename T
> ErrorOr
<T
> expectedToErrorOr(Expected
<T
> &&E
) {
1125 if (auto Err
= E
.takeError())
1126 return errorToErrorCode(std::move(Err
));
1127 return std::move(*E
);
1130 /// This class wraps a string in an Error.
1132 /// StringError is useful in cases where the client is not expected to be able
1133 /// to consume the specific error message programmatically (for example, if the
1134 /// error message is to be presented to the user).
1136 /// StringError can also be used when additional information is to be printed
1137 /// along with a error_code message. Depending on the constructor called, this
1138 /// class can either display:
1139 /// 1. the error_code message (ECError behavior)
1141 /// 3. the error_code message and a string
1143 /// These behaviors are useful when subtyping is required; for example, when a
1144 /// specific library needs an explicit error type. In the example below,
1145 /// PDBError is derived from StringError:
1148 /// Expected<int> foo() {
1149 /// return llvm::make_error<PDBError>(pdb_error_code::dia_failed_loading,
1150 /// "Additional information");
1154 class StringError
: public ErrorInfo
<StringError
> {
1158 // Prints EC + S and converts to EC
1159 StringError(std::error_code EC
, const Twine
&S
= Twine());
1161 // Prints S and converts to EC
1162 StringError(const Twine
&S
, std::error_code EC
);
1164 void log(raw_ostream
&OS
) const override
;
1165 std::error_code
convertToErrorCode() const override
;
1167 const std::string
&getMessage() const { return Msg
; }
1172 const bool PrintMsgOnly
= false;
1175 /// Create formatted StringError object.
1176 template <typename
... Ts
>
1177 inline Error
createStringError(std::error_code EC
, char const *Fmt
,
1178 const Ts
&... Vals
) {
1180 raw_string_ostream
Stream(Buffer
);
1181 Stream
<< format(Fmt
, Vals
...);
1182 return make_error
<StringError
>(Stream
.str(), EC
);
1185 Error
createStringError(std::error_code EC
, char const *Msg
);
1187 inline Error
createStringError(std::error_code EC
, const Twine
&S
) {
1188 return createStringError(EC
, S
.str().c_str());
1191 template <typename
... Ts
>
1192 inline Error
createStringError(std::errc EC
, char const *Fmt
,
1193 const Ts
&... Vals
) {
1194 return createStringError(std::make_error_code(EC
), Fmt
, Vals
...);
1197 /// This class wraps a filename and another Error.
1199 /// In some cases, an error needs to live along a 'source' name, in order to
1200 /// show more detailed information to the user.
1201 class FileError final
: public ErrorInfo
<FileError
> {
1203 friend Error
createFileError(const Twine
&, Error
);
1204 friend Error
createFileError(const Twine
&, size_t, Error
);
1207 void log(raw_ostream
&OS
) const override
{
1208 assert(Err
&& !FileName
.empty() && "Trying to log after takeError().");
1209 OS
<< "'" << FileName
<< "': ";
1210 if (Line
.hasValue())
1211 OS
<< "line " << Line
.getValue() << ": ";
1215 Error
takeError() { return Error(std::move(Err
)); }
1217 std::error_code
convertToErrorCode() const override
;
1219 // Used by ErrorInfo::classID.
1223 FileError(const Twine
&F
, Optional
<size_t> LineNum
,
1224 std::unique_ptr
<ErrorInfoBase
> E
) {
1225 assert(E
&& "Cannot create FileError from Error success value.");
1226 assert(!F
.isTriviallyEmpty() &&
1227 "The file name provided to FileError must not be empty.");
1230 Line
= std::move(LineNum
);
1233 static Error
build(const Twine
&F
, Optional
<size_t> Line
, Error E
) {
1235 std::unique_ptr
<FileError
>(new FileError(F
, Line
, E
.takePayload())));
1238 std::string FileName
;
1239 Optional
<size_t> Line
;
1240 std::unique_ptr
<ErrorInfoBase
> Err
;
1243 /// Concatenate a source file path and/or name with an Error. The resulting
1244 /// Error is unchecked.
1245 inline Error
createFileError(const Twine
&F
, Error E
) {
1246 return FileError::build(F
, Optional
<size_t>(), std::move(E
));
1249 /// Concatenate a source file path and/or name with line number and an Error.
1250 /// The resulting Error is unchecked.
1251 inline Error
createFileError(const Twine
&F
, size_t Line
, Error E
) {
1252 return FileError::build(F
, Optional
<size_t>(Line
), std::move(E
));
1255 /// Concatenate a source file path and/or name with a std::error_code
1256 /// to form an Error object.
1257 inline Error
createFileError(const Twine
&F
, std::error_code EC
) {
1258 return createFileError(F
, errorCodeToError(EC
));
1261 /// Concatenate a source file path and/or name with line number and
1262 /// std::error_code to form an Error object.
1263 inline Error
createFileError(const Twine
&F
, size_t Line
, std::error_code EC
) {
1264 return createFileError(F
, Line
, errorCodeToError(EC
));
1267 Error
createFileError(const Twine
&F
, ErrorSuccess
) = delete;
1269 /// Helper for check-and-exit error handling.
1271 /// For tool use only. NOT FOR USE IN LIBRARY CODE.
1275 /// Create an error on exit helper.
1276 ExitOnError(std::string Banner
= "", int DefaultErrorExitCode
= 1)
1277 : Banner(std::move(Banner
)),
1278 GetExitCode([=](const Error
&) { return DefaultErrorExitCode
; }) {}
1280 /// Set the banner string for any errors caught by operator().
1281 void setBanner(std::string Banner
) { this->Banner
= std::move(Banner
); }
1283 /// Set the exit-code mapper function.
1284 void setExitCodeMapper(std::function
<int(const Error
&)> GetExitCode
) {
1285 this->GetExitCode
= std::move(GetExitCode
);
1288 /// Check Err. If it's in a failure state log the error(s) and exit.
1289 void operator()(Error Err
) const { checkError(std::move(Err
)); }
1291 /// Check E. If it's in a success state then return the contained value. If
1292 /// it's in a failure state log the error(s) and exit.
1293 template <typename T
> T
operator()(Expected
<T
> &&E
) const {
1294 checkError(E
.takeError());
1295 return std::move(*E
);
1298 /// Check E. If it's in a success state then return the contained reference. If
1299 /// it's in a failure state log the error(s) and exit.
1300 template <typename T
> T
& operator()(Expected
<T
&> &&E
) const {
1301 checkError(E
.takeError());
1306 void checkError(Error Err
) const {
1308 int ExitCode
= GetExitCode(Err
);
1309 logAllUnhandledErrors(std::move(Err
), errs(), Banner
);
1315 std::function
<int(const Error
&)> GetExitCode
;
1318 /// Conversion from Error to LLVMErrorRef for C error bindings.
1319 inline LLVMErrorRef
wrap(Error Err
) {
1320 return reinterpret_cast<LLVMErrorRef
>(Err
.takePayload().release());
1323 /// Conversion from LLVMErrorRef to Error for C error bindings.
1324 inline Error
unwrap(LLVMErrorRef ErrRef
) {
1325 return Error(std::unique_ptr
<ErrorInfoBase
>(
1326 reinterpret_cast<ErrorInfoBase
*>(ErrRef
)));
1329 } // end namespace llvm
1331 #endif // LLVM_SUPPORT_ERROR_H