From de852c819f43c9651d2d636ee96db0852a09f0bb Mon Sep 17 00:00:00 2001 From: Bradlee Speice Date: Mon, 11 Feb 2019 00:18:16 -0500 Subject: [PATCH] Mark everything deprecated --- CHANGELOG.md | 8 +++++++- README.md | 34 +++++++++++++++++++++++++++++----- qadapt-macro/Cargo.toml | 4 ++-- qadapt-macro/README.md | 2 ++ qadapt-macro/src/lib.rs | 6 ++++++ src/lib.rs | 26 ++++++++++++++++++++++++++ 6 files changed, 72 insertions(+), 8 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 4feff58..07b7dd6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,4 +1,10 @@ -# Version 1.1.0 +# Version 1.0.3 + +- Mark the crate deprecated; [alloc-counter](https://crates.io/crates/alloc_counter) + does a better job at solving the problems QADAPT was driven for, and I'll be putting + my effort towards improving it instead. + +# Version 1.0.2 - Don't panic if calling guarded code and QADAPT isn't the allocator; Instead, let code determine at runtime whether or not QADAPT is enabled diff --git a/README.md b/README.md index 9532b79..6181b0e 100644 --- a/README.md +++ b/README.md @@ -9,6 +9,8 @@ --- ## `debug_assert!` for your memory usage +**Please note**: This crate has been deprecated in favor of [alloc-counter](https://crates.io/crates/alloc_counter). + This allocator is a helper for writing high-performance code that is memory-sensitive; a thread panic will be triggered if a function annotated with `#[no_alloc]`, or code inside an `assert_no_alloc!` macro interacts with the allocator in any way. @@ -26,18 +28,31 @@ circumstance causing your application to crash. Actually making use of QADAPT is straight-forward. To set up the allocator, place the following snippet in either your program binaries (main.rs) or tests: -```rust,ignore +```rust use qadapt::QADAPT; #[global_allocator] static Q: QADAPT = QADAPT; + +fn main() { + # // Because `debug_assertions` are on for doctests in release mode + # // we have to add an extra guard. + # if qadapt::is_active() { + assert!(qadapt::is_active()); + # } +} ``` After that, there are two ways of telling QADAPT that it should trigger a panic: 1. Annotate functions with the `#[no_alloc]` proc macro: -```rust,no_run +```rust use qadapt::no_alloc; +use qadapt::QADAPT; +use std::panic::catch_unwind; + +#[global_allocator] +static Q: QADAPT = QADAPT; // This function is fine, there are no allocations here #[no_alloc] @@ -53,15 +68,23 @@ fn does_panic() -> Box { fn main() { do_math(); - does_panic(); + + let err = catch_unwind(|| does_panic()); + # if qadapt::is_active() { + assert!(err.is_err()); + # } } ``` 2. Evaluate expressions with the `assert_no_alloc!` macro -```rust,no_run +```rust use qadapt::assert_no_alloc; +use qadapt::QADAPT; -fn do_work() { +#[global_allocator] +static Q: QADAPT = QADAPT; + +fn main() { // This code is allowed to trigger an allocation let b = Box::new(8); @@ -69,3 +92,4 @@ fn do_work() { let x = assert_no_alloc!(*b + 2); assert_eq!(x, 10); } +``` diff --git a/qadapt-macro/Cargo.toml b/qadapt-macro/Cargo.toml index 1f7360e..1e905fa 100644 --- a/qadapt-macro/Cargo.toml +++ b/qadapt-macro/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "qadapt-macro" -version = "1.0.2" +version = "1.0.3" authors = ["Bradlee Speice "] description = "The Quick And Dirty Allocation Profiling Tool - Support Macros" license = "Apache-2.0" @@ -16,7 +16,7 @@ repository = "https://github.com/bspeice/qadapt.git" edition = "2018" [badges] -maintenance = { status = "actively-developed" } +maintenance = { status = "deprecated" } [lib] proc-macro = true diff --git a/qadapt-macro/README.md b/qadapt-macro/README.md index e84994c..e7a6084 100644 --- a/qadapt-macro/README.md +++ b/qadapt-macro/README.md @@ -5,5 +5,7 @@ Helper macro for the QADAPT allocator. +**Please note**: This crate has been deprecated in favor of [alloc-counter](https://crates.io/crates/alloc_counter) + This crate is intended for managing the QADAPT allocator, and is unusable on its own. \ No newline at end of file diff --git a/qadapt-macro/src/lib.rs b/qadapt-macro/src/lib.rs index 4f14c75..daf81eb 100644 --- a/qadapt-macro/src/lib.rs +++ b/qadapt-macro/src/lib.rs @@ -1,5 +1,7 @@ //! Helper macros to use with the QADAPT allocator system //! +//! **Please note**: This crate has been deprecated in favor of [alloc-counter](https://crates.io/crates/alloc_counter) +//! //! This crate is intended for managing the QADAPT allocator, //! and is unusable on its own. //! @@ -155,6 +157,10 @@ fn escape_return(ts: TokenStream) -> TokenStream { /// separate thread, or defers allocations via closure/Future, those results /// will not trigger an error. #[proc_macro_attribute] +#[deprecated( + since = "1.0.3", + note = "Please use the `alloc_counter` crate instead." +)] pub fn no_alloc(_attr: TokenStream, item: TokenStream) -> TokenStream { let mut protected_fn: Vec = Vec::new(); let mut item_iter = item.into_iter(); diff --git a/src/lib.rs b/src/lib.rs index cc88ad4..dda1ba5 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -1,5 +1,7 @@ //! ## `debug_assert!` for your memory usage //! +//! **Please note**: This crate has been deprecated in favor of [alloc-counter](https://crates.io/crates/alloc_counter). +//! //! This allocator is a helper for writing high-performance code that is memory-sensitive; //! a thread panic will be triggered if a function annotated with `#[no_alloc]`, //! or code inside an `assert_no_alloc!` macro interacts with the allocator in any way. @@ -120,6 +122,10 @@ static INTERNAL_ALLOCATION: RwLock = RwLock::new(usize::max_value()); /// # } /// } /// ``` +#[deprecated( + since = "1.0.3", + note = "Please use the `alloc_counter` crate instead." +)] pub struct QADAPT; static SYSTEM_ALLOC: System = System; @@ -150,6 +156,10 @@ static SYSTEM_ALLOC: System = System; /// // It's now safe to allocate/drop again /// let z = Box::new(y); /// } +#[deprecated( + since = "1.0.3", + note = "Please use the `alloc_counter` crate instead." +)] pub fn enter_protected() { #[cfg(debug_assertions)] { @@ -191,6 +201,10 @@ pub fn enter_protected() { /// // It's now safe to allocate/drop again /// let z = Box::new(y); /// } +#[deprecated( + since = "1.0.3", + note = "Please use the `alloc_counter` crate instead." +)] pub fn exit_protected() { #[cfg(debug_assertions)] { @@ -259,6 +273,10 @@ pub fn exit_protected() { /// # } /// } #[macro_export] +#[deprecated( + since = "1.0.3", + note = "Please use the `alloc_counter` crate instead." +)] macro_rules! assert_no_alloc { ($e:expr) => {{ ::qadapt::enter_protected(); @@ -298,6 +316,10 @@ macro_rules! assert_no_alloc { /// /// // It's now safe to allocate/drop /// } +#[deprecated( + since = "1.0.3", + note = "Please use the `alloc_counter` crate instead." +)] pub fn protection_level() -> usize { PROTECTION_LEVEL.try_with(|v| *v.read()).unwrap_or(0) } @@ -324,6 +346,10 @@ pub fn protection_level() -> usize { /// # } /// } /// ``` +#[deprecated( + since = "1.0.3", + note = "Please use the `alloc_counter` crate instead." +)] pub fn is_active() -> bool { if cfg!(debug_assertions) { // Because there are heap allocations that happen before `fn main()`,