winmmf_ffi/

lib.rs

//! # An FFI interface for WinMMF
//!
//! The recommended way of working with this interface is to call [`open`] (or [`new`]) and then immediately [`read`]
//! with an explicit count of 0. Reuse the pointer provided for all subsequent reads by calling [`read_buf`], and then
//! freeing it with [`free_result`], most likely with other teardown and exit steps for your program. Alternatively, you
//! could just bring your own pointers. Just make sure they're all valid.
//!
//! If the lifetime for any MMFs should be `&'static` or longer than the execution context (e.g. you only `open` MMFs
//! created by a system service), it's possible to leave cleanup to the OS. No guarantees are made if or when that
//! happens, other than that cleanup will be done between program exit and system shutdown. If nobody is using the MMF
//! anymore, and all relevant programs have finished their `main` function (regardless of exit status), the system
//! should free up lingering handles with no active processes before erroring on the resource limit getting hit.
//!
//! During the lifetime of your program, if you decide to close any MMFs, they will be ejected from the inner
//! collection. Should you need to reopen one, and you're sure other handles to it yet live in the system, you can open
//! it anew and your data should be there unchanged.
//! Should you forget to free a pointer, use [`free_raw`] at your own risk.
//!
//! If you need to use several MMFs at once in your code, you can. Beware that tracking their indices is entirely at
//! your own risk though. Should you know which indices you need, and do you plan to use the same one for extended
//! periods of time, then select one for use with [`select_default`].

use std::{
    ffi::{c_char, CStr},
    num::NonZeroUsize,
    ptr::null_mut,
    sync::{
        atomic::{AtomicUsize, Ordering},
        Mutex, OnceLock,
    },
};
pub use winmmf::Namespace as ValidNamespaces;
use winmmf::*;

/// You didn't think I was going to keep _this_ long a type unaliased right?
type MMFWrapper<'a> = Mutex<Vec<MemoryMappedFile<RWLock<'a>>>>;

/// A wrapper to hold any MMFs that are produced during the application lifetime.
static MMFS: OnceLock<MMFWrapper> = OnceLock::new();
/// Currently selected default MMF to operate on. Counting starts from 1.
static CURRENT: AtomicUsize = AtomicUsize::new(0);

/// Lazy wrapper to use when ensuring initialization
fn _init<'a>(cap: usize) -> MMFWrapper<'a> {
    Mutex::new(Vec::with_capacity(cap))
}

/// Initialize the inner object to hold MMF instances.
///
/// Returns: 0 on success, -1 on error.
/// The only conceivable error state would be calling this function more than once.
#[unsafe(no_mangle)]
pub extern "system" fn init(count: Option<NonZeroUsize>) -> isize {
    let cap = count.map(|c| c.get()).unwrap_or(1);
    MMFS.set(_init(cap)).map(|_| 0).unwrap_or(-1)
}

/// Open an existing MMF and push it into the list, returning its index or an error indicator.
///
/// There are several possible return values here, these are:
///
/// - Positive integers: the new index
/// - -1: Size is 0
/// - -2: The name is invalid UTF-8
/// - -3: The namespace is invalid
/// - -4: The MMF could not be opened
/// - -5: The MMF could not be stored
#[unsafe(no_mangle)]
pub extern "system" fn open(
    size: Option<NonZeroUsize>,
    name: *const c_char,
    namespace: u8,
    large_pages: Option<&bool>,
) -> isize {
    match (
        size,
        unsafe { CStr::from_ptr(name).to_str().ok().map(|s| (s.len() > 0).then(|| s.to_owned())).flatten() },
        namespace.try_into(),
    ) {
        (None, _, _) => -1,
        (_, None, _) => -2,
        (_, _, Err(_)) => -3,
        (Some(size), Some(namestr), Ok(ns)) => {
            if let Ok(mapped) = MemoryMappedFile::open(size, namestr, ns, false, large_pages.cloned()) {
                MMFS.get_or_init(|| _init(1))
                    .lock()
                    .map(|mut inner| {
                        inner.push(mapped);
                        let idx = inner.len() - 1;
                        CURRENT.store(idx + 1, Ordering::Relaxed);
                        idx as isize
                    })
                    .unwrap_or(-5)
            } else {
                -4
            }
        }
    }
}

/// Create a new MMF and push it into the list, returning the new index or an error indicator.
///
/// There are several possible return values here, these are:
///
/// - Positive integers: Success
/// - -1: Size is 0
/// - -2: The name is invalid UTF-8
/// - -3: The namespace is invalid
/// - -4: The MMF could not be opened
/// - -5: The MMF could not be stored
#[unsafe(no_mangle)]
pub extern "system" fn new(
    size: Option<NonZeroUsize>,
    name: *const c_char,
    namespace: u8,
    large_pages: Option<&bool>,
) -> isize {
    match (
        size,
        unsafe { CStr::from_ptr(name).to_str().ok().map(|s| (s.len() > 0).then(|| s.to_owned())).flatten() },
        namespace.try_into(),
    ) {
        (None, _, _) => -1,
        (_, None, _) => -2,
        (_, _, Err(_)) => -3,
        (Some(size), Some(namestr), Ok(ns)) => {
            if let Ok(mapped) = MemoryMappedFile::new(size, namestr, ns, large_pages.cloned()) {
                MMFS.get_or_init(|| _init(1))
                    .lock()
                    .map(|mut inner| {
                        inner.push(mapped);
                        let idx = inner.len() - 1;
                        CURRENT.store(idx + 1, Ordering::Relaxed);
                        idx as isize
                    })
                    .unwrap_or(-5)
            } else {
                -4
            }
        }
    }
}

