//! Host-language callback invoker registry.

//!

//! Managed-FFI bindings (Lua, Ruby, Perl, PHP, OCaml, Node, C#, Java, …) can't

//! generate C-ABI trampolines for callback typedefs that take aggregate args

//! by value — that's a libffi / LuaJIT FFI / ruby-ffi limitation we can't fix

//! at the host. This module provides the alternative the user's analysis

//! settled on: each language registers **one** generic invoker function at

//! module load time, plus a releaser that fires when a host-language handle

//! goes out of use.

//!

//! Every callback the host registers becomes a `Callback { cb, ctx }` pair

//! whose `cb` is a *static thunk* in libazul (so by-value args land on a

//! native frame the way the framework already expects), and whose `ctx` is

//! a `RefAny` payload that carries an opaque host-language `u64` handle.

//! The thunk reads `info.get_ctx()`, extracts the handle, and dispatches to

//! the registered per-kind invoker — which, on the host side, looks up the

//! callable by id in a host-managed table and runs it. When the RefAny's

//! refcount drops to zero, the destructor calls back through the registered

//! releaser so the host can drop its table entry, mirroring Python's

//! `Py<PyAny>` lifetime story without making libazul link against any host

//! runtime.

//!

//! ## API surface

//!

//! - [`AzApp_setHostHandleReleaser`] — register the host's "drop this id"

//!   callback once per process. Fires when a host-handle [`RefAny`] is

//!   collected.

//! - Per callback kind, [`crate::impl_managed_callback!`] expands to:

//!   - A static thunk (`extern "C" fn`) compiled into libazul.

//!   - A `<Wrapper>::create_from_host_handle(u64)` constructor.

//!   - An `AzApp_set<Kind>Invoker(...)` setter for the host-side per-kind

//!     pointer-arg invoker.

//!

//! ## Why a single shared releaser

//!

//! Per-kind invokers are necessarily distinct — each callback typedef has

//! a different signature, so the host has to register a libffi closure per

//! typedef anyway. The releaser, on the other hand, has the same signature

//! for every kind (`extern "C" fn(u64)`), so we can share one slot across

//! all callbacks; the host registers it once and every kind's destructor

//! routes through it.

use core::ffi::c_void;

use core::sync::atomic::{AtomicUsize, Ordering};

use azul_css::AzString;

use crate::refany::RefAny;

/// RTTI id stamped into every RefAny created via [`host_handle_to_refany`].

///

/// Hosts must not reuse this id for their own user-data RefAnys, otherwise

/// `refany_to_host_handle` would mis-identify their data as a host handle

/// and the destructor would call the registered releaser with a bogus id.

/// The high 32 bits are reserved for azul-internal RTTI ids; the low 32

/// spell `'H','S','T','H'` so the value reads `0xA20A_4853_5448_5F44`.

pub const AZ_HOST_HANDLE_RTTI_ID: u64 = 0xA20A_4853_5448_5F44;

/// Heap payload stored inside the [`RefAny`] returned by

/// [`host_handle_to_refany`]. Just the opaque host-language id — the actual

/// host callable lives on the host side keyed by this id.

#[repr(C)]

pub struct HostHandlePayload {

    pub id: u64,

}

/// A single atomic-pointer slot for one registered host-side function

/// pointer. `0` means "not registered"; the static thunks bail out (returning

/// the kind's default value) when they see an unregistered slot rather than

/// transmuting `0` into a fn pointer and crashing.

#[repr(C)]

pub struct InvokerSlot {

    fn_ptr: AtomicUsize,

}

impl InvokerSlot {

    /// Create an empty slot. `const` so it can be used to declare `static`

    /// per-kind slots in `impl_managed_callback!` expansions.

    /// Replace the registered function pointer.

    ///

    /// `SeqCst` because the slot is read on every callback fire and we

    /// don't want any stale-pointer windows after the host swaps invokers

    /// (rare but legal — e.g. unloading a Lua module that registered).

    /// Read the current function pointer; `0` if unregistered.

}

