cofin/ipc

IPC (Inter-Process Communication)

Scope

• Shared memory regions (POSIX shm_open + mmap, Windows CreateFileMapping).
• Lock-free ring buffers (SPSC, MPMC).
• Platform-specific synchronization (futex, ulock, Win32 Event).
• Notification mechanisms (eventfd, pipe, kqueue).
• Async ring integration with Tokio.
• Buffer pools and zero-copy data transfer.

<workflow>

Shared Memory Regions

ShmRegion Pattern

<example>

pub struct ShmRegion {
    ptr: *mut u8,
    len: usize,
    fd: OwnedFd,  // RAII: closes on drop
}

impl ShmRegion {
    pub fn create(name: &str, size: usize) -> Result<Self, IpcError> {
        // SAFETY: shm_open + ftruncate + mmap is the standard POSIX pattern.
        // We own the fd exclusively and unlink after mapping.
        unsafe {
            let fd = shm_open(name, O_CREAT | O_RDWR, 0o600)?;
            ftruncate(fd, size as libc::off_t)?;
            let ptr = mmap(
                std::ptr::null_mut(),
                size,
                PROT_READ | PROT_WRITE,
                MAP_SHARED,
                fd,
                0,
            )?;
            shm_unlink(name)?;  // Unlink immediately — fd keeps it alive
            Ok(Self { ptr: ptr.cast(), len: size, fd: OwnedFd(fd) })
        }
    }

    pub fn as_slice(&self) -> &[u8] {
        // SAFETY: ptr is valid for len bytes and region outlives self
        unsafe { std::slice::from_raw_parts(self.ptr, self.len) }
    }
}

impl Drop for ShmRegion {
    fn drop(&mut self) {
        // SAFETY: We own this mapping exclusively
        unsafe { munmap(self.ptr.cast(), self.len) };
        // fd closed by OwnedFd::drop
    }
}

</example> <guardrails> ## Guardrails

• Always unlink shared memory immediately -- Use shm_unlink as soon as the memory is mapped to ensure it is correctly cleaned up by the OS when the process exits.
• Use RAII for all resources -- Wrap pointers, file descriptors, and mapping handles in structs that implement Drop to prevent resource leaks on crash or error.
• Align to page boundaries -- Shared memory region sizes should always be a multiple of the system page size (typically 4096 bytes) for optimal mapping.
• Capacity must be a power of two -- For ring buffers, this allows for fast indexing using bitwise AND instead of expensive modulo operations.
• Align headers to cache lines (64 bytes) -- This prevents false sharing between producers and consumers on different CPU cores. </guardrails>

<validation> ## Validation Checkpoint

• [ ] Shared memory is unlinked immediately after mapping
• [ ] RAII cleanup logic is implemented in Drop for all resources
• [ ] Ring buffer capacity is a power of two
• [ ] Headers are cache-line aligned (64 bytes) with explicit padding
• [ ] Bounds checks are performed on all reads and writes from shared memory
• [ ] Atomic memory ordering is correctly applied (Acquire/Release) </validation>