From 30a075810c14671a7d78c75ed0d1c4241268823d Mon Sep 17 00:00:00 2001 From: Amos Wenger Date: Thu, 18 Jul 2024 19:22:21 +0200 Subject: [PATCH] More docs --- rubicon/Cargo.lock | 2 +- rubicon/Cargo.toml | 2 +- rubicon/src/lib.rs | 32 ++++++++++++++++++++++++++++++++ 3 files changed, 34 insertions(+), 2 deletions(-) diff --git a/rubicon/Cargo.lock b/rubicon/Cargo.lock index 480e0ef..7b22938 100644 --- a/rubicon/Cargo.lock +++ b/rubicon/Cargo.lock @@ -10,7 +10,7 @@ checksum = "57c0d7b74b563b49d38dae00a0c37d4d6de9b432382b2892f0574ddcae73fd0a" [[package]] name = "rubicon" -version = "2.0.0" +version = "3.0.0" dependencies = [ "paste", ] diff --git a/rubicon/Cargo.toml b/rubicon/Cargo.toml index 49c8188..1cee335 100644 --- a/rubicon/Cargo.toml +++ b/rubicon/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "rubicon" -version = "2.0.0" +version = "3.0.0" edition = "2021" authors = ["Amos Wenger "] license = "MIT OR Apache-2.0" diff --git a/rubicon/src/lib.rs b/rubicon/src/lib.rs index 9318b5d..1bd3652 100644 --- a/rubicon/src/lib.rs +++ b/rubicon/src/lib.rs @@ -1,3 +1,35 @@ +//! rubicon enables a dangerous form of dynamic linking in Rust through cdylib crates +//! and carefully-enforced invariants. +//! +//! This crate provides macros to handle global state (thread-locals and process-locals/statics) +//! in a way that's compatible with the "xgraph" dynamic linking model, where multiple +//! copies of the same crate can coexist in the same address space. +//! +//! The main macros provided are: +//! +//! - `thread_local!`: A drop-in replacement for `std::thread_local!` +//! - `process_local!`: Used to declare statics (including `static mut`) +//! +//! These macros behave differently depending on whether the `export-globals` or +//! `import-globals` feature is enabled: +//! +//! - With `export-globals`: Symbols are exported for use by dynamically loaded modules +//! - With `import-globals`: Symbols are imported from the main executable +//! - With neither: The macros act as pass-through to standard Rust constructs +//! +//! # Safety +//! +//! Using this crate requires careful adherence to several invariants: +//! +//! 1. Modules must never be unloaded, only loaded. +//! 2. The exact same Rust compiler version must be used for the app and all modules. +//! 3. The exact same cargo features must be enabled for shared dependencies. +//! +//! Failure to maintain these invariants can lead to undefined behavior. +//! +//! For more details on the motivation and implementation of the "xgraph" model, +//! refer to the [crate's README and documentation](https://github.com/bearcove/rubicon?tab=readme-ov-file#rubicon). + #[cfg(all(feature = "export-globals", feature = "import-globals"))] compile_error!("The features `export-globals` and `import-globals` are mutually exclusive, see https://github.com/bearcove/rubicon");