#include <stdio.h>
#include <stddef.h>
#include "win/win.h"

Include dependency graph for macros.h:

This graph shows which files directly or indirectly include this file:

Macros
#define	STR_HELPER(x) #x
	Stringify `x` WITHOUT expanding it first. Implementation detail of STR().

#define	STR(x) STR_HELPER(x)
	Stringify `x` after macro-expanding it, e.g. STR(LINE) gives "42".

#define	DT_STRINGIFY_HELPER(x) #x
	Stringify `x` WITHOUT expanding it first. Implementation detail of DT_STRINGIFY().

#define	DT_STRINGIFY(x) DT_STRINGIFY_HELPER(x)
	Expand-then-stringify, identical in behaviour to STR().

#define	DT_RESTRICT restrict
	`restrict` in C, nothing in C++.

#define	IS_NULL_PTR(p)
	C is way too permissive with `!=`, `==` and `if(var)` checks, which can mean too many things depending on what we compare. We force here a semantic NULL check for pointers types that will fail for anything else than pointers, and make the code more explicit about what is checked. Rejected at COMPILE time: integers, floats, structs, and arrays – an array's `__typeof__` cannot initialise a local, which is what stops `IS_NULL_PTR(some_array)` from quietly testing a never-NULL decayed address.

#define	DT_FALLTHROUGH ((void)0)
	Mark a branch as impossible, naming it `D` in the message.

#define	dt_unreachable_codepath_with_desc(D) dt_unreachable_codepath_with_caller(D, __FILE__, __LINE__, __FUNCTION__)

#define	dt_unreachable_codepath() dt_unreachable_codepath_with_caller("unreachable", __FILE__, __LINE__, __FUNCTION__)
	Mark a branch as impossible.

Functions
static void	dt_unreachable_codepath_with_caller (const char description, const char file, const int line, const char *function)
	Back-end of the dt_unreachable_codepath() macros; call those, so the call site is recorded automatically.

Macro Definition Documentation

◆ DT_FALLTHROUGH

#define DT_FALLTHROUGH ((void)0)

Mark a branch as impossible, naming it D in the message.

See also: dt_unreachable_codepath()

Mark a deliberate switch fall-through so compilers and analysers stop warning.

Write it as a statement where the break would go: case 7: b |= ...; DT_FALLTHROUGH;

The conventional "fall through" COMMENT is understood by GCC's -Wimplicit-fallthrough and by clang-tidy, but not by every analyser – SonarCloud reports each one as c:S128 ("switch case should end with an unconditional break"), which is 7 findings on one intentionally-unrolled loop in common/hash.h. The attribute is a token the parser sees, so it settles the question everywhere at once.

Expands to nothing on a toolchain without the attribute, where the comment convention (or nothing at all) was the only option anyway.

Definition at line 127 of file macros.h.

◆ DT_RESTRICT

#define DT_RESTRICT restrict

restrict in C, nothing in C++.

restrict is not a C++ keyword, so a header shared with a .cc file cannot spell it directly. Where it survives (C), it is a PROMISE that the pointed-to memory is not reached through any other pointer for that object's lifetime; breaking the promise is undefined behaviour the compiler will happily optimise around, and the symptom is wrong pixels rather than a crash. Note the promise silently disappears in C++ translation units, so a bug it hides can behave differently in .c and .cc code.

Definition at line 73 of file macros.h.

◆ DT_STRINGIFY

#define DT_STRINGIFY ( x ) DT_STRINGIFY_HELPER(x)

Expand-then-stringify, identical in behaviour to STR().

Note: Both spellings exist for historical reasons and neither is deprecated. STR() is #undef'd before definition because windows.h and some third-party headers define a name that short; DT_STRINGIFY() is the collision-proof spelling and is the safer default in new code.

Definition at line 60 of file macros.h.

◆ DT_STRINGIFY_HELPER

#define DT_STRINGIFY_HELPER ( x ) #x

Stringify x WITHOUT expanding it first. Implementation detail of DT_STRINGIFY().

Definition at line 53 of file macros.h.

◆ dt_unreachable_codepath

#define dt_unreachable_codepath ( ) dt_unreachable_codepath_with_caller("unreachable", __FILE__, __LINE__, __FUNCTION__)

Mark a branch as impossible.

Warning: This is an ASSERTION OF FACT, not a guard. It ends in __builtin_unreachable(), which tells the optimiser the branch cannot be entered; if it ever is, the program has undefined behaviour and the printed message is no guarantee – the compiler may already have deleted the surrounding test. Use it only where the impossibility is structural. To HANDLE an unexpected value, return an error instead.

Definition at line 141 of file macros.h.

◆ dt_unreachable_codepath_with_desc

#define dt_unreachable_codepath_with_desc ( D ) dt_unreachable_codepath_with_caller(D, __FILE__, __LINE__, __FUNCTION__)

Definition at line 130 of file macros.h.

◆ IS_NULL_PTR

#define IS_NULL_PTR ( p )

Value:

  ({                                                              \
    __typeof__(p) _tmp = (p);                                     \
    (void)sizeof(char[                                            \
      (__builtin_classify_type(_tmp) == 5) ? 1 : -1               \
    ]);                                                           \
    _tmp == NULL;                                                 \
  })

C is way too permissive with !=, == and if(var) checks, which can mean too many things depending on what we compare. We force here a semantic NULL check for pointers types that will fail for anything else than pointers, and make the code more explicit about what is checked. Rejected at COMPILE time: integers, floats, structs, and arrays – an array's __typeof__ cannot initialise a local, which is what stops IS_NULL_PTR(some_array) from quietly testing a never-NULL decayed address.

ACCEPTED, contrary to what this comment claimed for a long time: function pointers. __builtin_classify_type() reports them as pointers, so IS_NULL_PTR(callback) compiles and does the obvious, useful thing. Verified rather than assumed.

Parameters

p	any pointer expression. Evaluated EXACTLY ONCE – it is bound to a local first – so `IS_NULL_PTR(*iter++)` is safe.

Returns: TRUE when p is NULL.

Note: Uses a GNU statement expression and typeof, so this header requires GCC or Clang. That is already true of the whole tree, MinGW included.

Definition at line 96 of file macros.h.

◆ STR

#define STR ( x ) STR_HELPER(x)

Stringify x after macro-expanding it, e.g. STR(LINE) gives "42".

Note: The indirection through STR_HELPER() is what forces the expansion; stringifying directly would yield "__LINE__".

Definition at line 49 of file macros.h.

◆ STR_HELPER

#define STR_HELPER ( x ) #x

Stringify x WITHOUT expanding it first. Implementation detail of STR().

Definition at line 43 of file macros.h.

Function Documentation

◆ dt_unreachable_codepath_with_caller()

static void dt_unreachable_codepath_with_caller	(	const char *	description,
		const char *	file,
		const int	line,
		const char *	function
	)

inlinestatic

Back-end of the dt_unreachable_codepath() macros; call those, so the call site is recorded automatically.