Crate fn_ptr

Crate fn_ptr 

Source
Expand description

fn-ptr is a utility crate for introspecting and rewriting function pointer types at compile time.

It implements FnPtr for all function-pointer types:

  • fn(T) -> U
  • unsafe fn(T) -> U
  • extern "C-unwind" fn(T)
  • unsafe extern "sysv64" fn() -> i32

§Function pointer metadata

FnPtr exposes metadata as associated types/consts.

use fn_ptr::{FnPtr, AbiValue};

type F = extern "C" fn(i32, i32) -> i32;
assert_eq!(<F as FnPtr>::ARITY, 2);
assert_eq!(<F as FnPtr>::IS_SAFE, true);
assert_eq!(<F as FnPtr>::IS_EXTERN, true);
assert_eq!(<F as FnPtr>::ABI, AbiValue::C { unwind: false });

Ergonomic const functions are provided as well:

const A: usize = fn_ptr::arity::<F>();
const SAFE: bool = fn_ptr::is_safe::<F>();
const EXT: bool = fn_ptr::is_extern::<F>();
const abi: AbiValue = fn_ptr::abi::<F>();

§Rewriting function-pointer types

The crate provides type-level rewriting via traits:

§Type-level transformations

The macros compute a new function-pointer type while preserving everything else.

use fn_ptr::{with_abi, with_safety, with_output, with_args};

type F = extern "C" fn(i32) -> i32;

type F1 = with_abi!("sysv64", F);   // extern "sysv64" fn(i32) -> i32
type F2 = with_safety!(unsafe, F);  // unsafe extern "C" fn(i32) -> i32
type F3 = with_output!(u64, F);     // extern "C" fn(i32) -> u64
type F4 = with_args!((u8, u16), F); // extern "C" fn(u8, u16) -> i32

§Value-level casts

The same transformations exist at the value level via methods on FnPtr. These casts are only transmuting and do not the actual underlying function.

use fn_ptr::{FnPtr, abi};

let f: fn(i32, i32) -> i32 = |a, b| a + b;

// safety
let u: unsafe fn(i32, i32) -> i32 = f.as_unsafe();
let f2: fn(i32, i32) -> i32 = unsafe { u.as_safe() };

// abi
let c: extern "C" fn(i32, i32) -> i32 = unsafe { f.with_abi::<abi!("C")>() };

// output
let out: fn(i32, i32) -> u64 = unsafe { f.with_output::<u64>() };

// args
let args: fn(u8, u16) -> i32 = unsafe { f.with_args::<(u8, u16)>() };

§How it works

Implementations are generated by a large macro. The rewrite macros are thin wrappers over the traits WithAbi, WithSafety, WithOutput, WithArgs (and the corresponding *Impl helper traits).

Re-exports§

pub use safety::Safety;
pub use abi::Abi;
pub use arity::Arity;

Modules§

abi
Module containing abi related marker types and traits.
arity
Module containing arity related marker types and traits.
prelude
Prelude for this crate.
safety
Module containing safety related marker types and traits.

Macros§

abi
Macro to convert an abi string to the corresponding Abi marker type.
arity
Macro to convert an integral number to the corresponding Arity marker type.
make_safe
Construct a function-pointer type identical to the given one but safe.
make_unsafe
Construct a function-pointer type identical to the given one but unsafe.
safety
Macro to convert a safety token (safe or unsafe) or a boolean literal to the corresponding Safety marker type.
with_abi
Construct a function-pointer type identical to the given one but using the specified abi.
with_args
Construct a function-pointer type identical to the given one but using the specified argument tuple type.
with_output
Construct a function-pointer type identical to the given one but using the specified return type.
with_safety
Construct a function-pointer type identical to the given one but using the specified safety.

Structs§

OpaqueFn
A struct representing an opaque function.

Enums§

AbiValue
The abi or calling convention of a function pointer.

Traits§

AsSafe
Helper trait to compute the safe version of a function pointer type while preserving its abi, arguments and return type. Equivalent to WithSafety<Safe>.
AsUnsafe
Helper trait to compute the unsafe version of a function pointer type while preserving arity, abi and signature.
BuildFn
Constructs a function-pointer type from its components.
FnPtr
Marker trait for all function pointers.
SafeFnPtr
Marker trait for all callable safe function pointer types (fn / extern fn).
StaticFnPtr
Marker trait for all static function pointer types. The return type and all parameter types have to be 'static.
Tuple
A trait implemented for all tuple types up to arity 6 (or 12 with feature max-arity-12).
UnsafeFnPtr
Marker trait for all callable unsafe function pointer types (unsafe fn / unsafe extern fn).
WithAbi
Helper trait to change the abi of a function pointer type while preserving its safety, arguments and return type.
WithAbiImpl
Helper trait used by WithAbi (use it instead). This trait is required to allow FnPtr to be a subtrait of WithAbi, which eliminates the need for a type bound when using a fixed abi marker. Using WithAbi directly would result in a cyclic supertrait error.
WithArgs
Helper trait to change the argument types of a function pointer type while preserving its safety, abi and return type.
WithArgsImpl
Helper trait used by WithArgs (use it instead). This trait is required to allow FnPtr to be a subtrait of WithArgs, which eliminates the need for a type bound when using a fixed args type. Using WithArgs directly would result in a cyclic supertrait error.
WithOutput
Helper trait to change the return type of a function pointer type while preserving its safety, abi and arguments.
WithOutputImpl
Helper trait used by WithOutput (use it instead). This trait is required to allow FnPtr to be a subtrait of WithOutput, which eliminates the need for a type bound when using a fixed output type. Using WithOutput directly would result in a cyclic supertrait error.
WithSafety
Helper trait to change the safety of a function pointer type while preserving its abi, arguments and return type.
WithSafetyImpl
Helper trait used by WithSafety (use it instead). This trait is required to allow FnPtr to be a subtrait of WithSafety, which eliminates the need for a type bound when using a fixed safety marker. Using WithSafety directly would result in a cyclic supertrait error.

Functions§

abi
Returns the abi of the function pointer.
arity
Returns the number of arguments of a function pointer type.
is_extern
Returns true if the function pointer uses an external abi.
is_safe
Returns true for safe function pointers (fn).
is_unsafe
Returns true for unsafe function pointers (unsafe fn).

Type Aliases§

UntypedFnPtr
Type alias for a raw untyped function pointer.