ErrorInterface Class Reference

#include <objectbase.h>

Inheritance diagram for ErrorInterface:

Detailed Description

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

return IllegalStateError(MAXON_SOURCE_LOCATION, "Object already contained in hierarchy."_s);
#define MAXON_SOURCE_LOCATION
Definition: memoryallocationbase.h:67

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:

return IllegalStateError(MAXON_SOURCE_LOCATION).SetMessage("Object already contained in hierarchy."_s).SetStackTrace();

To trigger a DebugStop() or CriticalStop() on creation of an error, add DbgStop() or CritStop() at the end of the creation as in

return IllegalStateError(MAXON_SOURCE_LOCATION).CritStop();

The ToString implementation of errors supports the following format statements:

  • "NoStack" to suppress the output of the call stack.
  • "NoLocation" to suppress the output of the code location.
  • "NoCause" to suppress the output of the cause error.
  • "NoMachine" to suppress the output of the machine. The machine is only printed out if it's not the local machine.
  • "Class" to print error class.
See also
@CLANGDUMMY errors

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 SourceLocationGetLocation () 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 ErrorInterfaceAlloc (MAXON_SOURCE_LOCATION_DECLARATION, const ErrorInterface &src)
 
template<typename DUMMY >
static maxon::Int PrivateInstantiateNullValueHelper ()
 
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 ObjectInterfaceAlloc (MAXON_SOURCE_LOCATION_DECLARATION, const ObjectInterface &src)
 
template<typename DUMMY >
static maxon::Int PrivateInstantiateNullValueHelper ()
 
static maxon::InterfaceReference * PrivateGetInterface ()
 
static constexpr MAXON_ATTRIBUTE_FORCE_INLINE std::nullptr_t NullValuePtr ()
 
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 ()
 

Static Private Member Functions

static ErrorInterfaceAlloc (MAXON_SOURCE_LOCATION_DECLARATION)
 
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
 

Member Typedef Documentation

◆ Interface

◆ IsAllocType

using IsAllocType = std::true_type

◆ Ptr

using Ptr = maxon::RefBase<ReferenceFunctions<maxon::RefBaseFn<maxon::DirectRef< ErrorInterface , maxon::PointerHandler, void> >> >

◆ ConstPtr

using ConstPtr = maxon::RefBase<ReferenceFunctions<maxon::RefBaseFn<maxon::DirectRef<const ErrorInterface , maxon::PointerHandler, void> >> >

◆ PartFormatter

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.

Parameters
[in]languageThe language to use, may be left empty.
[in]partThe part of an error message to format.
Returns
Formatted human-readable string representation of part.

Constructor & Destructor Documentation

◆ ~ ErrorInterface()

~ ErrorInterface ( )
protected

◆ ErrorInterface() [1/2]

ErrorInterface ( )
private

◆ ErrorInterface() [2/2]

ErrorInterface ( const ErrorInterface )
private

Member Function Documentation

◆ GetInterfaceId()

static maxon::Id GetInterfaceId ( )
static

◆ Alloc() [1/2]

static ErrorInterface* Alloc ( MAXON_SOURCE_LOCATION_DECLARATION  ,
const ErrorInterface src 
)
static

◆ GetPtr() [1/2]

Ptr GetPtr ( )

◆ GetPtr() [2/2]

ConstPtr GetPtr ( ) const

◆ PrivateInstantiateNullValueHelper()

static maxon::Int PrivateInstantiateNullValueHelper ( )
static

◆ PrivateGetInterface()

static maxon::InterfaceReference* PrivateGetInterface ( )
static

◆ Alloc() [2/2]

static ErrorInterface* Alloc ( MAXON_SOURCE_LOCATION_DECLARATION  )
staticprivate

◆ GetInfoOffset()

static maxon::Int GetInfoOffset ( )
staticprivate

◆ operator=()

void operator= ( const ErrorInterface )
private

◆ PrivateCheckClass()

void PrivateCheckClass ( )
private

◆ MAXON_ADD_TO_COPY_ON_WRITE_REFERENCE_CLASS()

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()

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();}  )

