From bc02cf11850b493c3a6ec5f944bb18c29ff1446c Mon Sep 17 00:00:00 2001 From: James Munns Date: Fri, 31 Jan 2025 00:22:59 +0100 Subject: [PATCH 1/2] Bump version --- Cargo.lock | 4 ++-- source/mutex/Cargo.toml | 2 +- source/mutex/src/raw_impls.rs | 3 ++- 3 files changed, 5 insertions(+), 4 deletions(-) diff --git a/Cargo.lock b/Cargo.lock index 6fb8cfe..ba40058 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -1,6 +1,6 @@ # This file is automatically @generated by Cargo. # It is not intended for manual editing. -version = 3 +version = 4 [[package]] name = "autocfg" @@ -26,7 +26,7 @@ dependencies = [ [[package]] name = "mutex" -version = "0.1.0" +version = "1.0.0" dependencies = [ "critical-section", "lock_api", diff --git a/source/mutex/Cargo.toml b/source/mutex/Cargo.toml index 7c16707..245f9e4 100644 --- a/source/mutex/Cargo.toml +++ b/source/mutex/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "mutex" -version = "0.1.0" +version = "1.0.0" description = "An abstraction over closure-based mutexes" categories = [ "embedded", diff --git a/source/mutex/src/raw_impls.rs b/source/mutex/src/raw_impls.rs index 2a8787d..5c1b450 100644 --- a/source/mutex/src/raw_impls.rs +++ b/source/mutex/src/raw_impls.rs @@ -10,9 +10,10 @@ use core::marker::PhantomData; use core::sync::atomic::{AtomicBool, Ordering}; - use mutex_traits::{ConstInit, ScopedRawMutex}; +pub use mutex_traits as traits; + #[cfg(feature = "impl-critical-section")] pub mod cs { //! Critical Section based implementation From 244c02fa5f9594a0ffc48ca8f8015c6bff2e4e37 Mon Sep 17 00:00:00 2001 From: James Munns Date: Fri, 31 Jan 2025 00:53:52 +0100 Subject: [PATCH 2/2] Improve the readmes --- source/mutex-traits/README.md | 19 +++++++++++++++++++ source/mutex/README.md | 18 ++++++++++++++++++ 2 files changed, 37 insertions(+) diff --git a/source/mutex-traits/README.md b/source/mutex-traits/README.md index a203f37..18e849e 100644 --- a/source/mutex-traits/README.md +++ b/source/mutex-traits/README.md @@ -23,6 +23,23 @@ Compared to the more general traits provided by the [`lock_api`] crate, these traits are aimed at being more compatible with implementations based on critical sections, are easier to work with in a nested or strictly LIFO pattern. +## Versioning, and which crate to use? + +The [`mutex-traits`] crate should be used by **library crates** that want to be generic +over different ways of exclusive access. + +The [`mutex`] crate should be used by **applications** that need to select which implementation +is appropriate for their use case. The [`mutex`] crate also re-exports the [`mutex-traits`] +crate for convenience, so applications only need to pull in one direct dependency. + +While both crates are >= 1.0, it should be expected that it is **MUCH** more likely that [`mutex`] +crate will make breaking changes someday. The hope is that [`mutex-traits`] NEVER releases a 2.0 +version, which means that even if there are 1.x, 2.x, 3.x, etc. versions of the [`mutex`] crate, +they all can be used interchangably since they implement the 1.x [`mutex-traits`] interfaces. + +If you are a library crate, consider ONLY relying on the [`mutex-traits`] crate directly, and +put any use of the [`mutex`] crate behind a feature flag or in the `dev-dependencies` section. + ## Provenance Portions of this code are forked from the `embassy-sync` crate. @@ -46,4 +63,6 @@ Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions. +[`mutex`]: https://crates.io/crates/mutex +[`mutex-traits`]: https://crates.io/crates/mutex-traits [`lock_api`]: https://docs.rs/lock_api/ diff --git a/source/mutex/README.md b/source/mutex/README.md index dcd7b7d..8d57a54 100644 --- a/source/mutex/README.md +++ b/source/mutex/README.md @@ -19,6 +19,23 @@ Mutex implementations using [`mutex-traits`]. +## Versioning, and which crate to use? + +The [`mutex-traits`] crate should be used by **library crates** that want to be generic +over different ways of exclusive access. + +The [`mutex`] crate should be used by **applications** that need to select which implementation +is appropriate for their use case. The [`mutex`] crate also re-exports the [`mutex-traits`] +crate for convenience, so applications only need to pull in one direct dependency. + +While both crates are >= 1.0, it should be expected that it is more likely that [`mutex`] crate +will make breaking changes someday. The hope is that [`mutex-traits`] NEVER releases a 2.0 +version, which means that even if there are 1.x, 2.x, 3.x, etc. versions of the [`mutex`] crate, +they all can be used interchangably since they implement the 1.x [`mutex-traits`] interfaces. + +If you are a library crate, consider ONLY relying on the [`mutex-traits`] crate directly, and +put any use of the [`mutex`] crate behind a feature flag or in the `dev-dependencies` section. + ## Crate Feature Flags The following feature flags enable implementations of @@ -49,6 +66,7 @@ functionality other than implementations of [`ScopedRawMutex`]/[`RawMutex`]: by embedded projects and other use-cases where minimizing binary size is important. +[`mutex`]: https://crates.io/crates/mutex [`mutex-traits`]: https://crates.io/crates/mutex-traits [`critical-section`]: https://crates.io/crates/critical-section [`lock_api`]: https://crates.io/crates/critical-section