Generic Macros

Table of Contents

• About
• Object Use
• Program Flow and Structure
• Finally
• Enummerations
• Classes and Functions
• Utility
• Further Reading

About

The Maxon API makes heavy use of C++ preprocessor macros. These macros are used to automatically create code or to mark parts of the code (e.g. in interfaces). The macros described on this page are relevant for every kind of development. Other specialised macros exist for special tasks.

Object Use

Under Xcode / GCC the compiler can check if the return value of a function is used or not. If a return value that should be used is not used, a compile error is thrown.

• MAXON_WARN_UNUSED: If the return value of this function is not used, a compile error is thrown.
• ::MAXON_WARN_MUTE_UNUSED: The compile error thrown by MAXON_WARN_UNUSED is muted.

Note

Do not use these macros to mute errors returned with the error system. Instead use iferr_cannot_fail() or iferr_ignore(). See Error Handling.

//----------------------------------------------------------------------------------------
// A critical function. Success must always be checked.
//----------------------------------------------------------------------------------------
MAXON_WARN_UNUSED static maxon::Bool CriticalFunction();

  // This example shows the function call without and with handling the return value.
 
  // this will trigger a compile error
  CriticalFunction();
 
  // this won't trigger a compile error
  const maxon::Bool res = CriticalFunction();
 
  // this won't trigger a compile error
  MAXON_WARN_MUTE_UNUSED CriticalFunction();
 

• MAXON_WARN_UNUSED_CLASS: If a class marked with this macro is used as a return value but this return value is not used, an error is thrown.

// This example shows a simple structure.
// It is marked with MAXON_WARN_UNUSED_CLASS,
// so when used as return value, this
// return value must be handled.
 
// A CriticalInfo.
struct MAXON_WARN_UNUSED_CLASS CriticalInfo
{
  maxon::Int32 _info; 
};
 
// This function returns a CriticalInfo.
static CriticalInfo GetCriticalInfo();

  // This example shows how the return value of the type of a MAXON_WARN_UNUSED_CLASS
  // marked class must be handled to avoid a compile error.
 
  // this will trigger a compile error
  GetCriticalInfo();
 
  // this won't trigger a compile error
  const CriticalInfo info = GetCriticalInfo();
 
  DiagnosticOutput("Info: @", info._info);
 

If a variable is declared but not used this will trigger a compile warning. This warning can be suppressed with this function:

• maxon::UseVariable(): Uses the given variable.

Note

Using maxon::UseVariable() will not cause any performance penalty.

  // This example shows how an unused variable triggers a warning and how this warning is silenced.
 
  MAXON_SCOPE
  {
    // this will trigger a compile warning that "number" is not used
    const maxon::Int number = GetNumber();
  }
 
  MAXON_SCOPE
  {
    // this won't trigger a warning
    const maxon::Int number = GetNumber();
    UseVariable(number);
  }

Program Flow and Structure

These macros are used to mark certain parts of the source code:

• MAXON_SCOPE: Marks a block of code that is scoped for a certain reason.
• MAXON_UNLIKELY: Marks an unlikely branch for branch prediction.
• MAXON_LIKELY: Marks a likely branch for branch prediction.

  // This example uses the MAXON_SCOPE macro to mark two blocks of code
  // that use the same variable names.
 
  MAXON_SCOPE
  {
    const maxon::Int key = 0;
    maxon::Int       number = data.Get(key, 0);
 
    number++;
 
    data.Set(key, number) iferr_return;
  }
 
  MAXON_SCOPE
  {
    const maxon::Int key = 1;
    maxon::Int       number = data.Get(key, 0);
 
    number++;
 
    data.Set(key, number) iferr_return;
  }

  // This example uses the MAXON_UNLIKELY to mark an unlikely case.
 
  if (MAXON_UNLIKELY(number > 100))
  {
    number = 100;
  }

Switch-case statements can be improved with:

• MAXON_SWITCH_CHECKALLENUMS_BEGIN: Enables a check if a switch-statement checks all elements of an enumeration.
• MAXON_SWITCH_CHECKALLENUMS_END: Disables above check.

  // This example defines a custom enumeration and checks if all elements are used in a switch-statement.
 
  enum class MyEnum
  {
    A,
    B,
    C
  };
 
  const MyEnum value = MyEnum::B;
 
  MAXON_SWITCH_CHECKALLENUMS_BEGIN;
  switch (value)
  {
    case MyEnum::A:
      ApplicationOutput("Value A");
      break;
    case MyEnum::B:
      ApplicationOutput("Value B");
      break;
    default:
      ApplicationOutput("No Value");
      break;
  }
  MAXON_SWITCH_CHECKALLENUMS_END;

Finally

The code defined in a "finally" block is executed when the program flow leaves the current scope.

• finally: Defines a code block which is executed when the scope is left.
• finally_once: Returns a maxon::FinallyOnce object that can be used to disable the code block execution.

// This example uses a "finally" block to ensure the allocated memory is deleted.
 
static maxon::Result<void> HandleMemory()
{
  iferr_scope;
 
  maxon::Char* data = NewMemClear(maxon::Char, 1024) iferr_return;
 
  finally
  {
    // make sure that the allocated data will be deleted in any case
    DeleteMem(data);
  };
 
  ReadData(data) iferr_return;
  WriteData(data) iferr_return;
 
  return maxon::OK;
}

Enummerations

