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 <inttypes.h>
#include <unistd.h>

Include dependency graph for defines.h:

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

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   1000
	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
	GCC will warn if you specify a function or parameter that is unused at runtime.
#define	PM_CONCATENATE(left, right)   left ## right
	Old Visual Studio versions do not support the inline keyword, so we need to define it to be __inline.
#define	PM_STATIC_ASSERT(line, condition, message)   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.
#define	PRISM_HAS_FILESYSTEM
	In general, libc for embedded systems does not support memory-mapped files.
#define	PRISM_ISINF(x)   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)   (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)   (x)
	Void because this platform does not support branch prediction hints.
#define	PRISM_FALLTHROUGH
	We use -Wimplicit-fallthrough to guard potentially unintended fall-through between cases of a switch.

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.

Macro Definition Documentation

PRISM_DEPTH_MAXIMUM

#define PRISM_DEPTH_MAXIMUM   1000

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.

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.

PRISM_ATTRIBUTE_FORMAT

#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.

This macro does that in a compiler-agnostic way.

PRISM_ATTRIBUTE_UNUSED

#define PRISM_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.

PM_CONCATENATE

#define PM_CONCATENATE	(		left,
			right
	)		left ## right

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

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.

PM_STATIC_ASSERT

#define PM_STATIC_ASSERT	(		line,
			condition,
			message
	)		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.

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.

PRISM_ISINF

#define PRISM_ISINF

(

x

)

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.

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.

xrealloc

#define xrealloc   realloc

The realloc function that should be used.

This can be overridden with the PRISM_XALLOCATOR define.

xcalloc

#define xcalloc   calloc

The calloc function that should be used.

This can be overridden with the PRISM_XALLOCATOR define.

xfree

#define xfree   free

The free function that should be used.

This can be overridden with the PRISM_XALLOCATOR define.

PRISM_LIKELY

#define PRISM_LIKELY

(

x

)

(x)

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. Void because this platform does not support branch prediction hints.

PRISM_FALLTHROUGH

#define PRISM_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.