impl Default for InvokerSlot {

}

/// Process-global slot for the host's "drop a handle id" callback. Set via

/// [`AzApp_setHostHandleReleaser`]. Read by [`host_handle_destructor`]

/// when a host-handle [`RefAny`]'s last clone drops.

pub static HOST_HANDLE_RELEASER: InvokerSlot = InvokerSlot::new();

/// Process-global slot for the host's *generic* invoker. Set via

/// [`AzApp_setGenericInvoker`]. Used as a fallback in macro-generated

/// per-kind thunks when the per-kind invoker is not registered, and as

/// the **only** dispatch path for user-defined custom callback kinds in

/// libffi-restricted hosts (Lua, PHP, koffi, …) that can't easily ship

/// an upstream `impl_managed_callback!` invocation.

///

/// Signature on the host side:

///

/// ```c

/// typedef void (*AzGenericInvoker)(

///     uint64_t           handle,    /* host-handle id from the RefAny ctx */

///     const char*        kind,      /* null-terminated wrapper name */

///     const void* const* args,      /* array of pointers, one per arg, in declared order */

///     size_t             n_args,    /* args[] length */

///     void*              ret        /* where to write the return value (kind-specific size) */

/// );

/// extern void AzApp_setGenericInvoker(AzGenericInvoker);

/// ```

///

/// The args array carries pointers into the framework's by-value frame

/// — host code must not retain them past the call. The host decides what

/// to do per kind from the `kind` string (which matches the wrapper

/// struct name, e.g. `"Callback"`, `"LayoutCallback"`,

/// `"ButtonOnClickCallback"`).

pub static GENERIC_INVOKER: InvokerSlot = InvokerSlot::new();

/// Type alias for the generic invoker callable. Hosts cast a libffi

/// closure to this signature once at module load.

pub type AzGenericInvoker = extern "C" fn(

    handle: u64,

    kind: *const core::ffi::c_char,

    args: *const *const c_void,

    n_args: usize,

    ret: *mut c_void,

);

/// Register the generic invoker for user-defined custom callback kinds

/// or as a fallback for per-kind dispatch. Called once at module load;

/// subsequent registrations replace the previous slot.

///

/// Safety: `invoker` must be a valid [`AzGenericInvoker`] function

/// pointer for the lifetime of any callback that might be dispatched

/// through it — typically the whole process.

#[no_mangle]

/// Register the host-language releaser. Hosts call this once at module

/// load time; subsequent registrations replace the previous slot.

///

/// `releaser` will be invoked as `releaser(id)` whenever a host-handle

/// `RefAny` (the kind built by [`host_handle_to_refany`]) drops its last

/// reference. The host should remove `id` from whatever id→callable table

/// it maintains.

///

/// Safety: `releaser` must be a valid `extern "C" fn(u64)` for the lifetime

/// of any host-handle [`RefAny`] that may still be alive — typically the

/// whole process. Passing a function pointer that becomes invalid (e.g.,

/// from an unloaded library) without first re-registering will cause a

/// crash on the next collection.

#[no_mangle]

/// Destructor stamped into every host-handle [`RefAny`]. Reads the payload's

/// `id` and forwards it to the registered releaser; if no releaser has been

/// registered (e.g., host hasn't initialized yet, or this is a release-build

/// dll loaded by a non-managed-FFI consumer) the destructor is a no-op so

/// the C side doesn't crash.

    // SAFETY: the destructor only runs for RefAnys built via

    // host_handle_to_refany, whose payload type is HostHandlePayload.

    // SAFETY: HOST_HANDLE_RELEASER only ever holds a value that came from

    // `releaser as usize` in `AzApp_setHostHandleReleaser`, where `releaser`

    // is an `extern "C" fn(u64)`.

/// Wrap a host-language `u64` handle in a [`RefAny`] suitable for storing

/// in a callback wrapper's `ctx` field.

///

/// The returned RefAny's destructor calls back through the registered

/// host releaser when the last clone is dropped, giving the host an

