defines.h File Reference

Macro definitions used throughout the prism library. More...

#include <ctype.h>
#include <limits.h>
#include <math.h>
#include <stdarg.h>
#include <stddef.h>
#include <stdint.h>
#include <stdio.h>
#include <string.h>
#include <sys/types.h>
#include <inttypes.h>
#include <unistd.h>

Go to the source code of this file.

Macros
#define	__STDC_FORMAT_MACROS
	We want to be able to use the PRI* macros for printing out integers, but on some platforms they aren't included unless this is already defined.
#define	PRISM_DEPTH_MAXIMUM   10000
	When we are parsing using recursive descent, we want to protect against malicious payloads that could attempt to crash our parser.
#define	PRISM_EXPORTED_FUNCTION
	By default, we compile with -fvisibility=hidden.
#define	PRISM_ATTRIBUTE_FORMAT(string_index, argument_index)
	Certain compilers support specifying that a function accepts variadic parameters that look like printf format strings to provide a better developer experience when someone is using the function.
#define	PRISM_ATTRIBUTE_UNUSED   __attribute__((unused))
	GCC will warn if you specify a function or parameter that is unused at runtime.
#define	inline   __inline
	Old Visual Studio versions do not support the inline keyword, so we need to define it to be __inline.
#define	PM_CONCATENATE(left, right)
	Old Visual Studio versions before 2015 do not implement sprintf, but instead implement _snprintf.
#define	PM_STATIC_ASSERT(line, condition, message)
	We want to be able to use static assertions, but they weren't standardized until C11.
#define	PRISM_HAS_FILESYSTEM
	In general, libc for embedded systems does not support memory-mapped files.
#define	PRISM_ISINF(x)
	isinf on POSIX systems it accepts a float, a double, or a long double.
#define	xmalloc   malloc
	If you build prism with a custom allocator, configure it with "-D PRISM_XALLOCATOR" to use your own allocator that defines xmalloc, xrealloc, xcalloc, and xfree.
#define	xrealloc   realloc
	The realloc function that should be used.
#define	xcalloc   calloc
	The calloc function that should be used.
#define	xfree   free
	The free function that should be used.
#define	PRISM_LIKELY(x)
	If PRISM_BUILD_MINIMAL is defined, then we're going to define every possible switch that will turn off certain features of prism.
#define	PRISM_UNLIKELY(x)
	The compiler should predicate that this branch will not be taken.
#define	PRISM_FALLTHROUGH   __attribute__((fallthrough));
	We use -Wimplicit-fallthrough to guard potentially unintended fall-through between cases of a switch.
#define	PRISM_ASSUME(expr_)
	Tell the compiler that the given expression can be assumed to be true.

Detailed Description

Macro definitions used throughout the prism library.

This file should be included first by any *.h or *.c in prism for consistency and to ensure that the macros are defined before they are used.

Definition in file defines.h.

Macro Definition Documentation

__STDC_FORMAT_MACROS

#define __STDC_FORMAT_MACROS

We want to be able to use the PRI* macros for printing out integers, but on some platforms they aren't included unless this is already defined.

Definition at line 25 of file defines.h.

inline

#define inline   __inline

Old Visual Studio versions do not support the inline keyword, so we need to define it to be __inline.

Definition at line 91 of file defines.h.

Referenced by rb_fd_select(), rb_fd_set(), rb_num2ull(), and rb_random_mark().

PM_CONCATENATE

#define PM_CONCATENATE	(		left,
			right )

Value:

left ## right

Old Visual Studio versions before 2015 do not implement sprintf, but instead implement _snprintf.

We standard that here. A simple utility macro to concatenate two tokens together, necessary when one of the tokens is itself a macro.

Definition at line 106 of file defines.h.

PM_STATIC_ASSERT

#define PM_STATIC_ASSERT	(		line,
			condition,
			message )

Value:

typedef char PM_CONCATENATE(static_assert_, line)[(condition) ? 1 : -1]

We want to be able to use static assertions, but they weren't standardized until C11.

As such, we polyfill it here by making a hacky typedef that will fail to compile due to a negative array size if the condition is false.

Definition at line 116 of file defines.h.

PRISM_ASSUME

#define PRISM_ASSUME

(

expr_

)

Value:

__builtin_assume(expr_)

Tell the compiler that the given expression can be assumed to be true.

Unlike assert, this emits no runtime check — it only feeds the optimizer's value range analysis so it can prune impossible paths. Use it to communicate an invariant the caller guarantees but that the compiler cannot otherwise prove.

