created_at2024-04-01 16:11:19.112588
updated_at2024-04-12 20:52:20.611697
descriptionShared memory crate designed for simplicity, safety, and extensibility
Jacob Lodenius (jlodenius)



# neocortex
Shared memory crate designed for simplicity, safety, and extensibility. With minimal dependencies on `libc` and `tracing`, this crate wraps unsafe shared memory operations in a user-friendly API. ## Quick Start Install using the *(currently)* only built-in lock implementation. See examples below for more instructions. ```bash cargo add neocortex --features semaphore ``` ## System Requirements - **Operating System**: Linux, macOS, or other UNIX-like operating systems. - **Dependencies**: Users must ensure `libc` is available in their system's standard library. ## Safety Guarantees - **Error Handling**: As `libc` syscalls are inherently unsafe, no guarantees can be made that all allocated resources are properly cleaned up on a failure. This crate provides two error variants, `CleanSystem` and `DirtySystem` to indicate whether or not the error is leaving any dangling resources. All system errors also provides additional error information from the operating system on top of our custom error messages. - **Error Logging**: As an additional safety guarantee, all `DirtySystem` errors that are not properly handled (currently only in some `Drop` implementations) will emit a `tracing::error!` event. ## Features - **Simple API**: Offers an easy-to-use interface for shared memory operations, abstracting `libc` complexities. - **Clear Error Handling**: Distinguishes between `Clean` and `Dirty` system errors. - **Built-in Synchronization**: Includes a semaphore-based lock for safe shared memory access. *(requires crate feature "semaphore")*. - **Extendable**: Flexibility to implement custom synchronization logic through the `CortexSync` trait. ## Examples Simple example using the built-in semaphore lock: ```rust use neocortex::{Cortex, CortexBuilder, Semaphore}; // Initialize a segment of shared memory with the value 42.0 let key = 123; let cortex = CortexBuilder::new(42.0) .key(key) .with_default_lock::() .unwrap(); // Attaching to an existing segment of shared memory requires explicit type annotations let attached: Cortex = Cortex::attach(key).unwrap(); assert_eq!(,; // Write to shared memory let new_val = 12.34; cortex.write(new_val).unwrap(); assert_eq!(, new_val); ``` The `semaphore` module comes with some pre-defined permissions, these permissions dictates which OS users can interact with the semaphore. Using `with_default_lock` defaults to `OwnerOnly` which is the most restrictive mode. Check out `SemaphorePermission` for other modes, or use the `Custom` enum-variant to set your own permissions. ```rust use neocortex::{CortexBuilder, Semaphore, SemaphoreSettings, SemaphorePermission}; let settings = SemaphoreSettings { mode: SemaphorePermission::OwnerAndGroup, }; let cortex = CortexBuilder::new(42.0) .key(123) .with_lock::(&settings) .unwrap(); ```
Commit count: 27

cargo fmt