/// Read `count` bytes from the MMF into the provided buffer.
///
/// It is up to the caller to ensure the buffer is large enough to hold at least `count` bytes. Passing in a buffer
/// smaller than `count` from Rust space is undefined behavior. This function _will_ make the assumption the buffer is
/// exactly `count` items long.
/// Return values are negative integers for errors, or 0 for success.
///
/// # Safety
/// Ensure `buff` is valid for at least `count` bytes and all will be well.
///
/// - -1: No MMFs opened yet
/// - -2: MMF is closed
/// - -3: MMF isn't initialized
/// - -4: ???
#[unsafe(no_mangle)]
pub unsafe extern "system" fn read_buf(mmf_idx: Option<NonZeroUsize>, count: usize, buff: *mut u8) -> isize {
    if buff.is_null() {
        return -4;
    }
    if count == 0 {
        return 0;
    }
    MMFS.get()
        .map(|inner| {
            inner
                .lock()
                .map(|inner| {
                    inner
                        .get(mmf_idx.map(|nsu| nsu.get()).unwrap_or_else(|| CURRENT.load(Ordering::Acquire) - 1))
                        .map(|mmf| {
                            mmf.read_to_raw(buff, count).map(|_| 0).unwrap_or_else(|e| match e {
                                Error::MMF_NotFound => -2,
                                Error::Uninitialized => -3,
                                _ => -4,
                            })
                        })
                        .unwrap_or(-1)
                })
                .unwrap_or(-4)
        })
        .unwrap_or(-1)
}

/// Read `count` bytes or all contents from the MMF and give back a pointer to the data.
///
/// The pointer produced from this function **must** be freed using [`free_result`], regardless of error state.
/// To this end, the returned pointer will _always_ have enough size behind it to fit the entire mapped view. Before
/// freeing it, this pointer may also be used with [read_buf] so you know you have a safe pointer to work with.
/// To further support this, passing a `count` of 0 returns a fresh buffer.
/// If you create more than one buffer, they should _all_ be handled with `free_result`. Failing to do so leaks memory.
///
/// If something went wrong, the data behind the pointer will be an error code, right padded with `0xFF` until the end
/// of the requested buffer. If no size is provided, the returned pointer will be the length of the current active MMF.
#[unsafe(no_mangle)]
pub extern "system" fn read(mmf_idx: Option<NonZeroUsize>, count: usize) -> *mut u8 {
    MMFS.get()
        .map(|inner| {
            inner
                .lock()
                .map(|inner| {
                    inner
                        .get(mmf_idx.map(|nsu| nsu.get()).unwrap_or_else(|| CURRENT.load(Ordering::Acquire) - 1))
                        .map(|mmf| {
                            if count == 0 {
                                let mut ret = vec![0; mmf.size()];
                                ret.shrink_to_fit();
                                let ptr = ret.as_mut_ptr();
                                std::mem::forget(ret);
                                ptr
                            } else {
                                let mut ret = Vec::new();
                                let ptr = ret.as_mut_ptr();

                                match mmf.read_to_buf(&mut ret, count) {
                                    Ok(_) => {
                                        std::mem::forget(ret);
                                        ptr
                                    } /* Becomes a pointer to the first */
                                    // element in the vec
                                    Err(e) => {
                                        let val = match e {
                                            Error::MMF_NotFound => -2_i8,
                                            Error::Uninitialized => -3_i8,
                                            _ => -4_i8,
                                        };
                                        ret = vec![0xFF; mmf.size()];
                                        ret[0] = val as u8;
                                        ret.shrink_to_fit();
                                        std::mem::forget(ret);
                                        ptr
                                    }
                                }
                            }
                        })
                        .unwrap_or(null_mut())
                })
                .unwrap_or(null_mut())
        })
        .unwrap_or(null_mut())
}

/// Free a pointer used for reading from an MMF by its index number.
///
/// # Safety
/// Do not pass pointers not received from this library. Doing so is UB by definition.
/// Null pointers will be silently ignored.
///
/// Mismatching pointers and their MMFs will leak memory. But because users tend to mess up, this function doesn't close
/// the MMF to prevent worse things from happening. Such as use after free and dangling references.
/// Using the pointer after passing it through this function is UB.
#[unsafe(no_mangle)]
pub unsafe extern "system" fn free_result(mmf_idx: Option<NonZeroUsize>, res: *mut u8) {
    if res.is_null() {
        return;
    }
    MMFS.get()
        .map(|inner| {
            inner
                .lock()
                .map(|inner| {
                    inner
                        .get(mmf_idx.map(|nsu| nsu.get()).unwrap_or_else(|| CURRENT.load(Ordering::Acquire) - 1))
                        .map(|mmf| unsafe { free_raw(res, mmf.size()) })
                        .unwrap_or(())
                })
                .unwrap_or(())
        })
        .unwrap_or(())
}

