1 | //! # The Rust core allocation and collections library |
2 | //! |
3 | //! This library provides smart pointers and collections for managing |
4 | //! heap-allocated values. |
5 | //! |
6 | //! This library, like core, normally doesn’t need to be used directly |
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. |
10 | //! |
11 | //! ## Boxed values |
12 | //! |
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. |
16 | //! |
17 | //! This type can be sent among threads efficiently as the size of a `Box` value |
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 | //! |
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. |
26 | //! |
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. |
30 | //! |
31 | //! ## Atomically reference counted pointers |
32 | //! |
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. |
37 | //! |
38 | //! This type allows for shared access to the contained data, and is often |
39 | //! paired with synchronization primitives such as mutexes to allow mutation of |
40 | //! shared resources. |
41 | //! |
42 | //! ## Collections |
43 | //! |
44 | //! Implementations of the most common general purpose data structures are |
45 | //! defined in this library. They are re-exported through the |
46 | //! [standard collections library](../std/collections/index.html). |
47 | //! |
48 | //! ## Heap interfaces |
49 | //! |
50 | //! The [`alloc`](alloc/index.html) module defines the low-level interface to the |
51 | //! default global allocator. It is not compatible with the libc allocator API. |
52 | //! |
53 | //! [`Arc`]: sync |
54 | //! [`Box`]: boxed |
55 | //! [`Cell`]: core::cell |
56 | //! [`Rc`]: rc |
57 | //! [`RefCell`]: core::cell |
58 | |
59 | #![allow (unused_attributes)] |
60 | #![stable (feature = "alloc" , since = "1.36.0" )] |
61 | #![doc ( |
62 | html_playground_url = "https://play.rust-lang.org/" , |
63 | issue_tracker_base_url = "https://github.com/rust-lang/rust/issues/" , |
64 | test(no_crate_inject, attr(allow(unused_variables), deny(warnings))) |
65 | )] |
66 | #![doc (cfg_hide( |
67 | not(test), |
68 | not(any(test, bootstrap)), |
69 | no_global_oom_handling, |
70 | not(no_global_oom_handling), |
71 | not(no_rc), |
72 | not(no_sync), |
73 | target_has_atomic = "ptr" |
74 | ))] |
75 | #![doc (rust_logo)] |
76 | #![feature (rustdoc_internals)] |
77 | #![no_std ] |
78 | #![needs_allocator ] |
79 | // Lints: |
80 | #![deny (unsafe_op_in_unsafe_fn)] |
81 | #![deny (fuzzy_provenance_casts)] |
82 | #![warn (deprecated_in_future)] |
83 | #![warn (missing_debug_implementations)] |
84 | #![warn (missing_docs)] |
85 | #![allow (explicit_outlives_requirements)] |
86 | #![warn (multiple_supertrait_upcastable)] |
87 | #![allow (internal_features)] |
88 | #![allow (rustdoc::redundant_explicit_links)] |
89 | #![deny (ffi_unwind_calls)] |
90 | // |
91 | // Library features: |
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))] |
97 | #![feature (alloc_layout_extra)] |
98 | #![feature (allocator_api)] |
99 | #![feature (array_chunks)] |
100 | #![feature (array_into_iter_constructors)] |
101 | #![feature (array_windows)] |
102 | #![feature (ascii_char)] |
103 | #![feature (assert_matches)] |
104 | #![feature (async_fn_traits)] |
105 | #![feature (async_iterator)] |
106 | #![feature (coerce_unsized)] |
107 | #![feature (const_align_of_val)] |
108 | #![feature (const_box)] |
109 | #![feature (const_cow_is_borrowed)] |
110 | #![feature (const_eval_select)] |
111 | #![feature (const_heap)] |
112 | #![feature (const_maybe_uninit_as_mut_ptr)] |
113 | #![feature (const_maybe_uninit_write)] |
114 | #![feature (const_option)] |
115 | #![feature (const_pin)] |
116 | #![feature (const_refs_to_cell)] |
117 | #![feature (const_size_of_val)] |
118 | #![feature (const_waker)] |
119 | #![feature (core_intrinsics)] |
120 | #![feature (deprecated_suggestion)] |
121 | #![feature (deref_pure_trait)] |
122 | #![feature (dispatch_from_dyn)] |
123 | #![feature (error_generic_member_access)] |
124 | #![feature (error_in_core)] |
125 | #![feature (exact_size_is_empty)] |
126 | #![feature (extend_one)] |
127 | #![feature (fmt_internals)] |
128 | #![feature (fn_traits)] |
129 | #![feature (hasher_prefixfree_extras)] |
130 | #![feature (hint_assert_unchecked)] |
131 | #![feature (inplace_iteration)] |
132 | #![feature (iter_advance_by)] |
133 | #![feature (iter_next_chunk)] |
134 | #![feature (iter_repeat_n)] |
135 | #![feature (layout_for_ptr)] |
136 | #![feature (local_waker)] |
137 | #![feature (maybe_uninit_slice)] |
138 | #![feature (maybe_uninit_uninit_array)] |
139 | #![feature (maybe_uninit_uninit_array_transpose)] |
140 | #![feature (non_null_convenience)] |
141 | #![feature (panic_internals)] |
142 | #![feature (pattern)] |
143 | #![feature (ptr_internals)] |
144 | #![feature (ptr_metadata)] |
145 | #![feature (ptr_sub_ptr)] |
146 | #![feature (receiver_trait)] |
147 | #![feature (set_ptr_value)] |
148 | #![feature (sized_type_properties)] |
149 | #![feature (slice_from_ptr_range)] |
150 | #![feature (slice_index_methods)] |
151 | #![feature (slice_ptr_get)] |
152 | #![feature (slice_range)] |
153 | #![feature (std_internals)] |
154 | #![feature (str_internals)] |
155 | #![feature (strict_provenance)] |
156 | #![feature (trusted_fused)] |
157 | #![feature (trusted_len)] |
158 | #![feature (trusted_random_access)] |
159 | #![feature (try_trait_v2)] |
160 | #![feature (try_with_capacity)] |
161 | #![feature (tuple_trait)] |
162 | #![feature (unicode_internals)] |
163 | #![feature (unsize)] |
164 | #![feature (utf8_chunks)] |
165 | #![feature (vec_pop_if)] |
166 | // tidy-alphabetical-end |
167 | // |
168 | // Language features: |
169 | // tidy-alphabetical-start |
170 | #![cfg_attr (bootstrap, feature(associated_type_bounds))] |
171 | #![cfg_attr (bootstrap, feature(inline_const))] |
172 | #![cfg_attr (not(bootstrap), rustc_preserve_ub_checks)] |
173 | #![cfg_attr (not(test), feature(coroutine_trait))] |
174 | #![cfg_attr (test, feature(panic_update_hook))] |
175 | #![cfg_attr (test, feature(test))] |
176 | #![feature (allocator_internals)] |
177 | #![feature (allow_internal_unstable)] |
178 | #![feature (c_unwind)] |
179 | #![feature (cfg_sanitize)] |
180 | #![feature (const_mut_refs)] |
181 | #![feature (const_precise_live_drops)] |
182 | #![feature (const_ptr_write)] |
183 | #![feature (const_trait_impl)] |
184 | #![feature (const_try)] |
185 | #![feature (decl_macro)] |
186 | #![feature (dropck_eyepatch)] |
187 | #![feature (exclusive_range_pattern)] |
188 | #![feature (fundamental)] |
189 | #![feature (hashmap_internals)] |
190 | #![feature (lang_items)] |
191 | #![feature (min_specialization)] |
192 | #![feature (multiple_supertrait_upcastable)] |
193 | #![feature (negative_impls)] |
194 | #![feature (never_type)] |
195 | #![feature (rustc_allow_const_fn_unstable)] |
196 | #![feature (rustc_attrs)] |
197 | #![feature (slice_internals)] |
198 | #![feature (staged_api)] |
199 | #![feature (stmt_expr_attributes)] |
200 | #![feature (unboxed_closures)] |
201 | #![feature (unsized_fn_params)] |
202 | #![feature (with_negative_coherence)] |
203 | // tidy-alphabetical-end |
204 | // |
205 | // Rustdoc features: |
206 | #![feature (doc_cfg)] |
207 | #![feature (doc_cfg_hide)] |
208 | // Technically, this is a bug in rustdoc: rustdoc sees the documentation on `#[lang = slice_alloc]` |
209 | // blocks is for `&[T]`, which also has documentation using this feature in `core`, and gets mad |
210 | // that the feature-gate isn't enabled. Ideally, it wouldn't check for the feature gate for docs |
211 | // from other crates, but since this can only appear for lang items, it doesn't seem worth fixing. |
212 | #![feature (intra_doc_pointers)] |
213 | |
214 | // Allow testing this library |
215 | #[cfg (test)] |
216 | #[macro_use ] |
217 | extern crate std; |
218 | #[cfg (test)] |
219 | extern crate test; |
220 | #[cfg (test)] |
221 | mod testing; |
222 | |
223 | // Module with internal macros used by other modules (needs to be included before other modules). |
224 | #[macro_use ] |
225 | mod macros; |
226 | |
227 | mod raw_vec; |
228 | |
229 | // Heaps provided for low-level allocation strategies |
230 | |
231 | pub mod alloc; |
232 | |
233 | // Primitive types using the heaps above |
234 | |
235 | // Need to conditionally define the mod from `boxed.rs` to avoid |
236 | // duplicating the lang-items when building in test cfg; but also need |
237 | // to allow code to have `use boxed::Box;` declarations. |
238 | #[cfg (not(test))] |
239 | pub mod boxed; |
240 | #[cfg (test)] |
241 | mod boxed { |
242 | pub use std::boxed::Box; |
243 | } |
244 | pub mod borrow; |
245 | pub mod collections; |
246 | #[cfg (all(not(no_rc), not(no_sync), not(no_global_oom_handling)))] |
247 | pub mod ffi; |
248 | pub mod fmt; |
249 | #[cfg (not(no_rc))] |
250 | pub mod rc; |
251 | pub mod slice; |
252 | pub mod str; |
253 | pub mod string; |
254 | #[cfg (all(not(no_rc), not(no_sync), target_has_atomic = "ptr" ))] |
255 | pub mod sync; |
256 | #[cfg (all(not(no_global_oom_handling), not(no_rc), not(no_sync)))] |
257 | pub mod task; |
258 | #[cfg (test)] |
259 | mod tests; |
260 | pub mod vec; |
261 | |
262 | #[doc (hidden)] |
263 | #[unstable (feature = "liballoc_internals" , issue = "none" , reason = "implementation detail" )] |
264 | pub mod __export { |
265 | pub use core::format_args; |
266 | } |
267 | |
268 | #[cfg (test)] |
269 | #[allow (dead_code)] // Not used in all configurations |
270 | pub(crate) mod test_helpers { |
271 | /// Copied from `std::test_helpers::test_rng`, since these tests rely on the |
272 | /// seed not being the same for every RNG invocation too. |
273 | pub(crate) fn test_rng() -> rand_xorshift::XorShiftRng { |
274 | use std::hash::{BuildHasher, Hash, Hasher}; |
275 | let mut hasher = std::hash::RandomState::new().build_hasher(); |
276 | std::panic::Location::caller().hash(&mut hasher); |
277 | let hc64 = hasher.finish(); |
278 | let seed_vec = |
279 | hc64.to_le_bytes().into_iter().chain(0u8..8).collect::<crate::vec::Vec<u8>>(); |
280 | let seed: [u8; 16] = seed_vec.as_slice().try_into().unwrap(); |
281 | rand::SeedableRng::from_seed(seed) |
282 | } |
283 | } |
284 | |