code_annotation.h File Reference

#include "lib/sysdep/compiler.h"
#include "lib/sysdep/arch.h"

Go to the source code of this file.

Classes
struct	static_assert_< true >
class	RValue< T >
Defines
#define	UNUSED(param)
	mark a function parameter as unused and avoid the corresponding compiler warning.
#define	UNUSED2(param)   ((void)(param))
	mark a function local variable or parameter as unused and avoid the corresponding compiler warning.
#define	NOTHROW_DECLARE
	indicate a function will not throw any synchronous exceptions, thus hopefully generating smaller and more efficient code.
#define	NOTHROW_DEFINE
#define	UNREACHABLE
	"unreachable code" helpers
#define	HAVE_ASSUME_UNREACHABLE   1
#define	ASSUME_UNREACHABLE
#define	HAVE_ASSUME_UNREACHABLE   0
#define	UNREACHABLE
	"unreachable code" helpers
#define	NODEFAULT   default: UNREACHABLE
	convenient specialization of UNREACHABLE for switch statements whose default can never be reached.
#define	PASTE3_HIDDEN__(a, b, c)   a ## b ## c
#define	PASTE3__(a, b, c)   PASTE3_HIDDEN__(a, b, c)
#define	UID__   PASTE3__(LINE_, __LINE__, _)
#define	UID2__   PASTE3__(LINE_, __LINE__, _2)
#define	cassert(expr)   typedef static_assert_<(expr)>::type UID__
	Compile-time assertion.
#define	cassert_dependent(expr)   typedef typename static_assert_<(expr)>::type UID__
#define	cassert2(expr)   extern char CASSERT_FAILURE[1][(expr)]
#define	NONCOPYABLE(className)
#define	ASSUME_ALIGNED(ptr, multiple)
#define	PRINTF_ARGS(fmtpos)
#define	VPRINTF_ARGS(fmtpos)
#define	WPRINTF_ARGS(fmtpos)
#define	VWPRINTF_ARGS(fmtpos)
#define	SENTINEL_ARG
#define	COMPILER_FENCE
	prevent the compiler from reordering loads or stores across this point.
#define	_W64
#define	RESTRICT
#define	ARRAY_SIZE(name)   (sizeof(*ArraySizeDeducer(name)))
#define	__func__   "(unknown)"
#define	EXTERN_C   extern
#define	INLINE   inline
#define	CALL_CONV
#define	DECORATED_NAME(name)   name
#define	STRINGIZE2(id)   # id
#define	STRINGIZE(id)   STRINGIZE2(id)
#define	WIDEN2(x)   L ## x
#define	WIDEN(x)   WIDEN2(x)
#define	RVALUE_REF(T)   T&&
	expands to the type `rvalue reference to T'; used in function parameter declarations.
#define	LVALUE(rvalue)   rvalue
	convert an rvalue to an lvalue
#define	RVALUE(lvalue)   std::move(lvalue)
	convert anything (lvalue or rvalue) to an rvalue
#define	RVALUE_REF(T)   const RValue<T>&
	expands to the type `rvalue reference to T'; used in function parameter declarations.
#define	LVALUE(rvalue)   rvalue.LValue()
	convert an rvalue to an lvalue
#define	RVALUE(lvalue)   ToRValue(lvalue)
	convert anything (lvalue or rvalue) to an rvalue
Functions
template<typename T , size_t n>
char(*	ArraySizeDeducer (T(&)[n]))[n]
template<class T >
static RValue< T >	ToRValue (T &lvalue)
template<class T >
static RValue< T >	ToRValue (const T &lvalue)
template<class T >
static RValue< T >	ToRValue (const RValue< T > &rvalue)

---

Define Documentation

#define __func__   "(unknown)"

#define _W64

#define ARRAY_SIZE

(

name

)

(sizeof(*ArraySizeDeducer(name)))

#define ASSUME_ALIGNED	(	ptr,
		multiple		)

#define ASSUME_UNREACHABLE

#define CALL_CONV

#define cassert

(

expr

)

typedef static_assert_<(expr)>::type UID__

Compile-time assertion.

Causes a compile error if the expression evaluates to zero/false.

No runtime overhead; may be used anywhere, including file scope. Especially useful for testing sizeof types.

Parameters:

expr

Expression that is expected to evaluate to non-zero at compile-time.

#define cassert2

(

expr

)

extern char CASSERT_FAILURE[1][(expr)]

Compile-time assertion. Causes a compile error if the expression evaluates to zero/false.No runtime overhead; may be used anywhere, including file scope. Especially useful for testing sizeof types.

Parameters:

expr

Expression that is expected to evaluate to non-zero at compile-time.

This version has a less helpful error message, but redefinition doesn't trigger warnings.

#define cassert_dependent

(

expr

)

typedef typename static_assert_<(expr)>::type UID__

Compile-time assertion. Causes a compile error if the expression evaluates to zero/false.No runtime overhead; may be used anywhere, including file scope. Especially useful for testing sizeof types.

Parameters:

expr

Expression that is expected to evaluate to non-zero at compile-time.

This version must be used if expr uses a dependent type (e.g. depends on a template parameter).

#define COMPILER_FENCE

prevent the compiler from reordering loads or stores across this point.

#define DECORATED_NAME

(

name

)

name

#define EXTERN_C   extern

#define HAVE_ASSUME_UNREACHABLE   0

#define HAVE_ASSUME_UNREACHABLE   1

#define INLINE   inline

#define LVALUE

(

rvalue

)

