Module interoptopus::patterns
source · Expand description
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 aservice
to a Pythonclass
. -
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 char
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§
- Helper to ensure the bindings match the used DLL.
- Useful when
extern "C" fn()
delegate types give compile errors. - Like a regular
Option
but FFI safe. - Additional support for primitives like
bool
. - For return enums with defined
Ok
variants; may translate to exceptions if not met. - Bundles function with common receiver into a service or ‘class’ in object oriented languages.
- Like a regular
&[T]
and&mut [T]
but FFI safe. - Raw
*const char
pointer on C-level but ASCIIstring
like in languages that support it.
Enums§
- A pattern on a library level, usually involving both methods and types.
- A pattern on a type level.