Module interoptopus::patterns

Optional types that translate to binding with better semantics in languages supporting them.

Patterns are purely optional. If you want to use a certain pattern in your bindings you generally define one or more functions that use some of the types contained in this module.

Backends which support a pattern will then generate additional language-specific helpers and bindings for it. In any case, regardless whether a pattern is supported by a backend or not, fallback bindings will be available.

Pattern Usage

Unless otherwise stated patterns are used by, well, using them in signatures. For example, instead of making x a type *const u8 (or similar) in the following print function:

#[ffi_function]
#[no_mangle]
pub extern "C" fn print_ptr(x: *const u8) {
   // Write unsafe code to convert `x
}

you would instead accept an AsciiPointer:

#[ffi_function]
#[no_mangle]
pub extern "C" fn print_ascii(x: AsciiPointer) {
   // Call `x.as_str()` and handle Result
}

This has the added benefit that any backend supporting a specific pattern will also generate more idiomatic code in the binding. In the example above, C# might emit a ref ubyte or IntPtr type for the print_ptr, but will use a correctly marshalled string type for print_ascii.

Pattern Backend Support

Patterns are exclusively designed on top of existing, C-compatible functions and types. That means a backend will handle a pattern in one of three ways:

• The pattern is supported and the backend will generate the raw, underlying type and / or a language-specific abstraction that safely and conveniently handles it. Examples include converting an AsciiPointer to a C# string, or a service to a Python class.

• The pattern is not supported and will be omitted, if the pattern was merely an aggregate of existing items. Examples include the service pattern in C which will not be emitted. However, this will not pose a problem as all constituent types and methods (functions) are still available as raw bindings.

• The pattern is not supported and will be replaced with a fallback type. Examples include the AsciiPointer which will become a regular *const u8 in C.

In other words, regardless of which pattern was used, the involved methods and types will always be accessible from any language.

Status

Some patterns have seen more testing (and documentation) than others. The ones marked ^🚧 should be considered particularly work-in-progress.

Modules

api_guard

Helper to ensure the bindings match the used DLL.

callbacks

Useful when extern "C" fn() delegate types give compile errors.

option

Like a regular Option but FFI safe.

primitives

Additional support for primitives like bool.

result

For return enums with defined Ok variants; may translate to exceptions if not met.

service

Bundles function with common receiver into a service or ‘class’ in object oriented languages.

slice

Like a regular &[T] and &mut [T] but FFI safe.

string

Raw *const char pointer on C-level but ASCII string like in languages that support it.

Enums

LibraryPattern

A pattern on a library level, usually involving both methods and types.

TypePattern

A pattern on a type level.