A safe and idiomatic wrapper over shared memory APIs in rust with proper cleanups.

Overview

shmem-bind

A safe and idiomatic wrapper over shared memory APIs in rust with proper cleanups.

Quick start:

check the message-passing example for better understanding

cargo run --example message-passing

Semantics:

Allocation:

import shared memory abstractions:

use shmem_bind::{ShmemBox, self as shmem};

in order to create new shared memory, use the following builder snippet:

let shared_mem = shmem::Builder::new("<FLINK_FILE_HANDLE>")
    .with_size(mem::size_of::<MyType>() as i64)
    .open()?;

this will allocate a shared memory file with the specified size if the shared memory is not present on the machine. the handle, here shared_mem, would claim ownership of the shared memory if the shared memory is not present and created via call to open function. this is useful information for cleanup process since there is only one owner for each shared memory and only the owner can and will unlink the shared memory.

you can wrap the shared memory configuration into a ShmemBox<T> via call to boxed function.

let boxed_val = unsafe { shared_mem.boxed::<MyType>() };

call to this function is inherently unsafe since there is no guarantee that the memory behind the pointer is initialized or valid.

type NotZeroI32 = i32;

let boxed_val = unsafe { 
  // the allocated shared_memory is zeroed and thus, not a valid `NotZeroI32`
  let mut boxed_val = shared_mem.boxed::<NotZeroI32>();
  *boxed_val = 5;
  boxed_val
  };

the ShmemBox type implements Deref and DerefMut so you can use all the rust semantics and guarantee of T in your code

Cleanup:

When the variable goes out of scope, the drop implementation is called. if the shared memory is owned, i.e. shared memory is created by this handle, the shared memory would unlink. in order to prevent this, you can use the ShmemBox::leak method:

struct MyType;

impl Drop for MyType{
    fn drop(&mut self) {
        println!("my type is dropped");
    }
}

{
  let shared_mem = shmem::Builder::new("<FLINK_FILE_HANDLE>")
      .with_size(mem::size_of::<Message>() as i64)
      .open()?;
  let mut boxed_val = unsafe {shared_mem.boxed::<MyType>()};

  // boxed_val goes out of scope and the underlying MyType is dropped
  // output:
  // my type is dropped
}
{
  let shared_mem = shmem::Builder::new("<FLINK_FILE_HANDLE>")
      .with_size(mem::size_of::<Message>() as i64)
      .open()?;
  let mut boxed_val = unsafe {shared_mem.boxed::<MyType>()};
  ShmemBox::leak(boxed_val);

  // boxed_val leaks and the underlying MyType is not dropped. the shared memory stays linked to the os
  // output is empty
}

you can also use the ShmemBox::own to ensure cleanup of the shared memory:

struct MyType;

impl Drop for MyType{
    fn drop(&mut self) {
        println!("my type is dropped");
    }
}

{
  let shared_mem = shmem::Builder::new("<FLINK_FILE_HANDLE>")
      .with_size(mem::size_of::<Message>() as i64)
      .open()?;
  let mut boxed_val = unsafe {shared_mem.boxed::<MyType>()};
  
  // boxed_val was owner, but it got leaked
  ShmemBox::leak(boxed_val);
}
{
  let shared_mem = shmem::Builder::new("<FLINK_FILE_HANDLE>")
      .with_size(mem::size_of::<Message>() as i64)
      .open()?;
  let mut boxed_val = unsafe {shared_mem.boxed::<MyType>()};
  
  // shared memory is already created, so the boxed_val is not the owner.
  let boxed_val = ShmemBox::own(boxed_val);

  // boxed_val goes out of scope, MyType is dropped. the shared memory is unliked.
  // output:
  // my type is dropped
}

ShmemBox<T> implements Sync and Send if the underlying T implements Sync and Send respectively.

You might also like...
Shared k-mer content between two genomes

skc skc is a simple tool for finding shared k-mer content between two genomes. Installation Prebuilt binary curl -sSL skc.mbh.sh | sh # or with wget w

REC2 (Rusty External Command and Control) is client and server tool allowing auditor to execute command from VirusTotal and Mastodon APIs written in Rust. 🦀
REC2 (Rusty External Command and Control) is client and server tool allowing auditor to execute command from VirusTotal and Mastodon APIs written in Rust. 🦀

Information: REC2 is an old personal project (early 2023) that I didn't continue development on. It's part of a list of projects that helped me to lea

Fork of the Official Python3 API connector for Bybit's HTTP (bybit) and WebSockets APIs to rust

