win-shared-memory

A typed, RAII Rust library for easy access to named Windows shared memory regions.

Table of Contents

• Dependencies and requirements
• Getting started
• Usage
  • Creating a region (writer process)
  • Opening a region (reader process)
  • Opening an existing region for read-write
• Access modes
• Error handling
• Safety
• Side notes

Dependencies and requirements

• Windows only — uses Win32 file-mapping APIs (CreateFileMappingW, MapViewOfFile, etc.).
• Requires Rust edition 2024.

Getting started

Add the library to your project:

cargo add win-shared-memory

Usage

All access goes through SharedMemoryLink<T, Access>, a typed RAII handle that unmaps the view and closes the handle automatically on drop. The type T describes the layout of the shared region and must be #[repr(C)] (or another stable layout) so that both processes agree on the memory layout.

Creating a region (writer process)

use win_shared_memory::{SharedMemoryLink, ReadWrite};

#[repr(C)]
struct GameState {
    score: u32,
    lives: u8,
}

// Create a fresh, zero-initialised region. Fails if the name is already taken.
let mut link: SharedMemoryLink<GameState, ReadWrite> =
    SharedMemoryLink::create("Local\\my_game_state").expect("failed to create shared memory");

unsafe {
    let state = link.get_mut();
    state.score = 42;
    state.lives = 3;
}

Use get_or_create instead if you want to open the region when it already exists:

let mut link: SharedMemoryLink<GameState, ReadWrite> =
    SharedMemoryLink::get_or_create("Local\\my_game_state").unwrap();

Opening a region (reader process)

use win_shared_memory::{SharedMemoryLink, ReadOnly};

#[repr(C)]
struct GameState {
    score: u32,
    lives: u8,
}

let link: SharedMemoryLink<GameState, ReadOnly> =
    SharedMemoryLink::open("Local\\my_game_state").expect("game not running");

let state = unsafe { link.get() };
println!("score: {}, lives: {}", state.score, state.lives);

Opening an existing region for read-write

A second writer (or any process that did not create the region) can open it for read-write access:

use win_shared_memory::{SharedMemoryLink, ReadWrite};

let mut link: SharedMemoryLink<GameState, ReadWrite> =
    SharedMemoryLink::open_existing("Local\\my_game_state").expect("region not found");

unsafe { link.get_mut().score += 1; }

Access modes

Error handling

All constructors return Result<_, SharedMemoryError>. The enum variants are:

Safety

get and get_mut are unsafe because shared memory is inherently a cross-process resource. The library enforces single-process aliasing rules through Rust's borrow checker (get_mut requires &mut self), but it cannot prevent a remote process from writing concurrently.

Callers are responsible for coordinating cross-process access — for example with a named mutex.

Side notes

Please keep in mind that at the moment this is a side project developed with no planned continuity nor schedule. Therefore support, fixes and new features can not be guaranteed.

As stated in the LICENSE, no contributor must be considered liable for the use of this project.