view release on metacpan or  search on metacpan

lib/Affix.h  view on Meta::CPAN

    Affix_Opcode opcode;           // The instruction for the VM
    Affix_Step_Data data;          // Pre-calculated data needed by the executor.
};
/// Represents a forward FFI call (a Perl sub that calls a C function).
/// This struct holds the pre-compiled execution plan and is attached to the generated XS subroutine.
struct Affix {
    infix_forward_t * infix;          ///< Handle to the infix trampoline and type info.
    infix_arena_t * args_arena;       ///< Persistent arena for type data (init-time only).
    infix_arena_t * ret_arena;        ///< Persistent arena for return type data (init-time only).
    infix_arena_t * call_args_arena;  ///< Per-call temp arena for arguments (fiber-safe: not restored via SAVEVPTR).
    infix_arena_t * call_ret_arena;   ///< Per-call temp arena for return value (fiber-safe: not restored via SAVEVPTR).
    infix_cif_func cif;               ///< A direct function pointer to the JIT-compiled trampoline code.
    infix_library_t * lib_handle;     ///< If affix() loaded a library itself, stores the handle for cleanup.
    SV * return_sv;                   ///< Pre-allocated, reusable SV to hold the return value.
    Affix_Plan_Step * plan;           ///< The linear array of operations (the "execution plan").
    size_t plan_length;               ///< The total number of steps in the plan.
    size_t num_args;                  ///< Cached number of arguments for faster access.
    size_t total_args_size;           ///< Pre-calculated total size of the C arguments buffer.
    // Pre-compiled plan for handling "out" parameters after the C call.
    OutParamInfo * out_param_info;
    size_t num_out_params;
    const infix_type * ret_type;
    const infix_type * unwrapped_ret_type;  // Pre-unwrapped for OP_RET_PTR
    Affix_Pull ret_pull_handler;            ///< Cached handler for marshalling the return value.
    Affix_Opcode ret_opcode;                ///< Optimized return opcode.
    bool ret_readonly;                      ///< Should the returned aggregate prevent perl-side mutations?
    void ** c_args;

    // Reconstruction info for threading/cloning
    char * sig_str;
    char * sym_name;
    void * target_addr;
    char * lib_path;
    dTHXfield(owner_perl)

        // Variadic demo
        HV * variadic_cache;
    size_t num_fixed_args;
};

/**
 * @struct Affix_Pin_2_Point_Oh
 * @brief The internal payload attached to Perl Scalars via Perl Magic (PERL_MAGIC_ext).
 * @details This struct holds the raw C pointer, type metadata, and bitfield offsets.
 * When Perl attempts to read or write a scalar, the VTable fetches this struct to
 * map the scalar value directly to native C memory.
 */
typedef struct {
    void * ptr;              /**< Pointer to the actual C memory backing this variable. */
    const infix_type * type; /**< Pointer to the parsed AST type node. */
    infix_arena_t * arena;   /**< Local arena for anonymous types. */
    uint8_t bit_offset;      /**< Bitfield offset (0 for standard types). */
    uint8_t bit_width;       /**< Bitfield width in bits (0 for standard types). */
    bool readonly;           /**< True if the pin is marked const/readonly. */
    bool absolute;           /**< True if ptr is the target address, false if it's the address of a variable */
    void (*destructor)(void *);
    SV * destructor_lib_sv;
} Affix_Pin_2_Point_Oh;
/// Holds the necessary data for a callback, specifically the Perl subroutine to call.
typedef struct {
    SV * coderef_rv;  ///< A reference (RV) to the Perl coderef. We hold this to keep it alive.
    dTHXfield(perl)   ///< The thread context in which the callback was created.
} Affix_Callback_Data;
/// Internal struct holding the C resources that are magically attached
///        to a user's coderef (CV*) when it is first used as a callback.
typedef struct {
    infix_reverse_t * reverse_ctx;  ///< Handle to the infix reverse-call trampoline.
} Implicit_Callback_Magic;
/// An entry in the thread-local library registry hash.
typedef struct {
    infix_library_t * lib;  ///< The handle to the opened library.
    UV ref_count;           ///< Reference count. The library is closed only when this reaches 0.
} LibRegistryEntry;

// Struct for the Direct Marshalling (aka "bundle") backend.
/// Represents a forward FFI call created with the high-performance direct marshalling API.
struct Affix_Backend {
    infix_forward_t * infix;       ///< Handle to the infix trampoline and type info.
    infix_direct_cif_func cif;     ///< Direct pointer to the specialized JIT code.
    infix_library_t * lib_handle;  ///< Handle for library cleanup.
    const infix_type * ret_type;   ///< Cached return type info.
    Affix_Pull pull_handler;       ///< Pre-resolved handler for marshalling the return value.
    Affix_Opcode ret_opcode;       ///< Optimized return opcode.
    bool ret_readonly;             ///< Should the returned aggregate prevent perl-side mutations?
    size_t num_args;               ///< Cached number of arguments.

    char * sig_str;
    char * sym_name;
    void * target_addr;
    char * lib_path;
    dTHXfield(owner_perl)
};

// Trigger function for the experimental backend (shh!)
extern void Affix_trigger_backend(pTHX_ CV *);

// Main execution trigger
extern void Affix_trigger_stack(pTHX_ CV *);
extern void Affix_trigger_arena(pTHX_ CV *);
extern void Affix_trigger_variadic(pTHX_ CV *);

// Marshalling (Perl -> C)
void sv2ptr(pTHX_ Affix * affix, SV * perl_sv, void * c_ptr, const infix_type * type);
void push_struct(pTHX_ Affix * affix, const infix_type * type, SV * sv, void * p);
void push_array(pTHX_ Affix * affix, const infix_type * type, SV * sv, void * p);
void push_reverse_trampoline(pTHX_ Affix * affix, const infix_type * type, SV * sv, void * p);

// Marshalling (Perl <- C)
void ptr2sv(pTHX_ Affix *, void *, SV *, const infix_type *, bool);
void _populate_hv_from_c_struct(
    pTHX_ Affix * affix, HV * hv, const infix_type * type, void * p, bool live, SV * owner_sv, bool);

// Handler resolution
Affix_Step_Executor get_plan_step_executor(const infix_type * type);
Affix_Pull get_pull_handler(pTHX_ const infix_type * type);
Affix_Out_Param_Writer get_out_param_writer(const infix_type * type);

// Pin management

// Reverse trampolines
void _affix_callback_handler_entry(infix_context_t *, void *, void **);