• MAXON_ENUM_LIST(): Used to handle generic enummerations.
• MAXON_ENUM_FLAGS(): Used to handle bit flag enummerations.

// This example shows the declaration of enumeration classes.
 
//----------------------------------------------------------------------------------------
//----------------------------------------------------------------------------------------
enum class PRIMARY_COLOR
{
  RED = 1,    
  GREEN = 2,  
  BLUE  = 3   
} MAXON_ENUM_LIST(PRIMARY_COLOR);
 
//----------------------------------------------------------------------------------------
//----------------------------------------------------------------------------------------
enum class QUALITY
{
  NONE = 0,     
  A = (1 << 0), 
  B = (1 << 1), 
  C = (1 << 2), 
  D = (1 << 3), 
} MAXON_ENUM_FLAGS(QUALITY);

  // This example shows how enumeration values are used.
 
  // use simple enumeration
 
  // set color
  const PRIMARY_COLOR color = PRIMARY_COLOR::RED;
 
  // check color
  if (color == PRIMARY_COLOR::RED)
    DiagnosticOutput("Red");
 
  if (color != PRIMARY_COLOR::BLUE)
    DiagnosticOutput("Color is not blue.");
 
  // use bit flags
 
  // define qualities
  const QUALITY qualities = QUALITY::A | QUALITY::B;
 
  // check qualities
 
  if (qualities & QUALITY::A)
    DiagnosticOutput("Qualitiy A set");
 
  if (!(qualities & QUALITY::D))
    DiagnosticOutput("Quality D not set");

Classes and Functions

The following macros are used to declare classes and their functions:

• MAXON_IMPLICIT: Marks a constructor that is used for implicit construction.
• MAXON_NONCONST_COUNTERPART: Utility to simplify the implementation of a non-const counterpart of a const member function.
• MAXON_ATTRIBUTE_FORCE_INLINE: Forces the compiler to use the function inline.
• MAXON_DISALLOW_COPY_AND_ASSIGN: Makes sure an instance of the class cannot be copied.
• MAXON_COPY_MEMBERS: Defines the members copied in a copy constructor.
• MAXON_MOVE_MEMBERS: Defines the members copied in a move constructor.

These macros are used to implement certain operators automatically:

• MAXON_OPERATOR_EQUALITY: Defines operator "==" and operator "!=" based on the equality operators for the given class members.
• MAXON_OPERATOR_COMPARISON: Defines member operators "!=", ">", "<=" and ">=" based on the member operators "==" and "<".
• MAXON_OPERATOR_INEQUALITY: Defines member operators ">", "<=" and ">=" based on the member operator "<".
• MAXON_OPERATOR_EQUALITY_HASHCODE: Utility that defines the "==" and "!=" operators and a GetHashCode() method.
• MAXON_OPERATOR_COPY_ASSIGNMENT: Creates a copy assignment operator from an existing copy constructor.
• MAXON_OPERATOR_MOVE_ASSIGNMENT: Creates a move assignment operator from an existing move constructor.

// This example shows a custom class using various macros
// to improve the class' functionality.
 
class NumberClass
{
public:
  MAXON_IMPLICIT NumberClass(maxon::Int v)
  {
    _number = v;
  }
 
  // define copy constructor
  NumberClass(const NumberClass& src) : MAXON_COPY_MEMBERS(_number) { }
 
  // define assign operator "=" from copy constructor
  MAXON_OPERATOR_COPY_ASSIGNMENT(NumberClass);
 
  // define "==", "!=" operators and GetHashCode()
  MAXON_OPERATOR_EQUALITY_HASHCODE(NumberClass, _number);
 
  // accessors
 
  const maxon::Int* GetNumber() const
  {
    return &_number;
  }
 
  maxon::Int* GetNumber()
  {
    return MAXON_NONCONST_COUNTERPART(GetNumber());
  }
 
private:
  maxon::Int _number; 
};

  // This example uses a class defined with various macros to implement
  // a non-const access function and GetHashCode().
 
  NumberClass someNumber(1);
 
  // edit
  maxon::Int* const number = someNumber.GetNumber();
  *number = *number + 1;
 
  // print
  const maxon::Int* const res = someNumber.GetNumber();
  DiagnosticOutput("Number: @", *res);
 
  // hash
  const maxon::UInt hash = someNumber.GetHashCode();
  DiagnosticOutput("Hash: @", hash);
 
  // copy
  NumberClass someOtherNumber(0);
  someOtherNumber = someNumber;

Utility

Other utility macros exist:

• MAXON_STRINGIFY(): Turns the given symbol into a string.
• MAXON_FUNCTIONNAME: Returns the name of the current function as a maxon::Id.
• MAXON_HASHCODE: Calculates a hash code for the given arguments.
• MAXON_DEPRECATED_ENUMVALUE: Marks an entry in an enumeration as deprecated.

  // This example uses various utility macros.
 
  // prints the value of the macro SOME_VALUE
  const maxon::String value(MAXON_STRINGIFY(SOME_VALUE));
  DiagnosticOutput("Some Value: @", value);
 
  // print the hash of the given values
 
  const maxon::Int   i = 123;
  const maxon::Float f = 132.0;
 
  const maxon::UInt hash = MAXON_HASHCODE(i, f);
  DiagnosticOutput("Hash: @", hash);

Further Reading

• C++ Techniques
• Debug and Output Functions