Definition at line 267 of file defines.h.

PRISM_ATTRIBUTE_FORMAT

#define PRISM_ATTRIBUTE_FORMAT	(		string_index,
			argument_index )

Value:

__attribute__((format(printf, string_index, argument_index)))

Certain compilers support specifying that a function accepts variadic parameters that look like printf format strings to provide a better developer experience when someone is using the function.

This macro does that in a compiler-agnostic way.

Definition at line 67 of file defines.h.

Referenced by pm_buffer_append_format().

PRISM_ATTRIBUTE_UNUSED

#define PRISM_ATTRIBUTE_UNUSED   __attribute__((unused))

GCC will warn if you specify a function or parameter that is unused at runtime.

This macro allows you to mark a function or parameter as unused in a compiler-agnostic way.

Definition at line 81 of file defines.h.

PRISM_DEPTH_MAXIMUM

#define PRISM_DEPTH_MAXIMUM   10000

When we are parsing using recursive descent, we want to protect against malicious payloads that could attempt to crash our parser.

We do this by specifying a maximum depth to which we are allowed to recurse.

Definition at line 37 of file defines.h.

PRISM_EXPORTED_FUNCTION

#define PRISM_EXPORTED_FUNCTION

By default, we compile with -fvisibility=hidden.

When this is enabled, we need to mark certain functions as being publically-visible. This macro does that in a compiler-agnostic way.

Definition at line 53 of file defines.h.

PRISM_FALLTHROUGH

#define PRISM_FALLTHROUGH   __attribute__((fallthrough));

We use -Wimplicit-fallthrough to guard potentially unintended fall-through between cases of a switch.

Use PRISM_FALLTHROUGH to explicitly annotate cases where the fallthrough is intentional.

Definition at line 253 of file defines.h.

PRISM_HAS_FILESYSTEM

#define PRISM_HAS_FILESYSTEM

In general, libc for embedded systems does not support memory-mapped files.

If the target platform is POSIX or Windows, we can map a file in memory and read it in a more efficient manner. If PRISM_HAS_NO_FILESYSTEM is defined, then we want to exclude all filesystem related code from the library. All filesystem related code should be guarded by PRISM_HAS_FILESYSTEM.

Definition at line 139 of file defines.h.

PRISM_ISINF

#define PRISM_ISINF

(

x

)

Value:

isinf(x)

isinf on POSIX systems it accepts a float, a double, or a long double.

But mingw didn't provide an isinf macro, only an isinf function that only accepts floats, so we need to use _finite instead.

Definition at line 151 of file defines.h.

PRISM_LIKELY

#define PRISM_LIKELY

(

x

)

Value:

__builtin_expect(!!(x), 1)

If PRISM_BUILD_MINIMAL is defined, then we're going to define every possible switch that will turn off certain features of prism.

Support PRISM_LIKELY and PRISM_UNLIKELY to help the compiler optimize its branch predication. The compiler should predicate that this branch will be taken.

Definition at line 234 of file defines.h.

PRISM_UNLIKELY

#define PRISM_UNLIKELY

(

x

)

Value:

__builtin_expect(!!(x), 0)

The compiler should predicate that this branch will not be taken.

Definition at line 237 of file defines.h.

xcalloc

#define xcalloc   calloc

The calloc function that should be used.

This can be overridden with the PRISM_XALLOCATOR define.

Definition at line 195 of file defines.h.

xfree

#define xfree   free

The free function that should be used.

This can be overridden with the PRISM_XALLOCATOR define.

Definition at line 203 of file defines.h.

xmalloc

#define xmalloc   malloc

If you build prism with a custom allocator, configure it with "-D PRISM_XALLOCATOR" to use your own allocator that defines xmalloc, xrealloc, xcalloc, and xfree.

For example, your prism_xallocator.h file could look like this:

#ifndef PRISM_XALLOCATOR_H
#define PRISM_XALLOCATOR_H
#define xmalloc      my_malloc
#define xrealloc     my_realloc
#define xcalloc      my_calloc
#define xfree        my_free
#endif

The malloc function that should be used. This can be overridden with the PRISM_XALLOCATOR define.

Definition at line 179 of file defines.h.

xrealloc

#define xrealloc   realloc

The realloc function that should be used.

This can be overridden with the PRISM_XALLOCATOR define.

Definition at line 187 of file defines.h.