/// opportunity to release whatever its `id` was keying.

        AZ_HOST_HANDLE_RTTI_ID,

        0,

        0,

    )

/// Read the host-language id back out of a [`RefAny`] previously created

/// via [`host_handle_to_refany`]. Returns `None` for any other RefAny, so

/// a static thunk that mistakenly receives a non-host-handle ctx falls

/// back to the kind's default value rather than reading random bytes.

    // SAFETY: type-id check above guarantees the payload was a HostHandlePayload.

/// C-ABI: build a [`RefAny`] wrapping a host-language id. Lets managed-FFI

/// bindings use the same machinery for user data that callbacks already use

/// — one releaser, one id-keyed table, one lifetime story.

///

/// The returned RefAny's destructor fires the releaser registered via

/// [`AzApp_setHostHandleReleaser`] once the last clone drops, so the host

/// can drop its `id → value` entry.

#[no_mangle]

/// C-ABI: read the host-language id from a [`RefAny`] previously built via

/// [`AzRefAny_newHostHandle`] (or any other host-handle constructor).

///

/// Returns `0` if `refany` is null or wasn't a host handle. Host bindings

/// must reserve `0` as "no value" — [`host_handle_to_refany`] never produces

/// `0` if the host's id allocator starts at `1` (the convention used by

/// every binding in this repo).

#[no_mangle]

    // SAFETY: caller's responsibility per `*const` signature.

/// Macro that expands to the per-callback-kind boilerplate: a static thunk

/// (compiled into libazul) that the framework calls with by-value args, a

/// `<Wrapper>::create_from_host_handle(u64)` constructor, and an

/// `AzApp_set<Kind>Invoker` setter the host calls once at module load.

///

/// All identifiers are passed in explicitly so we don't need a proc-macro

/// dependency just to concatenate idents. Codegen emits invocations of this

/// macro from `ir.callback_typedefs`.

///

/// Caller responsibilities:

///

/// - The wrapper type must have public fields `cb: <typedef>` and

///   `ctx: OptionRefAny` — that's the standard shape every callback wrapper

///   in the framework already follows.

/// - `info_ty` must expose a `.get_ctx() -> OptionRefAny` method (also

///   standard for `*CallbackInfo` types).

/// - `default_ret` is returned when:

///   - the framework invokes the thunk with `OptionRefAny::None` ctx

///     (host called the typedef directly without going through this path),

///   - the ctx isn't a host-handle (host registered the wrapper but the

///     ctx came from somewhere else),

///   - or no invoker has been registered yet for this kind. Pick a value

///     that can't be confused with a "real" return — typically the kind's

///     "do nothing" / "empty body" default.

#[macro_export]

