Generic Macros

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.

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();
bool Bool
boolean type, possible values are only false/true, 8 bit
Definition: apibase.h:206
#define MAXON_WARN_UNUSED
Definition: compilerdetection.h:302
// 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();
Py_UCS4 * res
Definition: unicodeobject.h:1113
#define MAXON_WARN_MUTE_UNUSED
The MAXON_WARN_MUTE_UNUSED macro is deprecated. Please use iferr_ignore or iferr_cannot_fail and spec...
Definition: compilerdetection.h:306
  • 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();
int32_t Int32
32 bit signed integer datatype.
Definition: apibase.h:201
#define MAXON_WARN_UNUSED_CLASS
Definition: compilerdetection.h:303
// 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);
#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.
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.
{
// 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();
UseVariable(number);
}
Int64 Int
signed 32/64 bit int, size depends on the platform
Definition: apibase.h:213
#define MAXON_SCOPE
Definition: apibase.h:2898

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

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
{
A,
B,
C
};
const MyEnum value = MyEnum::B;
switch (value)
{
case MyEnum::A:
ApplicationOutput("Value A");
break;
case MyEnum::B:
ApplicationOutput("Value B");
break;
default:
ApplicationOutput("No Value");
break;
}
PyObject * value
Definition: abstract.h:715
#define ApplicationOutput(formatString,...)
Definition: debugdiagnostics.h:210
#define MAXON_SWITCH_CHECKALLENUMS_BEGIN
Definition: compilerdetection.h:379
#define MAXON_SWITCH_CHECKALLENUMS_END
Definition: compilerdetection.h:380
A
Quality A.
Definition: macros.h:1
@ C
Quality C.
@ A
Quality A.
@ B
Quality B.
B
Quality B.
Definition: macros.h:2

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()
{
{
// 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;
}
#define NewMemClear(T, cnt)
Definition: defaultallocator.h:204
#define finally
Definition: finally.h:64
char Char
signed 8 bit character
Definition: apibase.h:209
return OK
Definition: apibase.h:2747
void DeleteMem(T *&p)
Definition: defaultallocator.h:257
#define iferr_scope
Definition: resultbase.h:1386

Enummerations

// 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
QUALITY
Various qualities.
Definition: macros.h:23
@ NONE
No qualities set.
@ D
Quality D.
PRIMARY_COLOR
[macros_enums_declare]
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
{
public:
{
_number = v;
}
// define copy constructor
NumberClass(const NumberClass& src) : MAXON_COPY_MEMBERS(_number) { }
// define assign operator "=" from copy constructor
// 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;
};
PyObject PyObject * v
Definition: abstract.h:297
PyObject * src
Definition: abstract.h:305
#define MAXON_IMPLICIT
Definition: apibase.h:197
#define MAXON_OPERATOR_EQUALITY_HASHCODE(T,...)
Definition: classhelpers.h:574
#define MAXON_NONCONST_COUNTERPART(...)
Definition: classhelpers.h:636
#define MAXON_COPY_MEMBERS(...)
Definition: classhelpers.h:482
#define MAXON_OPERATOR_COPY_ASSIGNMENT(TypeName)
Definition: classhelpers.h:397
// 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:214

Utility

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:222
#define MAXON_HASHCODE(...)
MAXON_HASHCODE computes the hash code of the arguments based on DefaultCompare::GetCombinedHashCode.
Definition: classhelpers.h:492

Further Reading