Module interoptopus::patterns [−][src]
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 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
Helpers for API loading patterns as described in this blog post.π§
Defines a helper function ensuring the bindings match the used DLL.
Raw *const char
pointer on C-level but ASCII string
like in languages that support it.
Useful when extern "C" fn()
delegate types give compile errors.
Like a regular Option
but FFI safe.
Additional support for primitives like bool
.
Bundles function with common receiver into a class
or service in object oriented languages.π§
Like a regular &[T]
and &mut [T]
but FFI safe.
For return enums with defined Ok
variants, translating to exceptions if not met.
Enums
A pattern on a library level, usually involving both methods and types.
A pattern on a type level.