Generic Macros


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.

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();
bool Bool
boolean type, possible values are only false/true, 8 bit
Definition: apibase.h:181
Definition: compilerdetection.h:291
// This example shows the function call without and with handling the return value.
// this will trigger a compile error
// this won't trigger a compile error
const maxon::Bool res = CriticalFunction();
// this won't trigger a compile error
MAXON_WARN_MUTE_UNUSED CriticalFunction();
Py_UCS4 * res
Definition: unicodeobject.h:1113
The MAXON_WARN_MUTE_UNUSED macro is deprecated. Please use iferr_ignore or iferr_cannot_fail and spec...
Definition: compilerdetection.h:295
  • 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.
maxon::Int32 _info;
// This function returns a CriticalInfo.
static CriticalInfo GetCriticalInfo();
int32_t Int32
32 bit signed integer datatype.
Definition: apibase.h:176
Definition: compilerdetection.h:292
// 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
// this won't trigger a compile error
const CriticalInfo info = GetCriticalInfo();
DiagnosticOutput("Info: @", info._info);
#define DiagnosticOutput(formatString,...)
Definition: debugdiagnostics.h:176
_Py_clock_info_t * info
Definition: pytime.h:197

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.
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.
// this will trigger a compile warning that "number" is not used
const maxon::Int number = GetNumber();
// this won't trigger a warning
const maxon::Int number = GetNumber();
Int64 Int
signed 32/64 bit int, size depends on the platform
Definition: apibase.h:188
Definition: apibase.h:2818

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.
const maxon::Int key = 0;
maxon::Int number = data.Get(key, 0);
data.Set(key, number) iferr_return;
const maxon::Int key = 1;
maxon::Int number = data.Get(key, 0);
data.Set(key, number) iferr_return;
PyObject * key
Definition: abstract.h:289
#define iferr_return
Definition: resultbase.h:1465
// This example uses the MAXON_UNLIKELY to mark an unlikely case.
if (MAXON_UNLIKELY(number > 100))
number = 100;
Definition: compilerdetection.h:404

Switch-case statements can be improved with:

// This example defines a custom enumeration and checks if all elements are used in a switch-statement.
enum class MyEnum
const MyEnum value = MyEnum::B;
switch (value)
case MyEnum::A:
ApplicationOutput("Value A");
case MyEnum::B:
ApplicationOutput("Value B");
ApplicationOutput("No Value");
PyObject * value
Definition: abstract.h:715
#define ApplicationOutput(formatString,...)
Definition: debugdiagnostics.h:210
Definition: compilerdetection.h:361
Definition: compilerdetection.h:362
Quality A.
Definition: macros.h:1
@ C
Quality C.
@ A
Quality A.
@ B
Quality B.
Quality B.
Definition: macros.h:2


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()
// make sure that the allocated data will be deleted in any case
ReadData(data) iferr_return;
WriteData(data) iferr_return;
return maxon::OK;
#define NewMemClear(T, cnt)
Definition: defaultallocator.h:204
#define finally
Definition: finally.h:64
char Char
signed 8 bit character
Definition: apibase.h:184
return OK
Definition: apibase.h:2667
void DeleteMem(T *&p)
Definition: defaultallocator.h:257
#define iferr_scope
Definition: resultbase.h:1374


// This example shows the declaration of enumeration classes.
enum class PRIMARY_COLOR
RED = 1,
GREEN = 2,
BLUE = 3
enum class QUALITY
NONE = 0,
A = (1 << 0),
B = (1 << 1),
C = (1 << 2),
D = (1 << 3),
#define MAXON_ENUM_LIST(E,...)
Definition: enumflags.h:137
#define MAXON_ENUM_FLAGS(E,...)
Definition: enumflags.h:192
Various qualities.
Definition: macros.h:23
No qualities set.
@ D
Quality D.
Definition: macros.h:13
// This example shows how enumeration values are used.
// use simple enumeration
// set color
// check color
if (color == PRIMARY_COLOR::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:

These macros are used to implement certain operators automatically:

// This example shows a custom class using various macros
// to improve the class' functionality.
class NumberClass
_number = v;
// define copy constructor
NumberClass(const NumberClass& src) : MAXON_COPY_MEMBERS(_number) { }
// define assign operator "=" from copy constructor
// define "==", "!=" operators and GetHashCode()
// accessors
const maxon::Int* GetNumber() const
return &_number;
maxon::Int* GetNumber()
maxon::Int _number;
PyObject PyObject * v
Definition: abstract.h:297
PyObject * src
Definition: abstract.h:305
Definition: apibase.h:172
Definition: classhelpers.h:561
Definition: classhelpers.h:623
Definition: classhelpers.h:469
Definition: classhelpers.h:384
// 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;
PyObject Py_hash_t hash
Definition: dictobject.h:35
UInt64 UInt
unsigned 32/64 bit int, size depends on the platform
Definition: apibase.h:189


Other utility macros exist:

// 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;
DiagnosticOutput("Hash: @", hash);
Py_ssize_t i
Definition: abstract.h:645
Definition: string.h:1235
PyFrameObject * f
Definition: ceval.h:26
Float64 Float
Definition: apibase.h:197
#define MAXON_HASHCODE(...)
MAXON_HASHCODE computes the hash code of the arguments based on DefaultCompare::GetCombinedHashCode.
Definition: classhelpers.h:479

Further Reading