#include <objectbase.h>
ErrorInterface is the base interface for errors. ErrorInterface itself cannot be instantiated, but there are several derived interfaces to indicate specific error conditions such as OutOfMemoryError, NullptrError or IllegalStateError.
An error typically contains file and line information (GetLocation()) and a message (GetMessage()). It may also have a stack trace (GetStackTrace()) and a cause (GetCause()), which is another error which caused this error.
Normally, errors shouldn't be used directly for return types of functions. Instead, you should use Result<T>
which can hold a result value and an error. The macros iferr and iferr_return support Result to facilitate error handling.
Errors are typically created in statements like
The usage of MAXON_SOURCE_LOCATION ensures that file and line information is set correctly in the error. The message is optional, and you can also pass a cause as third argument to the constructor. Some error classes may add specific constructors with additional arguments. But errors also support method chaining if you want so set additional values like the stack trace:
To trigger a DebugStop() or CriticalStop() on creation of an error, add DbgStop() or CritStop() at the end of the creation as in
The ToString implementation of errors supports the following format statements:
Classes | |
struct | ReferenceFunctions |
Public Types | |
using | Interface = ErrorInterface |
using | IsAllocType = std::true_type |
using | Ptr = maxon::RefBase< ReferenceFunctions< maxon::RefBaseFn< maxon::DirectRef< ErrorInterface, maxon::PointerHandler, void > >> > |
using | ConstPtr = maxon::RefBase< ReferenceFunctions< maxon::RefBaseFn< maxon::DirectRef< const ErrorInterface, maxon::PointerHandler, void > >> > |
using | PartFormatter = Delegate< String(const LanguageRef &language, const ConstDataPtr &part)> |
Public Types inherited from ObjectInterface | |
using | Interface = ObjectInterface |
using | IsAllocType = std::true_type |
using | Ptr = maxon::RefBase< ReferenceFunctions< maxon::RefBaseFn< maxon::DirectRef< ObjectInterface, maxon::PointerHandler, void > >> > |
using | ConstPtr = maxon::RefBase< ReferenceFunctions< maxon::RefBaseFn< maxon::DirectRef< const ObjectInterface, maxon::PointerHandler, void > >> > |
using | BaseInterface = ObjectInterface |
Public Member Functions | |
Ptr | GetPtr () |
ConstPtr | GetPtr () const |
MAXON_ADD_TO_COPY_ON_WRITE_REFERENCE_CLASS (protected:void Create(MAXON_SOURCE_LOCATION_DECLARATION) { *static_cast< typename S::DirectlyReferencedType::Hxx1::ReferenceClass * >(this)=S::DirectlyReferencedType::Hxx1::ErrObj::GetInstance()();typename S::DirectlyReferencedType::Ptr e=this->MakeWritable(false).GetPointer();e.SetLocation(MAXON_SOURCE_LOCATION_FORWARD);} void Create(MAXON_SOURCE_LOCATION_DECLARATION, const String &msg) { *static_cast< typename S::DirectlyReferencedType::Hxx1::ReferenceClass * >(this)=S::DirectlyReferencedType::Hxx1::ErrObj::GetInstance()();typename S::DirectlyReferencedType::Ptr e=this->MakeWritable(false).GetPointer();e.SetLocation(MAXON_SOURCE_LOCATION_FORWARD);e.SetMessage(msg);} void Create(MAXON_SOURCE_LOCATION_DECLARATION, const String &msg, const Error &cause) { *static_cast< typename S::DirectlyReferencedType::Hxx1::ReferenceClass * >(this)=S::DirectlyReferencedType::Hxx1::ErrObj::GetInstance()();typename S::DirectlyReferencedType::Ptr e=this->MakeWritable(false).GetPointer();e.SetLocation(MAXON_SOURCE_LOCATION_FORWARD);e.SetMessage(msg);e.SetCause(cause);}) | |
MAXON_ADD_TO_CONST_REFERENCE_CLASS (RefMemberType< S > DbgStop() { DebugOutput(OUTPUT::DIAGNOSTIC, static_cast< const typename S::ReferenceClass * >(this) ->ToString());DebugStop();return this->PrivateGetRefMember();} RefMemberType< S > CritStop() { CriticalOutput(static_cast< const typename S::ReferenceClass * >(this) ->ToString());return this->PrivateGetRefMember();} RefMemberType< S > DiagOutput() { DiagnosticOutput(static_cast< const typename S::ReferenceClass * >(this) ->ToString());return this->PrivateGetRefMember();}) | |
MAXON_METHOD const SourceLocation & | GetLocation () const |
MAXON_METHOD void | SetLocation (MAXON_SOURCE_LOCATION_DECLARATION) |
MAXON_METHOD Block< void *const > | GetStackTrace () const |
MAXON_METHOD void | SetStackTrace (const Block< void *const > &trace) |
MAXON_FUNCTION void | SetStackTrace (Int skip=STACKTRACE_SKIP) |
MAXON_FUNCTION Bool | IsCancellation () const |
MAXON_METHOD String | GetMessage () const |
MAXON_METHOD void | SetMessage (const String &message) |
MAXON_METHOD String | FormatMessage (const LanguageRef &language, const PartFormatter &partFormatter) const |
MAXON_METHOD void | SetMessageDelegate (Delegate< String(const LanguageRef &language, const ErrorInterface::PartFormatter &fmt)> &&message) |
MAXON_METHOD const Error & | GetCause () const |
MAXON_METHOD void | SetCause (const Error &cause) |
MAXON_METHOD void | GetMachine (MachineRef &machine) const |
MAXON_METHOD void | SetMachine (const MachineRef &machine) |
MAXON_METHOD Int | PrivateGetCode () const |
MAXON_METHOD void | PrivateSetCode (Int code) |
MAXON_METHOD void | PrivateSetPreallocation (ThreadReferencedError preallocation) const |
MAXON_METHOD ThreadReferencedError | PrivateGetPreallocation () const |
MAXON_METHOD void | PrivateSetDebugError (const Error &cause) const |
Public Member Functions inherited from ObjectInterface | |
Ptr | GetPtr () |
ConstPtr | GetPtr () const |
template<typename REFSUPERCLASS = ObjectRef> | |
MAXON_FUNCTION const maxon::Class< typename REFSUPERCLASS::PrivateErasedReferencedType::Hxx1::ReferenceClass > & | GetClass () const |
MAXON_FUNCTION const ClassInfo * | GetClassInfo () const |
template<typename REF > | |
const ComponentInfo & | GetComponentInfoOfSuper (const REF *sptr, OverloadRank0) const MAXON_IF_TARGET_DEBUG( |
template<typename REF , typename = typename REF::Component::ComponentClass> | |
const ComponentInfo & | GetComponentInfoOfSuper (const REF *sptr, OverloadRank1) const |
MAXON_FUNCTION Bool | HasSameClass (const ObjectInterface *obj) const |
Result< void > | CopyFrom (const ObjectInterface *src) |
Result< ObjectInterface * > | Clone () const |
template<typename REFCLASS > | |
MAXON_FUNCTION Result< REFCLASS > | Clone () const |
template<typename I > | |
MAXON_FUNCTION Bool | IsInstanceOf () const |
MAXON_FUNCTION Bool | IsInstanceOf (const DataType &type) const |
MAXON_METHOD String | ToString (const FormatStatement *formatStatement=nullptr) const |
MAXON_METHOD Result< void > | InitObject (const void *argument) |
MAXON_METHOD Result< void > | HandleMessage (const InternedId &message, void *argument) |
MAXON_METHOD Result< void > | HandleConstMessage (const InternedId &message, void *argument) const |
MAXON_METHOD Bool | IsEqual (const maxon::ObjectInterface *other) const |
MAXON_METHOD COMPARERESULT | Compare (const maxon::ObjectInterface *other) const |
MAXON_FUNCTION HashInt | GetHashCode () const |
MAXON_FUNCTION UniqueHash | GetUniqueHashCode () const |
MAXON_METHOD HashInt | GetHashCodeImpl () const |
MAXON_METHOD UniqueHash | GetUniqueHashCodeImpl () const |
MAXON_ADD_TO_CONST_REFERENCE_CLASS (Bool operator==(std::nullptr_t) const { return RefCompare< MAXON_IS_COW_KIND(S::Handler::KIND), true >::template IsEqual< const ObjectInterface *, const ObjectInterface * >(this->GetPointer(), nullptr);} Bool operator!=(std::nullptr_t) const { return !RefCompare< MAXON_IS_COW_KIND(S::Handler::KIND), true >::template IsEqual< const ObjectInterface *, const ObjectInterface * >(this->GetPointer(), nullptr);} Bool operator==(const ObjectInterface *ref) const { return RefCompare< MAXON_IS_COW_KIND(S::Handler::KIND), true >::template IsEqual< const ObjectInterface *, const ObjectInterface * >(this->GetPointer(), ref);} Bool operator!=(const ObjectInterface *ref) const { return !RefCompare< MAXON_IS_COW_KIND(S::Handler::KIND), true >::template IsEqual< const ObjectInterface *, const ObjectInterface * >(this->GetPointer(), ref);} Bool operator==(ObjectInterface *ref) const { return RefCompare< MAXON_IS_COW_KIND(S::Handler::KIND), true >::template IsEqual< const ObjectInterface *, const ObjectInterface * >(this->GetPointer(), ref);} Bool operator!=(ObjectInterface *ref) const { return !RefCompare< MAXON_IS_COW_KIND(S::Handler::KIND), true >::template IsEqual< const ObjectInterface *, const ObjectInterface * >(this->GetPointer(), ref);} template< typename T > Bool operator==(T *ref) const { return RefCompare< MAXON_IS_COW_KIND(S::Handler::KIND), true >::template IsEqual< const ObjectInterface *, const ObjectInterface * >(this->GetPointer(), ref);} template< typename T > Bool operator!=(T *ref) const { return !RefCompare< MAXON_IS_COW_KIND(S::Handler::KIND), true >::template IsEqual< const ObjectInterface *, const ObjectInterface * >(this->GetPointer(), ref);} template< typename R, typename=typename maxon::details::DisableComparison< typename S::PrivateReferencedType, typename R::ReferencedType >::type > Bool operator==(const R &ref) const { static_assert(AlwaysFalse< R >::value, "Can't compare unrelated reference classes.");return false;} template< typename R, typename=typename maxon::details::DisableComparison< typename S::PrivateReferencedType, typename R::ReferencedType >::type > Bool operator!=(const R &ref) const { static_assert(AlwaysFalse< R >::value, "Can't compare unrelated reference classes.");return false;}) | |
Bool | PrivateIsInstanceOf (const DataType &type) const |
Static Public Member Functions | |
static maxon::Id | GetInterfaceId () |
static ErrorInterface * | Alloc (const maxon::SourceLocation &, const ErrorInterface &src) |
template<typename DUMMY > | |
static maxon::Int | PrivateInstantiateDefaultValueHelper () |
static maxon::InterfaceReference * | PrivateGetInterface () |
template<typename T > | |
static MAXON_FUNCTION String | FormatPart (const LanguageRef &language, const ErrorInterface::PartFormatter &fmt, const T &part) |
Static Public Member Functions inherited from ObjectInterface | |
static maxon::Id | GetInterfaceId () |
static ObjectInterface * | Alloc (const maxon::SourceLocation &, const ObjectInterface &src) |
template<typename DUMMY > | |
static maxon::Int | PrivateInstantiateDefaultValueHelper () |
static maxon::InterfaceReference * | PrivateGetInterface () |
static constexpr MAXON_ATTRIBUTE_FORCE_INLINE std::nullptr_t | DefaultValuePtr () |
static void | PrivateFreeInstance (const ObjectInterface *o) |
Static Public Attributes | |
static maxon::InterfaceReference | _interface |
static maxon::NonvirtualInterfaceReference | _staticInterface |
static const maxon::EntityBase::FLAGS | REFERENCE_KIND |
Static Public Attributes inherited from ObjectInterface | |
static maxon::InterfaceReference | _interface |
static maxon::NonvirtualInterfaceReference | _staticInterface |
static const maxon::EntityBase::FLAGS | REFERENCE_KIND |
static const EntityBase::FLAGS | INTERFACE_FLAGS |
Protected Member Functions | |
~ ErrorInterface () | |
Protected Member Functions inherited from ObjectInterface | |
~ ObjectInterface () | |
void | RemoveReference () const |
Private Member Functions | |
ErrorInterface () | |
ErrorInterface (const ErrorInterface &) | |
void | operator= (const ErrorInterface &) |
void | PrivateCheckClass () |
MAXON_IMPLEMENTATION_MODULE ("net.maxon.kernel") | |
Static Private Member Functions | |
static ErrorInterface * | Alloc (const maxon::SourceLocation &) |
static maxon::Int | GetInfoOffset () |
Friends | |
class | maxon::ClassInterface |
class | maxon::ComponentDescriptor |
class | maxon::StrongCOWRefHandler |
Additional Inherited Members | |
Public Attributes inherited from ObjectInterface | |
maxon::ObjectInterface::ReferenceFunctions | MAXON_ENUM_LIST_CLASS |
using Interface = ErrorInterface |
using IsAllocType = std::true_type |
using Ptr = maxon::RefBase<ReferenceFunctions<maxon::RefBaseFn<maxon::DirectRef< ErrorInterface , maxon::PointerHandler, void> >> > |
using ConstPtr = maxon::RefBase<ReferenceFunctions<maxon::RefBaseFn<maxon::DirectRef<const ErrorInterface , maxon::PointerHandler, void> >> > |
using PartFormatter = Delegate<String(const LanguageRef& language, const ConstDataPtr& part)> |
A PartFormatter may be called by FormatMessage() to customize formatting of error message parts such as data types.
[in] | language | The language to use, may be left empty. |
[in] | part | The part of an error message to format. |
|
protected |
|
private |
|
private |
|
static |
|
static |
Ptr GetPtr | ( | ) |
ConstPtr GetPtr | ( | ) | const |
|
static |
|
static |
|
staticprivate |
|
staticprivate |
|
private |
|
private |
|
private |
MAXON_ADD_TO_COPY_ON_WRITE_REFERENCE_CLASS | ( | protected:void Create(MAXON_SOURCE_LOCATION_DECLARATION) { *static_cast< typename S::DirectlyReferencedType::Hxx1::ReferenceClass * >(this)=S::DirectlyReferencedType::Hxx1::ErrObj::GetInstance()();typename S::DirectlyReferencedType::Ptr e=this->MakeWritable(false).GetPointer();e.SetLocation(MAXON_SOURCE_LOCATION_FORWARD);} void Create(MAXON_SOURCE_LOCATION_DECLARATION, const String &msg) { *static_cast< typename S::DirectlyReferencedType::Hxx1::ReferenceClass * >(this)=S::DirectlyReferencedType::Hxx1::ErrObj::GetInstance()();typename S::DirectlyReferencedType::Ptr e=this->MakeWritable(false).GetPointer();e.SetLocation(MAXON_SOURCE_LOCATION_FORWARD);e.SetMessage(msg);} void Create(MAXON_SOURCE_LOCATION_DECLARATION, const String &msg, const Error &cause) { *static_cast< typename S::DirectlyReferencedType::Hxx1::ReferenceClass * >(this)=S::DirectlyReferencedType::Hxx1::ErrObj::GetInstance()();typename S::DirectlyReferencedType::Ptr e=this->MakeWritable(false).GetPointer();e.SetLocation(MAXON_SOURCE_LOCATION_FORWARD);e.SetMessage(msg);e.SetCause(cause);} | ) |
MAXON_ADD_TO_CONST_REFERENCE_CLASS | ( | RefMemberType< S > DbgStop() { DebugOutput(OUTPUT::DIAGNOSTIC, static_cast< const typename S::ReferenceClass * >(this) ->ToString());DebugStop();return this->PrivateGetRefMember();} RefMemberType< S > CritStop() { CriticalOutput(static_cast< const typename S::ReferenceClass * >(this) ->ToString());return this->PrivateGetRefMember();} RefMemberType< S > DiagOutput() { DiagnosticOutput(static_cast< const typename S::ReferenceClass * >(this) ->ToString());return this->PrivateGetRefMember();} | ) |
MAXON_METHOD const SourceLocation& GetLocation | ( | ) | const |
Returns the file location where the error was created.
MAXON_METHOD void SetLocation | ( | MAXON_SOURCE_LOCATION_DECLARATION | ) |
Sets the file location where the error was created.
[in] | allocLocation | Location (file and line) of the error creation. |
@MAXON_ANNOTATION{returnsThis,noResult}
MAXON_METHOD Block<void* const> GetStackTrace | ( | ) | const |
Returns the stack trace of this error. This may be empty.
MAXON_METHOD void SetStackTrace | ( | const Block< void *const > & | trace | ) |
Sets the stack trace of this error.
[in] | trace | Error stack trace to use for this error. |
@MAXON_ANNOTATION{returnsThis,noResult}
MAXON_FUNCTION void SetStackTrace | ( | Int | skip = STACKTRACE_SKIP | ) |
Sets the stack trace of this error to the current stack trace. The skip parameter allows to skip the topmost stack frames, which are typically insignificant as they include the SetStackTrace invocation itself.
[in] | skip | Number of stack frames to skip. A reasonable value may depend on the compiler and its settings and also on the context (e.g., whether the compiler inlined functions at the specific call site or not). |
@MAXON_ANNOTATION{returnsThis,noResult}
MAXON_FUNCTION Bool IsCancellation | ( | ) | const |
Returns true if an OperationCancelledError was returned.
MAXON_METHOD String GetMessage | ( | ) | const |
Returns the message of this error.
MAXON_METHOD void SetMessage | ( | const String & | message | ) |
Sets the message of this error.
[in] | message | Error message to use for this error. |
@MAXON_ANNOTATION{returnsThis,noResult}
MAXON_METHOD String FormatMessage | ( | const LanguageRef & | language, |
const PartFormatter & | partFormatter | ||
) | const |
Formats the message using the given language and formatter. The default implementation uses the delegate set by SetMessageDelegate or just GetMessage() if no such delegate has been set. This method can be overridden to support more human-friendly messages. The implementation may use the partFormatter to allow for customization of the formatting of certain parts of the error message.
[in] | language | The language to use, may be left empty. |
[in] | partFormatter | A delegate which is used to format parts of the message such as data types, can be null. |
MAXON_METHOD void SetMessageDelegate | ( | Delegate< String(const LanguageRef &language, const ErrorInterface::PartFormatter &fmt)> && | message | ) |
Sets a message delegate for this error. You can use the delegate instead of a fixed String message if you want to customize the message for different languages or allow for more human-friendly formatting of parts of the message.
[in] | message | Error message delegate to use for this error. |
@MAXON_ANNOTATION{returnsThis,noResult}
|
static |
Formats part using the given formatter and language. If the formatter is a null object, GlobalToString is used to convert part into a String.
[in] | language | The language to use, may be left empty. |
[in] | fmt | The part formatter to use, can be null. |
[in] | part | The part of an error message to format. |
MAXON_METHOD const Error& GetCause | ( | ) | const |
Returns the cause of this error. A cause is itself an error of which the current error is a subsequent error.
MAXON_METHOD void SetCause | ( | const Error & | cause | ) |
Sets the cause of this error. A cause is itself an error of which the current error is a subsequent error.
[in] | cause | Cause to use for this error. |
@MAXON_ANNOTATION{returnsThis,noResult}
MAXON_METHOD void GetMachine | ( | MachineRef & | machine | ) | const |
Returns the machine that caused this error.
[out] | machine | Receives the machine that caused this error. |
MAXON_METHOD void SetMachine | ( | const MachineRef & | machine | ) |
Sets the machine that caused this error.
[in] | machine | Machine that caused this error. |
MAXON_METHOD Int PrivateGetCode | ( | ) | const |
MAXON_METHOD void PrivateSetCode | ( | Int | code | ) |
@MAXON_ANNOTATION{returnsThis,noResult}
MAXON_METHOD void PrivateSetPreallocation | ( | ThreadReferencedError | preallocation | ) | const |
MAXON_METHOD ThreadReferencedError PrivateGetPreallocation | ( | ) | const |
MAXON_METHOD void PrivateSetDebugError | ( | const Error & | cause | ) | const |
|
friend |
|
friend |
|
friend |
|
static |
|
static |
|
static |