Error Types

Table of Contents

• About
• Built-in Types
• Custom Error
• Further Reading

About

For different situations different error classes exist. These different classes help to identify the nature of the error and allow to store additional information.

Built-in Types

The default error types are defined in the core.framework.

Note

In other frameworks various specialized error types exist.

To check the type of a given error one can use maxon::IsErrorOfType().

Errors about incorrect function arguments:

• maxon::IllegalArgumentErrorInterface: Indicates that an illegal argument was passed to a function parameter.
• maxon::UnsupportedArgumentErrorInterface: Indicates that a generally valid argument was passed to a function parameter, but the function implementation doesn't support that argument.
• maxon::NullptrErrorInterface: Indicates that an (illegal) nullptr was passed to a function.
• maxon::IllegalStateErrorInterface: Indicates that a function has been invoked on an object and the object hasn't been in a state which allows the proper execution of the function.

Errors about incorrect function implementations:

• maxon::FunctionNotImplementedErrorInterface: Indicates that a function has been invoked which did not contain a suitable implementation.
• maxon::UnsupportedOperationErrorInterface: Indicates that the intended operation is not supported by the implementation.
• maxon::UnresolvedErrorInterface: Indicates that an interface or declaration was accessed for which there is no definition.

Errors about incorrect program flow:

• maxon::OperationCancelledErrorInterface: Indicates that the function terminated because of a job or thread been cancelled from outside.
• maxon::ShutdownErrorInterface: Indicates that errors are being used while the object system is being shut down.

Specialised Errors:

• maxon::OutOfMemoryErrorInterface: Indicates that a memory allocation failed.
• maxon::ErrnoErrorInterface: Indicates an error storing an ANSI C file/IO error number. The number can be converted into a string using strerror().
• maxon::UnregisteredDataTypeErrorInterface: Indicates that GetDataType<T>() was called for an unregistered data type T.
• maxon::IoErrorInterface: Indicates an I/O error. The maxon::Url is stored with the error.
• maxon::UnknownFileSizeErrorInterface: Indicates an unknown file size.

General Errors:

• maxon::UnknownErrorInterface: Indicates an unspecified error.
• maxon::UnexpectedErrorInterface: Indicates that something unexpected happened within a function. This typically indicates a bug.
• maxon::AggregatedErrorInterface: Is an error that contains multiple errors. This error might be returned if multiple jobs of a group return errors. See maxon::AggregatedError.

// This example function checks every element in the given array.
// If an element is invalid, an error is added to the AggregatedError.
 
//----------------------------------------------------------------------------------------
// This function replaces each element of the given array with its square root.
// @param[in,out]   numbers     An array of maxon::Float32 values.
// @return                      maxon::OK on success.
//----------------------------------------------------------------------------------------
static maxon::Result<void> SquareRootElements(maxon::BaseArray<maxon::Float32>& numbers)
{
  iferr_scope;
 
  // prepare AggregatedError
  maxon::AggregatedError agg(MAXON_SOURCE_LOCATION);
 
  // loop through all elements of the given array
  const maxon::Int count = numbers.GetCount();
  for (maxon::Int i = 0; i < count; ++i)
  {
    maxon::Float32& number = numbers[i];
 
    if (number >= 0)
    {
      // replace value with its square root
      number = maxon::Sqrt(number);
    }
    else
    {
      // store error for invalid element
      const maxon::String errorMsg = FormatString("Negative number at index @", i);
      agg.AddError(maxon::IllegalArgumentError(MAXON_SOURCE_LOCATION, errorMsg)) iferr_return;
    }
  }
 
  // if any errors were found, return the collected errors
  if (agg.GetCount())
    return agg;
 
  return maxon::OK;
}

  // This example reads the AggregatedError returned by a function
  // and prints all sub-errors.
 
  const maxon::Result<void> res = SquareRootElements(data);
 
  // check for errors
  if (res == maxon::FAILED)
  {
    const maxon::Error error = res.GetError();
 
    // check for AggregatedError
    if (error.IsInstanceOf<maxon::AggregatedError>())
    {
      // get AggregatedError
      const maxon::AggregatedError agg = maxon::Cast<maxon::AggregatedError>(error);
 
      // loop through all sub-errors
      for (const maxon::Error subError : agg)
      {
        DiagnosticOutput("Sub-Error: @", subError);
      }
    }
  }

Custom Error

All error types are based on maxon::ErrorInterface. It is possible to create custom error types based on that interface. See also Interface Basics.

A custom error interfaces is based on the maxon::ErrorInterface (see Error Class):

// This example shows the declaration of a custom error type.
// The custom error is able to store a custom error code.
 
// ---------------------------------------------------------------------
// Custom error class that stores an error code.
// ---------------------------------------------------------------------
class ExampleErrorInterface : MAXON_INTERFACE_BASES(maxon::ErrorInterface)
{
  MAXON_INTERFACE(ExampleErrorInterface, MAXON_REFERENCE_COPY_ON_WRITE, "net.maxonexample.error.example");
 
public:
  MAXON_ADD_TO_COPY_ON_WRITE_REFERENCE_CLASS(
    void Create(MAXON_SOURCE_LOCATION_DECLARATION, maxon::Int errorCode)
    {
      *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.SetCustomErrorCode(errorCode);
    }
    );
 
  // custom methods
 
  // ---------------------------------------------------------------------
  // Stores an custom error code.
  // ---------------------------------------------------------------------
  MAXON_METHOD void SetCustomErrorCode(maxon::Int errorCode);
 
  // ---------------------------------------------------------------------
  // Returns the stored custom error code.
  // ---------------------------------------------------------------------
  MAXON_METHOD maxon::Int GetCustomErrorCode() const;
};

The registration or implementation of the custom error type can be simplified with these macros:

• ::MAXON_ERROR_REGISTERX: Registers the implementation and publishes the error object.
• MAXON_ERROR_IMPLEMENT_AND_REGISTER: Implements and registers a whole error interface that does not introduce additional methods.

// This example shows the implementation of a custom error type.
 
class ExampleErrorImpl : public maxon::Component<ExampleErrorImpl, ExampleErrorInterface>
{
  // use ErrorObjectClass to implement basic error functionality
  MAXON_COMPONENT(NORMAL, maxon::ErrorObjectClass);
 
public:
  maxon::Result<void> CopyFrom(const ExampleErrorImpl& src)
  {
    _errorCode = src._errorCode;
    return maxon::OK;
  }
 
public:
 
  MAXON_METHOD maxon::String GetMessage() const
  {
    return FormatString("Error Code is @", _errorCode);
  }
 
  // custom methods
 
  MAXON_METHOD void SetCustomErrorCode(maxon::Int errorCode)
  {
    _errorCode = errorCode;
  }
 
  MAXON_METHOD maxon::Int GetCustomErrorCode() const
  {
    return _errorCode;
  }
 
private:
  maxon::Int _errorCode;    
};
 
// register implementation
MAXON_COMPONENT_OBJECT_REGISTER(ExampleErrorImpl, ExampleErrorObject);

The new error type can now easily be used:

// This example creates and returns an instance of the custom error.
 
static maxon::Result<void> CustomOperation()
{
  // execute operation
  const maxon::Int res = Operate();
 
  // if no success, return error
  if (res == -1)
    return ExampleError(MAXON_SOURCE_LOCATION, res);
 
  return maxon::OK;
}

Further Reading

• Error System
• Error Handling
• Error Result
• Error Class
• Error Utility
• Debugging