From 9fbab202b6fd1f8498734f6918a639ae8341d760 Mon Sep 17 00:00:00 2001 From: Spencer Bartholomew <38776747+spencerbart@users.noreply.github.com> Date: Tue, 28 Feb 2023 10:48:30 -0700 Subject: [PATCH 1/2] depreciate this crate --- README.md | 193 +------------------------------------------ wee_alloc/src/lib.rs | 8 ++ 2 files changed, 9 insertions(+), 192 deletions(-) diff --git a/README.md b/README.md index cc246e5..c660da5 100644 --- a/README.md +++ b/README.md @@ -1,192 +1 @@ -
- -

wee_alloc

- - The Wasm-Enabled, Elfin Allocator - -

- Build Status - Build Status - Crates.io version - Download - docs.rs docs -

- -

- API Docs - | - Contributing - | - Chat -

- - Built with 🦀🕸 by The Rust and WebAssembly Working Group -
- - -### About - -`wee_alloc`: The **W**asm-**E**nabled, **E**lfin Allocator. - -- **Elfin, i.e. small:** Generates less than a kilobyte of uncompressed - WebAssembly code. Doesn't pull in the heavy panicking or formatting - infrastructure. `wee_alloc` won't bloat your `.wasm` download size on the Web. - -- **WebAssembly enabled:** Designed for the `wasm32-unknown-unknown` target and - `#![no_std]`. - -`wee_alloc` is focused on targeting WebAssembly, producing a small `.wasm` code -size, and having a simple, correct implementation. It is geared towards code -that makes a handful of initial dynamically sized allocations, and then performs -its heavy lifting without any further allocations. This scenario requires *some* -allocator to exist, but we are more than happy to trade allocation performance -for small code size. In contrast, `wee_alloc` would be a poor choice for a -scenario where allocation is a performance bottleneck. - -Although WebAssembly is the primary target, `wee_alloc` also has an `mmap` based -implementation for unix systems, a `VirtualAlloc` implementation for Windows, -and a static array-based backend for OS-independent environments. This enables -testing `wee_alloc`, and code using `wee_alloc`, without a browser or -WebAssembly engine. - -`wee_alloc` compiles on stable Rust 1.33 and newer. - -- [Using `wee_alloc` as the Global Allocator](#using-wee_alloc-as-the-global-allocator) -- [`cargo` Features](#cargo-features) -- [Implementation Notes and Constraints](#implementation-notes-and-constraints) -- [License](#license) -- [Contribution](#contribution) - -### Using `wee_alloc` as the Global Allocator - -```rust -extern crate wee_alloc; - -// Use `wee_alloc` as the global allocator. -#[global_allocator] -static ALLOC: wee_alloc::WeeAlloc = wee_alloc::WeeAlloc::INIT; -``` - -### `cargo` Features - -- **size_classes**: On by default. Use size classes for smaller allocations to - provide amortized *O(1)* allocation for them. Increases uncompressed `.wasm` - code size by about 450 bytes (up to a total of ~1.2K). - -- **extra_assertions**: Enable various extra, expensive integrity assertions and - defensive mechanisms, such as poisoning freed memory. This incurs a large - runtime overhead. It is useful when debugging a use-after-free or `wee_alloc` - itself. - -- **static_array_backend**: Force the use of an OS-independent backing - implementation with a global maximum size fixed at compile time. Suitable for - deploying to non-WASM/Unix/Windows `#![no_std]` environments, such as on - embedded devices with esoteric or effectively absent operating systems. The - size defaults to 32 MiB (33554432 bytes), and may be controlled at build-time - by supplying an optional environment variable to cargo, - `WEE_ALLOC_STATIC_ARRAY_BACKEND_BYTES`. Note that this feature requires - nightly Rust. - -- **nightly**: Enable usage of nightly-only Rust features, such as implementing - the `Alloc` trait (not to be confused with the stable `GlobalAlloc` trait!) - -### Implementation Notes and Constraints - -- `wee_alloc` imposes two words of overhead on each allocation for maintaining - its internal free lists. - -- Deallocation is an *O(1)* operation. - -- `wee_alloc` will never return freed pages to the WebAssembly engine / - operating system. Currently, WebAssembly can only grow its heap, and can never - shrink it. All allocated pages are indefinitely kept in `wee_alloc`'s internal - free lists for potential future allocations, even when running on unix - targets. - -- `wee_alloc` uses a simple, first-fit free list implementation. This means that - allocation is an *O(n)* operation. - - Using the `size_classes` feature enables extra free lists dedicated to small - allocations (less than or equal to 256 words). The size classes' free lists - are populated by allocating large blocks from the main free list, providing - amortized *O(1)* allocation time. Allocating from the size classes' free lists - uses the same first-fit routines that allocating from the main free list does, - which avoids introducing more code bloat than necessary. - -Finally, here is a diagram giving an overview of `wee_alloc`'s implementation: - -``` -+------------------------------------------------------------------------------+ -| WebAssembly Engine / Operating System | -+------------------------------------------------------------------------------+ - | - | - | 64KiB Pages - | - V -+------------------------------------------------------------------------------+ -| Main Free List | -| | -| +------+ +------+ +------+ +------+ | -| Head --> | Cell | --> | Cell | --> | Cell | --> | Cell | --> ... | -| +------+ +------+ +------+ +------+ | -| | -+------------------------------------------------------------------------------+ - | | ^ - | | | - | Large Blocks | | - | | | - V | | -+---------------------------------------------+ | | -| Size Classes | | | -| | | | -| +------+ +------+ | | | -| Head(1) --> | Cell | --> | Cell | --> ... | | | -| +------+ +------+ | | | -| | | | -| +------+ +------+ | | | -| Head(2) --> | Cell | --> | Cell | --> ... | | | -| +------+ +------+ | | | -| | | | -| ... | | | -| | | | -| +------+ +------+ | | | -| Head(256) --> | Cell | --> | Cell | --> ... | | | -| +------+ +------+ | | | -| | | | -+---------------------------------------------+ | | - | ^ | | - | | | | - Small | Small | Large | Large | - Allocations | Frees | Allocations | Frees | - | | | | - | | | | - | | | | - | | | | - | | | | - V | V | -+------------------------------------------------------------------------------+ -| User Application | -+------------------------------------------------------------------------------+ -``` - -### License - -Licensed under the [Mozilla Public License 2.0](https://www.mozilla.org/en-US/MPL/2.0/). - -[TL;DR?](https://choosealicense.com/licenses/mpl-2.0/) - -> Permissions of this weak copyleft license are conditioned on making available -> source code of licensed files and modifications of those files under the same -> license (or in certain cases, one of the GNU licenses). Copyright and license -> notices must be preserved. Contributors provide an express grant of patent -> rights. However, a larger work using the licensed work may be distributed -> under different terms and without source code for files added in the larger -> work. - -### Contribution - -See -[CONTRIBUTING.md](https://github.com/rustwasm/wee_alloc/blob/master/CONTRIBUTING.md) -for hacking! - +# THIS CRATE HAS MAJOR SECURITY ISSUES AND SHOULD BE CONSIDERED DEPRECIATED \ No newline at end of file diff --git a/wee_alloc/src/lib.rs b/wee_alloc/src/lib.rs index f4aff45..4b06a3c 100644 --- a/wee_alloc/src/lib.rs +++ b/wee_alloc/src/lib.rs @@ -186,22 +186,27 @@ extern crate spin; extern crate memory_units; +#[deprecated(note = "this crate is deprecated and has major bugs")] #[macro_use] mod extra_assert; cfg_if! { if #[cfg(feature = "static_array_backend")] { + #[deprecated(note = "this crate is deprecated and has major bugs")] mod imp_static_array; use imp_static_array as imp; } else if #[cfg(target_arch = "wasm32")] { + #[deprecated(note = "this crate is deprecated and has major bugs")] mod imp_wasm32; use imp_wasm32 as imp; } else if #[cfg(unix)] { extern crate libc; + #[deprecated(note = "this crate is deprecated and has major bugs")] mod imp_unix; use imp_unix as imp; } else if #[cfg(windows)] { extern crate winapi; + #[deprecated(note = "this crate is deprecated and has major bugs")] mod imp_windows; use imp_windows as imp; } else { @@ -211,8 +216,11 @@ cfg_if! { } } +#[deprecated(note = "this crate is deprecated and has major bugs")] mod const_init; +#[deprecated(note = "this crate is deprecated and has major bugs")] mod neighbors; +#[deprecated(note = "this crate is deprecated and has major bugs")] #[cfg(feature = "size_classes")] mod size_classes; From 28c3d73b04cdf396e627c6ba8c4dcea1b29e3e78 Mon Sep 17 00:00:00 2001 From: Spencer Bartholomew <38776747+spencerbart@users.noreply.github.com> Date: Tue, 28 Feb 2023 10:53:58 -0700 Subject: [PATCH 2/2] change spelling --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index c660da5..7470bf7 100644 --- a/README.md +++ b/README.md @@ -1 +1 @@ -# THIS CRATE HAS MAJOR SECURITY ISSUES AND SHOULD BE CONSIDERED DEPRECIATED \ No newline at end of file +# THIS CRATE HAS MAJOR SECURITY ISSUES AND SHOULD BE CONSIDERED DEPRECATED \ No newline at end of file