rvalue.LValue()

convert an rvalue to an lvalue

#define LVALUE

(

rvalue

)

rvalue

convert an rvalue to an lvalue

#define NODEFAULT   default: UNREACHABLE

convenient specialization of UNREACHABLE for switch statements whose default can never be reached.

example usage: int x; switch(x % 2) { case 0: break; case 1: break; NODEFAULT; }

#define NONCOPYABLE

(

className

)

Value:

private:\
    className(const className&);\
    const className& operator=(const className&)

#define NOTHROW_DECLARE

indicate a function will not throw any synchronous exceptions, thus hopefully generating smaller and more efficient code.

must be placed BEFORE return types because "The [VC++] compiler ignores, without warning, any __declspec keywords placed after *". such syntax is apparently also legal in GCC, per the example "__attribute__((noreturn)) void d0 (void)".

example: NOTHROW_DECLARE void function(); NOTHROW_DEFINE void function() {}

#define NOTHROW_DEFINE

#define PASTE3__	(	a,
		b,
		c		)	PASTE3_HIDDEN__(a, b, c)

#define PASTE3_HIDDEN__	(	a,
		b,
		c		)	a ## b ## c

#define PRINTF_ARGS

(

fmtpos

)

#define RESTRICT

#define RVALUE

(

lvalue

)

ToRValue(lvalue)

convert anything (lvalue or rvalue) to an rvalue

#define RVALUE

(

lvalue

)

std::move(lvalue)

convert anything (lvalue or rvalue) to an rvalue

#define RVALUE_REF

(

T

)

const RValue<T>&

expands to the type `rvalue reference to T'; used in function parameter declarations.

for example, UniqueRange's move ctor is: UniqueRange(RVALUE_REF(UniqueRange) rvalue) { ... }

#define RVALUE_REF

(

T

)

T&&

expands to the type `rvalue reference to T'; used in function parameter declarations.

for example, UniqueRange's move ctor is: UniqueRange(RVALUE_REF(UniqueRange) rvalue) { ... }

#define SENTINEL_ARG

#define STRINGIZE

(

id

)

STRINGIZE2(id)

#define STRINGIZE2

(

id

)

# id

#define UID2__   PASTE3__(LINE_, __LINE__, _2)

#define UID__   PASTE3__(LINE_, __LINE__, _)

#define UNREACHABLE

Value:

STMT(\
        DEBUG_WARN_ERR(ERR::LOGIC); /* hit supposedly unreachable code */\
        for(;;){};\
    )

"unreachable code" helpers

unreachable lines of code are often the source or symptom of subtle bugs. they are flagged by compiler warnings; however, the opposite problem - erroneously reaching certain spots (e.g. due to missing return statement) is worse and not detected automatically.

to defend against this, the programmer can annotate their code to indicate to humans that a particular spot should never be reached. however, that isn't much help; better is a sentinel that raises an error if if it is actually reached. hence, the UNREACHABLE macro.

ironically, if the code guarded by UNREACHABLE works as it should, compilers may flag the macro's code as unreachable. this would distract from genuine warnings, which is unacceptable.

even worse, compilers differ in their code checking: GCC only complains if non-void functions end without returning a value (i.e. missing return statement), while VC checks if lines are unreachable (e.g. if they are preceded by a return on all paths).

the implementation below enables optimization and automated checking without raising warnings.

#define UNREACHABLE

"unreachable code" helpers

unreachable lines of code are often the source or symptom of subtle bugs. they are flagged by compiler warnings; however, the opposite problem - erroneously reaching certain spots (e.g. due to missing return statement) is worse and not detected automatically.

to defend against this, the programmer can annotate their code to indicate to humans that a particular spot should never be reached. however, that isn't much help; better is a sentinel that raises an error if if it is actually reached. hence, the UNREACHABLE macro.

ironically, if the code guarded by UNREACHABLE works as it should, compilers may flag the macro's code as unreachable. this would distract from genuine warnings, which is unacceptable.

even worse, compilers differ in their code checking: GCC only complains if non-void functions end without returning a value (i.e. missing return statement), while VC checks if lines are unreachable (e.g. if they are preceded by a return on all paths).

the implementation below enables optimization and automated checking without raising warnings.

#define UNUSED

(

param

)

mark a function parameter as unused and avoid the corresponding compiler warning.

wrap around the parameter name, e.g. void f(int UNUSED(x))

#define UNUSED2

(

param

)

((void)(param))

mark a function local variable or parameter as unused and avoid the corresponding compiler warning.

note that UNUSED is not applicable to variable definitions that involve initialization, nor is it sufficient in cases where an argument is unused only in certain situations. example: void f(int x) { ASSERT(x == 0); UNUSED2(x); } this asserts in debug builds and avoids warnings in release.

#define VPRINTF_ARGS

(

fmtpos

)

#define VWPRINTF_ARGS

(

fmtpos

)

#define WIDEN

(

x

)

WIDEN2(x)

#define WIDEN2

(

x

)

L ## x

#define WPRINTF_ARGS

(

fmtpos

)

---

Function Documentation

template<typename T , size_t n>

char(* ArraySizeDeducer

(

T(&)

[n]

)

)[n] [inline]

template<class T >

static RValue<T> ToRValue

(

const RValue< T > &

rvalue

)

[inline, static]

template<class T >

static RValue<T> ToRValue

(

const T &

lvalue

)

[inline, static]

template<class T >

static RValue<T> ToRValue

(

T &

lvalue

)

[inline, static]