Fork of pybit python libary in Rust For the rust lovers and creators for bybit exchange version 5 Official Python3 API connector for Bybit's HTTP and

Rust library for integrating local LLMs (with llama.cpp) and external LLM APIs.

Table of Contents About The Project Getting Started Roadmap Contributing License Contact A rust interface for the OpenAI API and Llama.cpp ./server AP

Crates.io library that provides high-level APIs for obtaining information on various entertainment media such as books, movies, comic books, anime, manga, and so on.
Crates.io library that provides high-level APIs for obtaining information on various entertainment media such as books, movies, comic books, anime, manga, and so on.

Crates.io library that provides high-level APIs for obtaining information on various entertainment media such as books, movies, comic books, anime, manga, and so on.

Prototype for a CLI/Libary designed for interacting with NASA Open APIs with Rust.

Overview Voyager is a swiss army knife library for the NASA Open APIs. It is designed to bundle all the NASA APIs into a single package. Voyager can b

excss is a small, simple, zero-runtime CSS-in-JS library with just two APIs.

excss excss is a small, simple, zero-runtime CSS-in-JS library with just two APIs.

Incredible.dev is an AI Coding Co-worker which can code, fix, document, deploy, test your APIs. One agent to rule everything API.

Incredible.dev Early Github preview, documentation and instruction to run coming soon in a week! Here are some highlights: AI agents that can code, fi

Sample and plot power consumption, average frequency and cpu die temperatures over time.
Sample and plot power consumption, average frequency and cpu die temperatures over time.

sense Sense is a small tool to gather data on cpu temperature, power usage and clock frequency and plot graphs during some load. Dependencies Sense is

Owner
ArshiA Akhavan
ArshiA Akhavan
nvim-oxi provides safe and idiomatic Rust bindings to the rich API exposed by the Neovim text editor.

?? nvim-oxi nvim-oxi provides safe and idiomatic Rust bindings to the rich API exposed by the Neovim text editor. The project is mostly intended for p

Riccardo Mazzarini 655 Jul 13, 2023
Idiomatic inotify wrapper for the Rust programming language

inotify-rs Idiomatic inotify wrapper for the Rust programming language. extern crate inotify; use std::env; use inotify::{ EventMask, Watch

Hanno Braun 220 Dec 26, 2022
A simple made in Rust crack, automatic for Winrar, activated from shared virtual memory, for studies.

Simple Winrar Crack in Rust What does it do ? A simple project that allows you to modify the license check used by WinRaR, "RegKey" from virtual memor

João Vitor 7 Jan 2, 2023
More than safe rust abstractions over rytm-sys, an unofficial SDK for writing software for Analog Rytm running on firmware 1.70.

rytm-rs More than safe rust abstractions over rytm-sys, an unofficial SDK for writing software for Analog Rytm running on firmware 1.70. On top of CC

Ali Somay 5 Dec 22, 2023
Wrapper over MMTk to simplify integration with runtimes: thread management system, object header, root scanning

vmkit A library which provides bunch of building blocks to make a VM in Rust. Feautures MMTK integration out of the box Thread management provided by

null 3 Aug 31, 2024
This repo contains crates that are used to create the micro services and keep shared code in a common place.

MyEmma Helper Crates This repo contains crates that can are reused over different services. These crate are used in projects at MyEmma. But these crat

MyEmma 1 Jan 14, 2022
Rustato: A powerful, thread-safe global state management library for Rust applications, offering type-safe, reactive state handling with an easy-to-use macro-based API.

Rustato State Manager A generical thread-safe global state manager for Rust Introduction • Features • Installation • Usage • Advanced Usage • Api Refe

BiteCraft 8 Sep 16, 2024
Shared Rust libraries for Hyperledger Indy.

indy-shared-rs Shared Rust libraries for Hyperledger Indy. indy-credx: Indy verifiable credential issuance and presentation (aka Anoncreds) indy-data-

Hyperledger 18 Dec 29, 2022
A CLI for extracting libraries from Apple's dyld shared cache file

dyld-shared-cache-extractor As of macOS Big Sur, instead of shipping the system libraries with macOS, Apple ships a generated cache of all built in dy

Keith Smiley 238 Jan 4, 2023
Shared execution environment for constructing 3D virtual spaces from the inside.

Hearth Hearth is a shared, always-on execution environment for constructing 3D virtual spaces from the inside. Come join our Discord server! The Histo

null 6 Jan 31, 2023