Struct Userdata

pub struct Userdata<T: 'static>(/* private fields */);

Type-erased user data.

Use this to wrap arbitrary data into a structure which may be passed via a c_void pointer to an external library. Later, when this extern callback is run with that data, you may unwrap it and can thus access the original data.

The implementation uses associated methods:

• Userdata::prepare() to wrap the user data and get a c_void pointer
• Userdata::peek_at() to unwrap the c_void pointer and get the user data
• Userdata::consume() to clean up the c_void pointer and get the user data

Each prepare() must be paired with exactly one consume() to release the data held by the wrapper structure. peek_at() must only be called in-between and the lifetime of the returned reference is not allowed to extend past the next call to either peek_at() or consume().

Examples

use open62541::Userdata;

// Turn user data into type-erased void pointer for FFI.
let raw_data: *mut c_void = Userdata::<u32>::prepare(0);

// Use type-erased pointer to get/manipulate user data.
unsafe {
    let userdata = Userdata::<u32>::peek_at(raw_data);
    assert_eq!(*userdata, 0);
    *userdata = 123;
}

// Unwrap data. Clean up resources held by pointer.
let userdata = unsafe {
    Userdata::<u32>::consume(raw_data)
};

// Got user data. `raw_data` is no longer valid.
assert_eq!(userdata, 123);

Implementations

impl<T> Userdata<T>

pub fn prepare(userdata: T) -> *mut c_void

Wraps user data.

This allocates memory. To prevent memory leaks, make sure to call consume() on the returned pointer exactly once.

pub fn prepare_sentinel(userdata: T) -> UserdataSentinel<T>

Wraps user data and returns sentinel.

This uses prepare() but wraps the resulting pointer in UserdataSentinel to make sure that it is cleaned up when the sentinel is dropped. This is useful when the recipient of the raw pointer does not become the owner, i.e. does not clean up the user data by itself.

Use UserdataSentinel::as_ptr() to get the pointer from the sentinel.

pub unsafe fn peek_at<'a>(data: *mut c_void) -> &'a mut T

Unwraps c_void pointer to access data.

Safety

The given pointer must have been returned from prepare(), using the same value type T. It must not have been given to consume() yet.

The lifetime of the returned reference is not allowed to extend past the next call to either peek_at() or consume() and must not outlive the lifetime of T itself. (In case the user data has been wrapped into a UserdataSentinel, the sentinel must still be alive.)

pub unsafe fn consume(data: *mut c_void) -> T

Unwraps c_void pointer and returns owned data.

Safety

The given pointer must have been returned from prepare(), using the same value type T. It must not have been given to consume() yet, nor wrapped in a UserdataSentinel (the user data is consumed automatically when the sentinel is being dropped).

Trait Implementations

impl<T: Debug + 'static> Debug for Userdata<T>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.