view release on metacpan or  search on metacpan

infix/include/infix/infix.h  view on Meta::CPAN

/**
 * @def INFIX_NODISCARD
 * @brief A compatibility macro for the C23 `[[nodiscard]]` attribute.
 *
 * @details This attribute is used to issue a compiler warning if the return value
 * of a function is ignored by the caller. This is extremely useful for catching
 * bugs where an error code or an important result is not checked.
 *
 * This macro expands to:
 * - `[[nodiscard]]` on compilers that support the C23 standard syntax.
 * - `__attribute__((warn_unused_result))` on GCC and Clang.
 * - `_Check_return_` on Microsoft Visual C++.
 * - Nothing on other compilers.
 *
 * This is aliased as `c23_nodiscard` in `compat_c23.h`.
 */
#if defined(__STDC_VERSION__) && __STDC_VERSION__ > 201710L && _INFIX_HAS_C_ATTRIBUTE(nodiscard) && \
    !defined(__GNUC__) && !defined(__clang__)
#define INFIX_NODISCARD [[nodiscard]]
#elif defined(__GNUC__) || defined(__clang__)
#define INFIX_NODISCARD __attribute__((warn_unused_result))
#elif defined(_MSC_VER)
#define INFIX_NODISCARD _Check_return_
#else
#define INFIX_NODISCARD
#endif

/**
 * @struct infix_version_t
 * @brief A structure representing the semantic version of the library.
 * @see infix_get_version
 */
typedef struct {
    int major; /**< The major version number (incremented for incompatible API changes). */
    int minor; /**< The minor version number (incremented for backwards-compatible features). */
    int patch; /**< The patch version number (incremented for backwards-compatible bug fixes). */
} infix_version_t;

/** @} */
// Define the POSIX source macro to ensure function declarations for shm_open,
// ftruncate, etc., are visible on all POSIX-compliant systems.
// This must be defined before any system headers are included.
#ifndef _DEFAULT_SOURCE
#define _DEFAULT_SOURCE
#endif
// Define the POSIX source macro to ensure function declarations for posix_memalign
// are visible. This must be defined before any system headers are included.
#if !defined(_POSIX_C_SOURCE)
#define _POSIX_C_SOURCE 200809L
#endif
#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>

#ifdef __cplusplus
extern "C" {
#endif
/**
 * @brief Retrieves the version of the infix library linked at runtime.
 *
 * @details This function allows applications to verify that the version of the
 *          library they are linked against matches the headers they were compiled with.
 *          This is particularly useful when loading `infix` as a shared library/DLL
 *          to detect version mismatches.
 *
 * @return An `infix_version_t` structure containing the major, minor, and patch numbers.
 */
INFIX_API INFIX_NODISCARD infix_version_t infix_get_version(void);

/**
 * @defgroup high_level_api High-Level Signature API
 * @brief The primary, recommended API for creating trampolines from human-readable strings.
 *
 * This API provides the simplest and most powerful way to interact with `infix`.
 * All functions in this group take a signature string and an optional type registry
 * to parse and generate the required FFI trampolines.
 * @{
 */
/**
 * @defgroup type_system Type System
 * @brief The core data structures and APIs for describing C types and function signatures.
 *
 * `infix` uses a powerful, introspectable type system to represent C types. These
 * structures can be created programmatically using the Manual API or parsed from
 * human-readable signature strings.
 *
 * @{
 */
// Opaque and Semi-Opaque Type Forward Declarations
/** @brief A semi-opaque object describing a C type's memory layout and calling convention. See `infix_type_t` for
 * details. */
typedef struct infix_type_t infix_type;
/** @brief A semi-opaque object describing a member of a C struct or union. See `infix_struct_member_t` for details. */
typedef struct infix_struct_member_t infix_struct_member;
/** @brief A semi-opaque object describing an argument to a C function. See `infix_function_argument_t` for details. */
typedef struct infix_function_argument_t infix_function_argument;
/** @brief An opaque handle to a forward (C-to-native) trampoline. Created by `infix_forward_create` and variants. */
typedef struct infix_forward_t infix_forward_t;
/** @brief An opaque handle to a reverse (native-to-C) trampoline, also known as a callback or closure. */
typedef struct infix_reverse_t infix_reverse_t;
/** @brief An alias for `infix_reverse_t`, used to clarify its role as a context object in closure handlers. */
typedef infix_reverse_t infix_context_t;
/** @brief An opaque handle to an arena allocator, used for efficient grouped memory allocations. */
typedef struct infix_arena_t infix_arena_t;
/** @brief An opaque handle to a dynamically loaded shared library (`.so`, `.dll`, `.dylib`). */
typedef struct infix_library_t infix_library_t;
/** @brief An opaque handle to a named type registry. */
typedef struct infix_registry_t infix_registry_t;

/**
 * @brief Enumerates the fundamental categories of types that `infix` can represent.
 */
typedef enum {
    INFIX_TYPE_PRIMITIVE,          /**< A fundamental C type like `int`, `float`, or `double`. */
    INFIX_TYPE_POINTER,            /**< A pointer to another `infix_type`. */
    INFIX_TYPE_STRUCT,             /**< A C `struct`. */
    INFIX_TYPE_UNION,              /**< A C `union`. */
    INFIX_TYPE_ARRAY,              /**< A fixed-size C array. */
    INFIX_TYPE_REVERSE_TRAMPOLINE, /**< A function pointer type, used internally by the signature parser. */
    INFIX_TYPE_ENUM,               /**< A C `enum`, represented by its underlying integer type. */
    INFIX_TYPE_COMPLEX,            /**< A C99 `_Complex` number. */