Open Search
    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 (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 ObjectInterfaceAlloc (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 ()
     

    Static Private Member Functions

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

    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 ( const maxon::SourceLocation ,
    const ErrorInterface src 
    )
    static

    ◆ GetPtr() [1/2]

    Ptr GetPtr ( )

    ◆ GetPtr() [2/2]

    ConstPtr GetPtr ( ) const

    ◆ PrivateInstantiateDefaultValueHelper()

    static maxon::Int PrivateInstantiateDefaultValueHelper ( )
    static

    ◆ PrivateGetInterface()

    static maxon::InterfaceReference* PrivateGetInterface ( )
    static

    ◆ Alloc() [2/2]

    static ErrorInterface* Alloc ( const maxon::SourceLocation )
    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