ark-api-ffi 0.17.0-pre.15

define_api_id!(0x8756_3a19_6243_4366, "module-run-v0");

use bytemuck::CheckedBitPattern;
use bytemuck::NoUninit;

use crate::FFIResult;

pub type RequestHandle = u64;
pub type FunctionHandle = u64;

#[repr(C)]
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, NoUninit, CheckedBitPattern)]
pub struct IsReady {
    pub is_ready: bool,
    pub _pad: [u8; 3],
    pub size: u32,
}

#[ark_api_macros::ark_bindgen(imports = "ark-module-run-v0")]
mod module_run {
    use super::*;

    /// Source module for a function
    #[derive(Copy, Clone, Debug, Hash, Eq, PartialEq)]
    #[repr(u32)]
    pub enum FunctionSource {
        /// Launch a function in the module itself
        OwnModule = 0,
        /// Launch a function from a separate named module
        NamedModule = 1,
    }

    extern "C" {
        pub fn create_function(
            fn_type: FunctionSource,
            fn_module: &str,
            fn_name: &str,
        ) -> FFIResult<FunctionHandle>;

        pub fn remove_function(handle: FunctionHandle) -> FFIResult<()>;

        /// Launch a module in a blocking/synchronous manner.
        ///
        /// This will block until the execution of the module is done.
        /// Which guarantees that `is_ready` will return that it is ready directly after this.
        ///
        /// # Returns
        ///
        /// These _may_ be returned, but the host can also choose to return success on any launch
        /// and have `retrieve` return the error codes
        /// - [`crate::ErrorCode::Success`] - if module was successfully launched
        /// - [`crate::ErrorCode::NotFound`] - if the module function was not found
        /// - [`crate::ErrorCode::InternalError`] - something else went wrong during launch
        pub fn blocking_launch(fn_handle: FunctionHandle, input: &[u8])
            -> FFIResult<RequestHandle>;

        /// Launch a module asynchronously.
        ///
        /// This will launch the module in the background and one have to poll `is_ready` to see when the request completes
        ///
        /// # Returns
        ///
        /// These _may_ be returned, but the host can also choose to return success on any launch
        /// and have `retrieve` return the error codes
        ///
        /// - [`crate::ErrorCode::Success`] - if module was successfully launched
        /// - [`crate::ErrorCode::NotFound`] - if the module function was not found
        /// - [`crate::ErrorCode::InternalError`] - something else went wrong during launch
        pub fn launch(fn_handle: FunctionHandle, input: &[u8]) -> FFIResult<RequestHandle>;

        /// Checks if the results of a launched module is ready
        pub fn is_ready(handle: RequestHandle) -> FFIResult<IsReady>;

        /// Retrieve the resulting output buffer from a request that is ready.
        ///
        /// This should only be called once `is_ready` on the request is true
        ///
        /// # Returns
        /// - [`crate::ErrorCode::Success`] - if results were successfully retrieved
        /// - [`crate::ErrorCode::InvalidArguments`] - if any of the parameters are invalid
        /// - [`crate::ErrorCode::Unavailable`] - if the handle is valid but the results are not available yet
        pub fn retrieve(handle: RequestHandle, out_buffer: &mut [u8]) -> FFIResult<()>;
    }
}

pub use module_run::*;