Struct Opaque

pub struct Opaque<T> { /* private fields */ }

Stores an opaque value.

Opaque<T> is meant to be used with FFI objects that are never interpreted by Rust code.

It is used to wrap structs from the C side, like for example Opaque<bindings::mutex>. It gets rid of all the usual assumptions that Rust has for a value:

• The value is allowed to be uninitialized (for example have invalid bit patterns: 3 for a bool).
• The value is allowed to be mutated, when a &Opaque<T> exists on the Rust side.
• No uniqueness for mutable references: it is fine to have multiple &mut Opaque<T> point to the same value.
• The value is not allowed to be shared with other threads (i.e. it is !Sync).

This has to be used for all values that the C side has access to, because it can’t be ensured that the C side is adhering to the usual constraints that Rust needs.

Using Opaque<T> allows to continue to use references on the Rust side even for values shared with C.

Examples

use kernel::types::Opaque;

// `foo.val` is assumed to be handled on the C side, so we use `Opaque` to wrap it.
pub struct Foo {
    foo: Opaque<bindings::Foo>,
}

impl Foo {
    pub fn get_val(&self) -> u8 {
        let ptr = Opaque::get(&self.foo);

        // SAFETY: `Self` is valid from C side.
        unsafe { (*ptr).val }
    }
}

// Create an instance of `Foo` with the `Opaque` wrapper.
let foo = Foo {
    foo: Opaque::new(bindings::Foo { val: 0xdb }),
};

assert_eq!(foo.get_val(), 0xdb);

Implementations

impl<T> Opaque<T>

pub const fn new(value: T) -> Self

Creates a new opaque value.

pub const fn uninit() -> Self

Creates an uninitialised value.

pub fn ffi_init(init_func: impl FnOnce(*mut T)) -> impl PinInit<Self>

Creates a pin-initializer from the given initializer closure.

The returned initializer calls the given closure with the pointer to the inner T of this Opaque. Since this memory is uninitialized, the closure is not allowed to read from it.

This function is safe, because the T inside of an Opaque is allowed to be uninitialized. Additionally, access to the inner T requires unsafe, so the caller needs to verify at that point that the inner value is valid.

pub fn try_ffi_init<E>( init_func: impl FnOnce(*mut T) -> Result<(), E>, ) -> impl PinInit<Self, E>

Creates a fallible pin-initializer from the given initializer closure.

The returned initializer calls the given closure with the pointer to the inner T of this Opaque. Since this memory is uninitialized, the closure is not allowed to read from it.

This function is safe, because the T inside of an Opaque is allowed to be uninitialized. Additionally, access to the inner T requires unsafe, so the caller needs to verify at that point that the inner value is valid.

pub const fn get(&self) -> *mut T

Returns a raw pointer to the opaque data.

pub const fn raw_get(this: *const Self) -> *mut T

Gets the value behind this.

This function is useful to get access to the value without creating intermediate references.

Trait Implementations

impl<T> Zeroable for Opaque<T>