Python3 API

Installation

The API is available via pypi: pip install metaffi

MetaFFIRuntime Class

MetaFFIRuntime is a class that provides a simple and easy FFI framework to connect Python with other languages. Pass to the constructor the runtime plugin you wish to load into the process (e.g. go, openjdk), and call load_runtime_plugin to load the runtime.

Once the runtime is loaded, use load_module to load the module and receive and instance of MetaFFIModule.

Methods

__init__(runtime_plugin: str)

Constructor specifies the requested runtime plugin to use

Parameters:

  • runtime_plugin: The name of the runtime plugin to use

load_runtime_plugin()

Loads the runtime of the plugin.

release_runtime_plugin()

Releases the loaded runtime. After calling this function, and loaded entity must not be used.

load_module(module_path: str)->MetaFFIModule

Loads a foreign module from a given. It returns a MetaFFIModule object that represents the foreign module.

The modulePath might contain multiple modules (for cases like dependencies). A runtime plugin specifies in its documentation what it expects.

Parameters:

  • module_path - Path to the module(s) to load

Return:

  • Instance of MetaFFIModule representing the foreign module

MetaFFIModule Class

The MetaFFIModule class provides the load method, which loads a foreign entity and returns it as a Callable.

The class should not be created directly, but using the MetaFFIRuntime.load_module function.

Methods

__init__(runtime, xllr, module_path)

The constructor method for the MetaFFIModule class. It initializes the instance with the given attributes.

Parameters:

  • runtime: A MetaFFIRuntime object that specifies the runtime plugin for the module.
  • xllr: An XllrWrapper object that provides the interface to XLLR (Cross-Language Link Runtime).
  • module_path: A string that contains the path to the module file.

load_entity(entity_path: str, params_metaffi_types: List[metaffi_type_info], retval_metaffi_types: List[metaffi_type_info]) -> Callable[..., Tuple[Any, ...]]

The load method for the MetaFFIModule class loads a foreign entity from the module and returns a Callable that can be used to invoke the foreign entity from another language. If it Callable calls a Method or a Field of an object, the $1^{st}$ parameter is an instance of the object.

The load method receives a entity path telling the runtime plugin the location of the entity inside the module.

The method should also pass a list of MetaFFI Types, specifying the type of the parameters and return values. metaffi_type_info type is created by new_metaffi_type_info function.

In case there are no parameters or return values, pass None or empty list.

Parameters:

  • entity_path: A string that contains the path to the function within the module.
  • params_metaffi_types: A list of metaffi_type_info objects that specify the parameter types for the function.
  • retval_metaffi_types: A list of metaffi_type_info objects that specify the return value types for the function.

Returns:

  • A Callable that accepts the number of parameters defiend in params_metaffi_types and their expected corresponding types. The function returns the number of expected return values and their corresponding types.

    In case of an error during the call, or an error in the foreign entity, the callable raises an exception containing the error message.

Callback

make_metaffi_callable(f: Callable) -> Callable

The function wraps the given callable f, and returns a cross-language Callable. The returned Callable can be passed to other languages.

Parameter:

  • f: a Python3 callable

Return:

  • MetaFFI-enabled Callable

MetaFFI Types In Python3

MetaFFI Type Python3
metaffi_float64_type float
metaffi_float32_type float
metaffi_int8_type int
metaffi_int16_type int
metaffi_int32_type int
metaffi_int64_type int
metaffi_uint8_type int
metaffi_uint16_type int
metaffi_uint32_type int
metaffi_uint64_type int
metaffi_bool_type bool
metaffi_char8_type bytes
metaffi_char16_type bytes
metaffi_char32_type bytes
metaffi_string8_type str
metaffi_string16_type str
metaffi_string32_type str
metaffi_handle_type metaffi_handle
metaffi_any_type Any
metaffi_null_type None
metaffi_callable_type Callable
(returned by make_callable)
metaffi_float64_array_type list
metaffi_float32_array_type list
metaffi_int8_array_type list
metaffi_int16_array_type list
metaffi_int32_array_type list
metaffi_int64_array_type list
metaffi_uint8_array_type list
metaffi_uint16_array_type list
metaffi_uint32_array_type list
metaffi_uint64_array_type list
metaffi_bool_array_type list
metaffi_char8_array_type list
metaffi_string8_array_type list
metaffi_string16_array_type list
metaffi_string32_array_type list
metaffi_any_array_type list
metaffi_handle_array_type list
metaffi_size_array_type list