Struct BuilderWithSize 

pub struct BuilderWithSize { /* private fields */ }

Implementations

impl BuilderWithSize

pub fn open(self) -> Result<ShmemConf, ShmemError>

Ensures a shared memory using the specified size and flink_id and mapping it to the virtual address of the process memory.

In case of success, a ShmemConf is returned, representing the configuration of the allocated shared memory.

If the shared memory with the given flink_id is not present on the system, the call to open would create a new shared memory and claims its ownership which is later used for cleanup of the shared memory.

Examples

use std::mem;
use shmem_bind::{self as shmem,ShmemError};

fn main() -> Result<(),ShmemError>{
    // shared_mem is the owner
    let shared_mem = shmem::Builder::new("flink_test")
        .with_size(mem::size_of::<i32>() as i64)
        .open()?;
    {
        // shared_mem_barrow is not the owner
        let shared_mem_barrow = shmem::Builder::new("flink_test")
            .with_size(mem::size_of::<i32>() as i64)
            .open()?;

        // shared_mem_barrow goes out of scope, the shared memory is unmapped from virtual
        // memory of the process.
    }
    // shared_mem goes out of scope, the shared memory is unmapped from virtual memory of
    // the process. after that, the shared memory is unlinked from the system.
    Ok(())
}

Examples found in repository

examples/message-passing.rs (line 28)

fn main() -> Result<(), Box<dyn Error>> {
    // create new shared memory pointer with desired size
    //
    // first call to this function with the same FILE_LINK_ID would result in creating a new shared
    // memory file and owning it. this would result in deleting the shared memory when the variable
    // goes out of scope.
    // the second call to this function will only open shared memory and would not delete it.
    let shared_mem = shmem::Builder::new("shmem-example_message-passing.shm")
        .with_size(mem::size_of::<Message>() as i64)
        .open()?;

    // wrap the raw shared memory ptr with desired Boxed type
    // user must ensure that the data the pointer is pointing to is initialized and valid for use
    let mut message = unsafe { shared_mem.boxed::<Message>() };

    let mut args = std::env::args();
    let num_args = args.len();
    match num_args {
        // parent process
        1 => {
            // ensure that first process owns the shared memory (used for cleanup)
            let mut message = ShmemBox::own(message);

            // initiate the data behind the boxed pointer
            message.val = 1;

            let binary_path = args.next().unwrap();
            let new_val = 5;
            // create new process to mutate the shared memory
            let mut handle = Command::new(&binary_path)
                .arg(format!("{new_val}"))
                .spawn()
                .unwrap();
            handle.wait()?;

            // assert that the new process mutated the shared memory
            assert_eq!(message.val, new_val);

            // message is dropped here, shared memory IS deallocated
        }
        // child process
        2 => {
            let value = std::env::args().last().unwrap().parse()?;

            message.val = value;

            // message is dropped here, shared memory IS NOT deallocated
        }
        _ => unimplemented!(),
    }
    Ok(())
}