macro_rules! impl_managed_callback {

    // Form 1: simple two-argument callbacks `(RefAny, info) -> ret` —

    // matches `Callback`, `LayoutCallback`, `ButtonOnClickCallback`,

    // and the bulk of widget event callbacks. Identical to the

    // extras-form below with an empty extra-args list.

    (

        wrapper:        $wrapper:ty,

        info_ty:        $info_ty:ty,

        return_ty:      $ret:ty,

        default_ret:    $default:expr,

        invoker_static: $invoker_static:ident,

        invoker_ty:     $invoker_ty:ident,

        thunk_fn:       $thunk_fn:ident,

        setter_fn:      $setter_fn:ident,

        from_handle_fn: $from_handle_fn:ident,

    ) => {

        $crate::impl_managed_callback! {

            wrapper:        $wrapper,

            info_ty:        $info_ty,

            return_ty:      $ret,

            default_ret:    $default,

            invoker_static: $invoker_static,

            invoker_ty:     $invoker_ty,

            thunk_fn:       $thunk_fn,

            setter_fn:      $setter_fn,

            from_handle_fn: $from_handle_fn,

            extra_args:     [],

        }

    };

    // Form 2: callbacks that take additional state after info — e.g.

    // `CheckBoxOnToggleCallback(RefAny, CallbackInfo, CheckBoxState)`.

    // The extras list is forwarded by reference into the host invoker

    // so libffi-style runtimes never have to handle aggregate-by-value

    // returns OR aggregate-by-value args.

    (

        wrapper:        $wrapper:ty,

        info_ty:        $info_ty:ty,

        return_ty:      $ret:ty,

        default_ret:    $default:expr,

        invoker_static: $invoker_static:ident,

        invoker_ty:     $invoker_ty:ident,

        thunk_fn:       $thunk_fn:ident,

        setter_fn:      $setter_fn:ident,

        from_handle_fn: $from_handle_fn:ident,

        extra_args:     [ $( $extra_name:ident : $extra_ty:ty ),* $(,)? ] $(,)?

    ) => {

        /// Process-global slot for this callback kind's host-side invoker.

        pub static $invoker_static: $crate::host_invoker::InvokerSlot =

            $crate::host_invoker::InvokerSlot::new();

        /// Pointer-arg variant of this callback kind's typedef.

        ///

        /// The host's libffi closure casts to this signature (which all

        /// managed-FFI runtimes can handle — args and return are passed

        /// by pointer, no aggregate-by-value anywhere). The static thunk

        /// in libazul does the by-value plumbing on the C ABI side.

        ///

        /// LuaJIT FFI in particular cannot return aggregates larger than

        /// 8 bytes from a callback, so we use an out-pointer for the

        /// return value uniformly across kinds — even for `Update` which

        /// would fit in a register, so the macro stays homogeneous.

        pub type $invoker_ty = extern "C" fn(

            handle: u64,

            data: *const $crate::refany::RefAny,

            info: *const $info_ty,

            $( $extra_name : *const $extra_ty , )*

            out: *mut $ret,

        );

        /// Register the host-side invoker for this callback kind.

        #[no_mangle]

        /// Static thunk compiled into libazul. The framework calls this

        /// with by-value args; we extract the host handle from `info.ctx`,

        /// allocate space for the return value on our stack, and forward

        /// pointers to the registered invoker.

                        None => return $default,

                    }

                }

                _ => return $default,

            };

                // Per-kind invoker not registered — fall back to the

                // generic invoker for hosts that wired up only the

                // single `AzApp_setGenericInvoker` slot (or for custom

                // user-defined kinds emitted by a downstream

                // `impl_managed_callback!` whose host hasn't shipped a

                // per-kind invoker setter yet).

                    return $default;

                // SAFETY: GENERIC_INVOKER only ever holds an address that

                // came from `invoker as usize` in `AzApp_setGenericInvoker`,

                // whose parameter is typed as `AzGenericInvoker`.

                // Wrapper name as a null-terminated C string. `stringify!`

                // expands `$wrapper:ty` to e.g. `Callback`,

                // `ButtonOnClickCallback`, etc. — matching what the host's

                // dispatch table keys on.

                const KIND_STR: &str = concat!(stringify!($wrapper), "\0");

                // Build the args array: pointers to each by-value frame

                // arg, in declared order (data, info, extras…). Lifetime

                // is the scope of this thunk; the host MUST NOT retain

                // these pointers past the call. Array size is inferred

                // (2 base args + however many extras the macro forwarded).

            // SAFETY: $invoker_static only ever holds a value that came from

            // `invoker as usize` in `$setter_fn`, where `invoker` has type

            // `$invoker_ty`.

            // Pre-fill `out` with the kind's default so a host that fails

            // to write to the out-pointer (e.g. a buggy invoker) leaves us

            // with a sane value rather than uninitialized memory.

        impl $wrapper {

            /// Build a wrapper whose `cb` is the static thunk above and

            /// whose `ctx` carries the host's `u64` handle. The host

            /// language is responsible for keeping its id→callable table

            /// in sync with the releaser registered via

            /// `AzApp_setHostHandleReleaser`.

        }

        /// C-ABI export wrapping `<Wrapper>::create_from_host_handle`.

        #[no_mangle]

    };

}