]>
Commit | Line | Data |
---|---|---|
041b39d2 | 1 | //! # The Rust core allocation and collections library |
1a4d82fc | 2 | //! |
041b39d2 XL |
3 | //! This library provides smart pointers and collections for managing |
4 | //! heap-allocated values. | |
1a4d82fc | 5 | //! |
9c376795 | 6 | //! This library, like core, normally doesn’t need to be used directly |
8faf50e0 XL |
7 | //! since its contents are re-exported in the [`std` crate](../std/index.html). |
8 | //! Crates that use the `#![no_std]` attribute however will typically | |
9 | //! not depend on `std`, so they’d use this crate instead. | |
1a4d82fc | 10 | //! |
1a4d82fc JJ |
11 | //! ## Boxed values |
12 | //! | |
416331ca XL |
13 | //! The [`Box`] type is a smart pointer type. There can only be one owner of a |
14 | //! [`Box`], and the owner can decide to mutate the contents, which live on the | |
15 | //! heap. | |
1a4d82fc | 16 | //! |
bd371182 | 17 | //! This type can be sent among threads efficiently as the size of a `Box` value |
1a4d82fc JJ |
18 | //! is the same as that of a pointer. Tree-like data structures are often built |
19 | //! with boxes because each node often has only one owner, the parent. | |
20 | //! | |
21 | //! ## Reference counted pointers | |
22 | //! | |
416331ca XL |
23 | //! The [`Rc`] type is a non-threadsafe reference-counted pointer type intended |
24 | //! for sharing memory within a thread. An [`Rc`] pointer wraps a type, `T`, and | |
25 | //! only allows access to `&T`, a shared reference. | |
1a4d82fc | 26 | //! |
416331ca XL |
27 | //! This type is useful when inherited mutability (such as using [`Box`]) is too |
28 | //! constraining for an application, and is often paired with the [`Cell`] or | |
29 | //! [`RefCell`] types in order to allow mutation. | |
1a4d82fc JJ |
30 | //! |
31 | //! ## Atomically reference counted pointers | |
32 | //! | |
416331ca XL |
33 | //! The [`Arc`] type is the threadsafe equivalent of the [`Rc`] type. It |
34 | //! provides all the same functionality of [`Rc`], except it requires that the | |
35 | //! contained type `T` is shareable. Additionally, [`Arc<T>`][`Arc`] is itself | |
36 | //! sendable while [`Rc<T>`][`Rc`] is not. | |
1a4d82fc | 37 | //! |
32a655c1 | 38 | //! This type allows for shared access to the contained data, and is often |
1a4d82fc JJ |
39 | //! paired with synchronization primitives such as mutexes to allow mutation of |
40 | //! shared resources. | |
41 | //! | |
041b39d2 XL |
42 | //! ## Collections |
43 | //! | |
44 | //! Implementations of the most common general purpose data structures are | |
2c00a5a8 | 45 | //! defined in this library. They are re-exported through the |
041b39d2 XL |
46 | //! [standard collections library](../std/collections/index.html). |
47 | //! | |
1a4d82fc JJ |
48 | //! ## Heap interfaces |
49 | //! | |
83c7162d | 50 | //! The [`alloc`](alloc/index.html) module defines the low-level interface to the |
1a4d82fc | 51 | //! default global allocator. It is not compatible with the libc allocator API. |
416331ca | 52 | //! |
3dfed10e XL |
53 | //! [`Arc`]: sync |
54 | //! [`Box`]: boxed | |
55 | //! [`Cell`]: core::cell | |
56 | //! [`Rc`]: rc | |
57 | //! [`RefCell`]: core::cell | |
1a4d82fc | 58 | |
e9174d1e | 59 | #![allow(unused_attributes)] |
48663c56 | 60 | #![stable(feature = "alloc", since = "1.36.0")] |
dfeec247 | 61 | #![doc( |
74b04a01 | 62 | html_playground_url = "https://play.rust-lang.org/", |
dfeec247 XL |
63 | issue_tracker_base_url = "https://github.com/rust-lang/rust/issues/", |
64 | test(no_crate_inject, attr(allow(unused_variables), deny(warnings))) | |
65 | )] | |
5099ac24 FG |
66 | #![doc(cfg_hide( |
67 | not(test), | |
68 | not(any(test, bootstrap)), | |
5099ac24 FG |
69 | no_global_oom_handling, |
70 | not(no_global_oom_handling), | |
2b03887a FG |
71 | not(no_rc), |
72 | not(no_sync), | |
5099ac24 FG |
73 | target_has_atomic = "ptr" |
74 | ))] | |
4b012472 FG |
75 | #![doc(rust_logo)] |
76 | #![feature(rustdoc_internals)] | |
1a4d82fc | 77 | #![no_std] |
9cc50fc6 | 78 | #![needs_allocator] |
3c0e092e XL |
79 | // Lints: |
80 | #![deny(unsafe_op_in_unsafe_fn)] | |
487cf647 | 81 | #![deny(fuzzy_provenance_casts)] |
9fa01778 | 82 | #![warn(deprecated_in_future)] |
9fa01778 | 83 | #![warn(missing_debug_implementations)] |
3c0e092e | 84 | #![warn(missing_docs)] |
48663c56 | 85 | #![allow(explicit_outlives_requirements)] |
353b0b11 | 86 | #![warn(multiple_supertrait_upcastable)] |
781aab86 FG |
87 | #![allow(internal_features)] |
88 | #![allow(rustdoc::redundant_explicit_links)] | |
c620b35d | 89 | #![deny(ffi_unwind_calls)] |
3c0e092e XL |
90 | // |
91 | // Library features: | |
353b0b11 FG |
92 | // tidy-alphabetical-start |
93 | #![cfg_attr(not(no_global_oom_handling), feature(const_alloc_error))] | |
94 | #![cfg_attr(not(no_global_oom_handling), feature(const_btree_len))] | |
95 | #![cfg_attr(test, feature(is_sorted))] | |
96 | #![cfg_attr(test, feature(new_uninit))] | |
3c0e092e | 97 | #![feature(alloc_layout_extra)] |
0531ce1d | 98 | #![feature(allocator_api)] |
3dfed10e | 99 | #![feature(array_chunks)] |
064997fb | 100 | #![feature(array_into_iter_constructors)] |
1b1a35ee | 101 | #![feature(array_windows)] |
49aad941 | 102 | #![feature(ascii_char)] |
04454e1e | 103 | #![feature(assert_matches)] |
c620b35d | 104 | #![feature(async_fn_traits)] |
5099ac24 | 105 | #![feature(async_iterator)] |
1f0639a9 | 106 | #![feature(clone_to_uninit)] |
62682a34 | 107 | #![feature(coerce_unsized)] |
353b0b11 | 108 | #![feature(const_align_of_val)] |
a2a8927a | 109 | #![feature(const_box)] |
353b0b11 FG |
110 | #![feature(const_cow_is_borrowed)] |
111 | #![feature(const_eval_select)] | |
e8be2606 | 112 | #![feature(const_heap)] |
a2a8927a | 113 | #![feature(const_maybe_uninit_as_mut_ptr)] |
353b0b11 | 114 | #![feature(const_maybe_uninit_write)] |
e8be2606 | 115 | #![feature(const_option)] |
353b0b11 | 116 | #![feature(const_pin)] |
a2a8927a | 117 | #![feature(const_refs_to_cell)] |
353b0b11 FG |
118 | #![feature(const_size_of_val)] |
119 | #![feature(const_waker)] | |
62682a34 | 120 | #![feature(core_intrinsics)] |
781aab86 | 121 | #![feature(deprecated_suggestion)] |
e8be2606 | 122 | #![feature(deref_pure_trait)] |
3c0e092e | 123 | #![feature(dispatch_from_dyn)] |
2b03887a | 124 | #![feature(error_generic_member_access)] |
041b39d2 | 125 | #![feature(exact_size_is_empty)] |
f9f354fc | 126 | #![feature(extend_one)] |
1f0639a9 | 127 | #![feature(extend_one_unchecked)] |
041b39d2 | 128 | #![feature(fmt_internals)] |
9fa01778 | 129 | #![feature(fn_traits)] |
04454e1e | 130 | #![feature(hasher_prefixfree_extras)] |
1b1a35ee | 131 | #![feature(inplace_iteration)] |
c295e0f8 | 132 | #![feature(iter_advance_by)] |
064997fb | 133 | #![feature(iter_next_chunk)] |
487cf647 | 134 | #![feature(iter_repeat_n)] |
f035d41b | 135 | #![feature(layout_for_ptr)] |
c620b35d | 136 | #![feature(local_waker)] |
3c0e092e | 137 | #![feature(maybe_uninit_slice)] |
2b03887a | 138 | #![feature(maybe_uninit_uninit_array_transpose)] |
c0240ec0 | 139 | #![feature(panic_internals)] |
041b39d2 | 140 | #![feature(pattern)] |
2c00a5a8 | 141 | #![feature(ptr_internals)] |
04454e1e FG |
142 | #![feature(ptr_metadata)] |
143 | #![feature(ptr_sub_ptr)] | |
0731742a | 144 | #![feature(receiver_trait)] |
5869c6ff | 145 | #![feature(set_ptr_value)] |
2b03887a | 146 | #![feature(sized_type_properties)] |
923072b8 | 147 | #![feature(slice_from_ptr_range)] |
c620b35d | 148 | #![feature(slice_index_methods)] |
3dfed10e | 149 | #![feature(slice_ptr_get)] |
6a06907d | 150 | #![feature(slice_range)] |
353b0b11 | 151 | #![feature(std_internals)] |
041b39d2 | 152 | #![feature(str_internals)] |
5e7ed085 | 153 | #![feature(strict_provenance)] |
4b012472 | 154 | #![feature(trusted_fused)] |
041b39d2 | 155 | #![feature(trusted_len)] |
3c0e092e XL |
156 | #![feature(trusted_random_access)] |
157 | #![feature(try_trait_v2)] | |
c620b35d | 158 | #![feature(try_with_capacity)] |
9c376795 | 159 | #![feature(tuple_trait)] |
83c7162d | 160 | #![feature(unicode_internals)] |
62682a34 | 161 | #![feature(unsize)] |
31ef2f64 | 162 | #![feature(unwrap_infallible)] |
e8be2606 | 163 | #![feature(vec_pop_if)] |
353b0b11 | 164 | // tidy-alphabetical-end |
3c0e092e XL |
165 | // |
166 | // Language features: | |
353b0b11 | 167 | // tidy-alphabetical-start |
1f0639a9 | 168 | #![cfg_attr(bootstrap, feature(c_unwind))] |
ed00b5ec | 169 | #![cfg_attr(not(test), feature(coroutine_trait))] |
353b0b11 FG |
170 | #![cfg_attr(test, feature(panic_update_hook))] |
171 | #![cfg_attr(test, feature(test))] | |
3b2f2976 | 172 | #![feature(allocator_internals)] |
3c0e092e | 173 | #![feature(allow_internal_unstable)] |
3c0e092e | 174 | #![feature(cfg_sanitize)] |
a2a8927a | 175 | #![feature(const_mut_refs)] |
a2a8927a | 176 | #![feature(const_precise_live_drops)] |
353b0b11 | 177 | #![feature(const_ptr_write)] |
a2a8927a | 178 | #![feature(const_try)] |
c0240ec0 | 179 | #![feature(decl_macro)] |
3c0e092e | 180 | #![feature(dropck_eyepatch)] |
3c0e092e | 181 | #![feature(fundamental)] |
04454e1e | 182 | #![feature(hashmap_internals)] |
3c0e092e XL |
183 | #![feature(lang_items)] |
184 | #![feature(min_specialization)] | |
353b0b11 | 185 | #![feature(multiple_supertrait_upcastable)] |
3c0e092e XL |
186 | #![feature(negative_impls)] |
187 | #![feature(never_type)] | |
3c0e092e XL |
188 | #![feature(rustc_allow_const_fn_unstable)] |
189 | #![feature(rustc_attrs)] | |
04454e1e | 190 | #![feature(slice_internals)] |
3c0e092e | 191 | #![feature(staged_api)] |
923072b8 | 192 | #![feature(stmt_expr_attributes)] |
3c0e092e XL |
193 | #![feature(unboxed_closures)] |
194 | #![feature(unsized_fn_params)] | |
f2b60f7d | 195 | #![feature(with_negative_coherence)] |
31ef2f64 | 196 | #![rustc_preserve_ub_checks] |
353b0b11 | 197 | // tidy-alphabetical-end |
3c0e092e XL |
198 | // |
199 | // Rustdoc features: | |
c295e0f8 | 200 | #![feature(doc_cfg)] |
3c0e092e XL |
201 | #![feature(doc_cfg_hide)] |
202 | // Technically, this is a bug in rustdoc: rustdoc sees the documentation on `#[lang = slice_alloc]` | |
203 | // blocks is for `&[T]`, which also has documentation using this feature in `core`, and gets mad | |
204 | // that the feature-gate isn't enabled. Ideally, it wouldn't check for the feature gate for docs | |
205 | // from other crates, but since this can only appear for lang items, it doesn't seem worth fixing. | |
206 | #![feature(intra_doc_pointers)] | |
1a4d82fc | 207 | |
3c0e092e | 208 | // Allow testing this library |
b039eaaf SL |
209 | #[cfg(test)] |
210 | #[macro_use] | |
211 | extern crate std; | |
041b39d2 XL |
212 | #[cfg(test)] |
213 | extern crate test; | |
9c376795 FG |
214 | #[cfg(test)] |
215 | mod testing; | |
041b39d2 | 216 | |
476ff2be SL |
217 | // Module with internal macros used by other modules (needs to be included before other modules). |
218 | #[macro_use] | |
219 | mod macros; | |
220 | ||
3c0e092e XL |
221 | mod raw_vec; |
222 | ||
1a4d82fc JJ |
223 | // Heaps provided for low-level allocation strategies |
224 | ||
83c7162d XL |
225 | pub mod alloc; |
226 | ||
1a4d82fc JJ |
227 | // Primitive types using the heaps above |
228 | ||
c34b1796 AL |
229 | // Need to conditionally define the mod from `boxed.rs` to avoid |
230 | // duplicating the lang-items when building in test cfg; but also need | |
83c7162d | 231 | // to allow code to have `use boxed::Box;` declarations. |
1a4d82fc JJ |
232 | #[cfg(not(test))] |
233 | pub mod boxed; | |
85aaf69f | 234 | #[cfg(test)] |
b039eaaf | 235 | mod boxed { |
83c7162d | 236 | pub use std::boxed::Box; |
b039eaaf | 237 | } |
041b39d2 | 238 | pub mod borrow; |
dfeec247 | 239 | pub mod collections; |
2b03887a | 240 | #[cfg(all(not(no_rc), not(no_sync), not(no_global_oom_handling)))] |
04454e1e | 241 | pub mod ffi; |
041b39d2 | 242 | pub mod fmt; |
2b03887a | 243 | #[cfg(not(no_rc))] |
dfeec247 | 244 | pub mod rc; |
041b39d2 | 245 | pub mod slice; |
7cac9316 | 246 | pub mod str; |
041b39d2 | 247 | pub mod string; |
2b03887a | 248 | #[cfg(all(not(no_rc), not(no_sync), target_has_atomic = "ptr"))] |
dfeec247 | 249 | pub mod sync; |
c620b35d | 250 | #[cfg(all(not(no_global_oom_handling), not(no_rc), not(no_sync)))] |
ba9703b0 | 251 | pub mod task; |
dfeec247 XL |
252 | #[cfg(test)] |
253 | mod tests; | |
041b39d2 | 254 | pub mod vec; |
041b39d2 | 255 | |
e1599b0c | 256 | #[doc(hidden)] |
dfeec247 | 257 | #[unstable(feature = "liballoc_internals", issue = "none", reason = "implementation detail")] |
e1599b0c XL |
258 | pub mod __export { |
259 | pub use core::format_args; | |
1f0639a9 | 260 | pub use core::hint::must_use; |
e1599b0c | 261 | } |
9c376795 FG |
262 | |
263 | #[cfg(test)] | |
264 | #[allow(dead_code)] // Not used in all configurations | |
265 | pub(crate) mod test_helpers { | |
266 | /// Copied from `std::test_helpers::test_rng`, since these tests rely on the | |
267 | /// seed not being the same for every RNG invocation too. | |
268 | pub(crate) fn test_rng() -> rand_xorshift::XorShiftRng { | |
269 | use std::hash::{BuildHasher, Hash, Hasher}; | |
4b012472 | 270 | let mut hasher = std::hash::RandomState::new().build_hasher(); |
9c376795 FG |
271 | std::panic::Location::caller().hash(&mut hasher); |
272 | let hc64 = hasher.finish(); | |
273 | let seed_vec = | |
274 | hc64.to_le_bytes().into_iter().chain(0u8..8).collect::<crate::vec::Vec<u8>>(); | |
275 | let seed: [u8; 16] = seed_vec.as_slice().try_into().unwrap(); | |
276 | rand::SeedableRng::from_seed(seed) | |
277 | } | |
278 | } |