◆ GetLocation()

MAXON_METHOD const SourceLocation& GetLocation ( ) const

Returns the file location where the error was created.

Returns
Location (file and line) of the error creation.

◆ SetLocation()

Sets the file location where the error was created.

Parameters
[in]allocLocationLocation (file and line) of the error creation.

@MAXON_ANNOTATION{returnsThis,noResult}

◆ GetStackTrace()

MAXON_METHOD Block<void* const> GetStackTrace ( ) const

Returns the stack trace of this error. This may be empty.

Returns
Error stack trace.

◆ SetStackTrace() [1/2]

MAXON_METHOD void SetStackTrace ( const Block< void *const > &  trace)

Sets the stack trace of this error.

Parameters
[in]traceError stack trace to use for this error.

@MAXON_ANNOTATION{returnsThis,noResult}

◆ SetStackTrace() [2/2]

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.

Parameters
[in]skipNumber 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}

◆ IsCancellation()

MAXON_FUNCTION Bool IsCancellation ( ) const

Returns true if an OperationCancelledError was returned.

Returns
True if the error is a cancellation, false otherwise.

◆ GetMessage()

MAXON_METHOD String GetMessage ( ) const

Returns the message of this error.

Returns
Error message.

◆ SetMessage()

MAXON_METHOD void SetMessage ( const String message)

Sets the message of this error.

Parameters
[in]messageError message to use for this error.

@MAXON_ANNOTATION{returnsThis,noResult}

◆ FormatMessage()

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.

Parameters
[in]languageThe language to use, may be left empty.
[in]partFormatterA delegate which is used to format parts of the message such as data types, can be null.
Returns
Formatted human-readable message.

◆ SetMessageDelegate()

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.

Parameters
[in]messageError message delegate to use for this error.

@MAXON_ANNOTATION{returnsThis,noResult}

◆ FormatPart()

static MAXON_FUNCTION String FormatPart ( const LanguageRef &  language,
const ErrorInterface::PartFormatter fmt,
const T &  part 
)
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.

Parameters
[in]languageThe language to use, may be left empty.
[in]fmtThe part formatter to use, can be null.
[in]partThe part of an error message to format.
Returns
Formatted human-readable string representation of part.

◆ GetCause()

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.

Returns
Cause of this error, this will be a null reference in most cases.

◆ SetCause()

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.

Parameters
[in]causeCause to use for this error.

@MAXON_ANNOTATION{returnsThis,noResult}

◆ GetMachine()

MAXON_METHOD void GetMachine ( MachineRef &  machine) const

Returns the machine that caused this error.

Parameters
[out]machineReceives the machine that caused this error.

◆ SetMachine()

MAXON_METHOD void SetMachine ( const MachineRef &  machine)

Sets the machine that caused this error.

Parameters
[in]machineMachine that caused this error.

◆ PrivateGetCode()

MAXON_METHOD Int PrivateGetCode ( ) const

◆ PrivateSetCode()

MAXON_METHOD void PrivateSetCode ( Int  code)

@MAXON_ANNOTATION{returnsThis,noResult}

◆ PrivateSetPreallocation()

MAXON_METHOD void PrivateSetPreallocation ( ThreadReferencedError  preallocation) const

◆ PrivateGetPreallocation()

MAXON_METHOD ThreadReferencedError PrivateGetPreallocation ( ) const

◆ PrivateSetDebugError()

MAXON_METHOD void PrivateSetDebugError ( const Error &  cause) const

Friends And Related Function Documentation

◆ maxon::ClassInterface

friend class maxon::ClassInterface
friend

◆ maxon::ComponentDescriptor

friend class maxon::ComponentDescriptor
friend

◆ maxon::StrongCOWRefHandler

friend class maxon::StrongCOWRefHandler
friend

Member Data Documentation

◆ _interface

maxon::InterfaceReference _interface
static

◆ _staticInterface

maxon::NonvirtualInterfaceReference _staticInterface
static

◆ REFERENCE_KIND

const maxon::EntityBase::FLAGS REFERENCE_KIND
static