Ruby  3.4.0dev (2024-12-06 revision 892c46283a5ea4179500d951c9d4866c0051f27b)
Macros
defines.h File Reference

(892c46283a5ea4179500d951c9d4866c0051f27b)

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. More...
 
#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. More...
 
#define PRISM_EXPORTED_FUNCTION
 By default, we compile with -fvisibility=hidden. More...
 
#define PRISM_ATTRIBUTE_FORMAT(string_index, argument_index)   __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. More...
 
#define PRISM_ATTRIBUTE_UNUSED   __attribute__((unused))
 GCC will warn if you specify a function or parameter that is unused at runtime. More...
 
#define inline   __inline
 Old Visual Studio versions do not support the inline keyword, so we need to define it to be __inline. More...
 
#define PM_CONCATENATE(left, right)   left ## right
 Old Visual Studio versions before 2015 do not implement sprintf, but instead implement _snprintf. More...
 
#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. More...
 
#define PRISM_HAS_FILESYSTEM
 In general, libc for embedded systems does not support memory-mapped files. More...
 
#define xmalloc   malloc
 isinf on POSIX systems it accepts a float, a double, or a long double. More...
 
#define xrealloc   realloc
 The realloc function that should be used. More...
 
#define xcalloc   calloc
 The calloc function that should be used. More...
 
#define xfree   free
 The free function that should be used. More...
 
#define PRISM_LIKELY(x)   __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. More...
 
#define PRISM_UNLIKELY(x)   __builtin_expect(!!(x), 0)
 The compiler should predicate that this branch will not be taken. More...
 

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 88 of file defines.h.

◆ PM_CONCATENATE

#define PM_CONCATENATE (   left,
  right 
)    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 103 of file defines.h.

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

Definition at line 113 of file defines.h.

◆ PRISM_ATTRIBUTE_FORMAT

#define PRISM_ATTRIBUTE_FORMAT (   string_index,
  argument_index 
)    __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 64 of file defines.h.

◆ 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 78 of file defines.h.

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

Definition at line 34 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 50 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 136 of file defines.h.

◆ PRISM_LIKELY

#define PRISM_LIKELY (   x)    __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 227 of file defines.h.

◆ PRISM_UNLIKELY

#define PRISM_UNLIKELY (   x)    __builtin_expect(!!(x), 0)

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

Definition at line 230 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 188 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 196 of file defines.h.

◆ xmalloc

#define xmalloc   malloc

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

But Windows didn't provide isinf, so we need to use _finite instead. 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 172 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 180 of file defines.h.