/// You had better know how big that thing is.
///
/// # Safety
///
/// If the provided size is incorrect, you might be leaking bytes (too small, mostly harmless) or you might be invoking
/// UB (too large, harmful to the universe). If you're just gambling the size, I hope you anger the Duolingo bird.
#[unsafe(no_mangle)]
pub unsafe extern "system" fn free_raw(res: *mut u8, size: usize) {
    drop(Vec::from_raw_parts(res, size, size))
}

/// Expose writing data as well. Slightly less complex for FFI purposes than reading.
///
/// # Safety
/// `data` must be at least `count` bytes long, or somebody's getting hurt.
///
/// Return values for this function are:
/// - 0: Write was successful!
/// - -1: Writing not allowed (readonly or closed)
/// - -2: Buffer is bigger than the MMF
/// - -3: Uninitialized
/// - -4: Read- or WriteLocked
/// - -5: Programmer issue
#[unsafe(no_mangle)]
pub unsafe extern "system" fn write(mmf_idx: Option<NonZeroUsize>, data: *mut u8, size: usize) -> isize {
    if data.is_null() {
        -5
    } else if size > 0 {
        MMFS.get()
            .map(|inner| {
                inner
                    .lock()
                    .map(|inner| {
                        inner
                            .get(mmf_idx.map(|nsu| nsu.get()).unwrap_or_else(|| CURRENT.load(Ordering::Acquire) - 1))
                            .map(|mmf| {
                                let buff = unsafe { std::slice::from_raw_parts_mut(data, size) };
                                match mmf.write(buff) {
                                    Ok(_) => 0,
                                    Err(Error::MMF_NotFound) => -1,
                                    Err(Error::NotEnoughMemory) => -2,
                                    Err(Error::Uninitialized) => -3,
                                    Err(Error::ReadLocked) | Err(Error::WriteLocked) => -4,
                                    _ => -5,
                                }
                            })
                            .unwrap_or(-3)
                    })
                    .unwrap_or(-5)
            })
            .unwrap_or(-5)
    } else {
        0 // Copying zero bytes is always successful.
    }
}

/// Convenience function to open a read-only MMF and get an index back to read from it.
///
/// Results returned from this function are the same as [`open`]
#[unsafe(no_mangle)]
pub extern "system" fn open_ro(
    size: Option<NonZeroUsize>,
    name: *const c_char,
    namespace: u8,
    large_pages: Option<&bool>,
) -> isize {
    match (
        size,
        unsafe { CStr::from_ptr(name).to_str().ok().map(|s| (s.len() > 0).then(|| s.to_owned())).flatten() },
        namespace.try_into(),
    ) {
        (None, _, _) => -1,
        (_, None, _) => -2,
        (_, _, Err(_)) => -3,
        (Some(size), Some(namestr), Ok(ns)) => {
            if let Ok(mapped) = MemoryMappedFile::open(size, namestr, ns, true, large_pages.cloned()) {
                MMFS.get_or_init(|| _init(1))
                    .lock()
                    .map(|mut inner| {
                        inner.push(mapped);
                        let idx = inner.len() - 1;
                        CURRENT.store(idx + 1, Ordering::Relaxed);
                        idx as isize
                    })
                    .unwrap_or(-5)
            } else {
                -4
            }
        }
    }
}

/// Close the MMF
///
/// Closes the specific instance stored here without interferring with other processes that might be using it.
#[unsafe(no_mangle)]
pub extern "system" fn close(mmf_idx: Option<NonZeroUsize>) {
    MMFS.get()
        .map(|inner| {
            inner
                .lock()
                .map(|mut inner| {
                    drop(
                        inner.remove(
                            mmf_idx.map(|nsu| nsu.get()).unwrap_or_else(|| CURRENT.load(Ordering::Acquire) - 1),
                        ),
                    )
                })
                .unwrap_or_default()
        })
        .unwrap_or_default()
}

/// Selects a different default mmf for all operations.
///
/// The only thing that can really go wrong here is the user being dumb,
/// so the input is clamped or wrapped and the newly selected index is returned.
#[unsafe(no_mangle)]
pub extern "system" fn select_default(mmf_idx: Option<NonZeroUsize>) -> isize {
    if let Some(max_idx) = MMFS.get().map(|inner| inner.lock().unwrap().len()) {
        let idx = mmf_idx.map(|nsu| nsu.get()).unwrap_or(CURRENT.load(Ordering::Acquire));
        let select = if idx == 0 || idx > max_idx { max_idx } else { idx };
        CURRENT.store(select, Ordering::Release);
        return select as isize;
    }
    -1
}