Commit | Line | Data |
---|---|---|
057b8d25 MO |
1 | // SPDX-License-Identifier: Apache-2.0 OR MIT |
2 | ||
753dece8 MO |
3 | //! # The Rust core allocation and collections library |
4 | //! | |
5 | //! This library provides smart pointers and collections for managing | |
6 | //! heap-allocated values. | |
7 | //! | |
8 | //! This library, like libcore, normally doesn’t need to be used directly | |
9 | //! since its contents are re-exported in the [`std` crate](../std/index.html). | |
10 | //! Crates that use the `#![no_std]` attribute however will typically | |
11 | //! not depend on `std`, so they’d use this crate instead. | |
12 | //! | |
13 | //! ## Boxed values | |
14 | //! | |
15 | //! The [`Box`] type is a smart pointer type. There can only be one owner of a | |
16 | //! [`Box`], and the owner can decide to mutate the contents, which live on the | |
17 | //! heap. | |
18 | //! | |
19 | //! This type can be sent among threads efficiently as the size of a `Box` value | |
20 | //! is the same as that of a pointer. Tree-like data structures are often built | |
21 | //! with boxes because each node often has only one owner, the parent. | |
22 | //! | |
23 | //! ## Reference counted pointers | |
24 | //! | |
25 | //! The [`Rc`] type is a non-threadsafe reference-counted pointer type intended | |
26 | //! for sharing memory within a thread. An [`Rc`] pointer wraps a type, `T`, and | |
27 | //! only allows access to `&T`, a shared reference. | |
28 | //! | |
29 | //! This type is useful when inherited mutability (such as using [`Box`]) is too | |
30 | //! constraining for an application, and is often paired with the [`Cell`] or | |
31 | //! [`RefCell`] types in order to allow mutation. | |
32 | //! | |
33 | //! ## Atomically reference counted pointers | |
34 | //! | |
35 | //! The [`Arc`] type is the threadsafe equivalent of the [`Rc`] type. It | |
36 | //! provides all the same functionality of [`Rc`], except it requires that the | |
37 | //! contained type `T` is shareable. Additionally, [`Arc<T>`][`Arc`] is itself | |
38 | //! sendable while [`Rc<T>`][`Rc`] is not. | |
39 | //! | |
40 | //! This type allows for shared access to the contained data, and is often | |
41 | //! paired with synchronization primitives such as mutexes to allow mutation of | |
42 | //! shared resources. | |
43 | //! | |
44 | //! ## Collections | |
45 | //! | |
46 | //! Implementations of the most common general purpose data structures are | |
47 | //! defined in this library. They are re-exported through the | |
48 | //! [standard collections library](../std/collections/index.html). | |
49 | //! | |
50 | //! ## Heap interfaces | |
51 | //! | |
52 | //! The [`alloc`](alloc/index.html) module defines the low-level interface to the | |
53 | //! default global allocator. It is not compatible with the libc allocator API. | |
54 | //! | |
55 | //! [`Arc`]: sync | |
56 | //! [`Box`]: boxed | |
57 | //! [`Cell`]: core::cell | |
58 | //! [`Rc`]: rc | |
59 | //! [`RefCell`]: core::cell | |
60 | ||
61 | // To run liballoc tests without x.py without ending up with two copies of liballoc, Miri needs to be | |
62 | // able to "empty" this crate. See <https://github.com/rust-lang/miri-test-libstd/issues/4>. | |
63 | // rustc itself never sets the feature, so this line has no affect there. | |
64 | #![cfg(any(not(feature = "miri-test-libstd"), test, doctest))] | |
65 | #![allow(unused_attributes)] | |
66 | #![stable(feature = "alloc", since = "1.36.0")] | |
67 | #![doc( | |
68 | html_playground_url = "https://play.rust-lang.org/", | |
69 | issue_tracker_base_url = "https://github.com/rust-lang/rust/issues/", | |
70 | test(no_crate_inject, attr(allow(unused_variables), deny(warnings))) | |
71 | )] | |
72 | #![doc(cfg_hide( | |
73 | not(test), | |
74 | not(any(test, bootstrap)), | |
75 | any(not(feature = "miri-test-libstd"), test, doctest), | |
76 | no_global_oom_handling, | |
77 | not(no_global_oom_handling), | |
78 | target_has_atomic = "ptr" | |
79 | ))] | |
80 | #![no_std] | |
81 | #![needs_allocator] | |
82 | // | |
83 | // Lints: | |
84 | #![deny(unsafe_op_in_unsafe_fn)] | |
85 | #![warn(deprecated_in_future)] | |
86 | #![warn(missing_debug_implementations)] | |
87 | #![warn(missing_docs)] | |
88 | #![allow(explicit_outlives_requirements)] | |
89 | // | |
90 | // Library features: | |
91 | #![cfg_attr(not(no_global_oom_handling), feature(alloc_c_string))] | |
92 | #![feature(alloc_layout_extra)] | |
93 | #![feature(allocator_api)] | |
94 | #![feature(array_chunks)] | |
95 | #![feature(array_methods)] | |
96 | #![feature(array_windows)] | |
97 | #![feature(assert_matches)] | |
98 | #![feature(async_iterator)] | |
99 | #![feature(coerce_unsized)] | |
100 | #![cfg_attr(not(no_global_oom_handling), feature(const_alloc_error))] | |
101 | #![feature(const_box)] | |
102 | #![cfg_attr(not(no_global_oom_handling), feature(const_btree_new))] | |
8909a80e | 103 | #![cfg_attr(not(no_borrow), feature(const_cow_is_borrowed))] |
753dece8 MO |
104 | #![feature(const_convert)] |
105 | #![feature(const_size_of_val)] | |
106 | #![feature(const_align_of_val)] | |
107 | #![feature(const_ptr_read)] | |
108 | #![feature(const_maybe_uninit_write)] | |
109 | #![feature(const_maybe_uninit_as_mut_ptr)] | |
110 | #![feature(const_refs_to_cell)] | |
111 | #![feature(core_c_str)] | |
112 | #![feature(core_intrinsics)] | |
113 | #![feature(core_ffi_c)] | |
114 | #![feature(const_eval_select)] | |
115 | #![feature(const_pin)] | |
116 | #![feature(cstr_from_bytes_until_nul)] | |
117 | #![feature(dispatch_from_dyn)] | |
118 | #![feature(exact_size_is_empty)] | |
119 | #![feature(extend_one)] | |
120 | #![feature(fmt_internals)] | |
121 | #![feature(fn_traits)] | |
122 | #![feature(hasher_prefixfree_extras)] | |
123 | #![feature(inplace_iteration)] | |
124 | #![feature(iter_advance_by)] | |
125 | #![feature(layout_for_ptr)] | |
126 | #![feature(maybe_uninit_slice)] | |
127 | #![cfg_attr(test, feature(new_uninit))] | |
128 | #![feature(nonnull_slice_from_raw_parts)] | |
129 | #![feature(pattern)] | |
130 | #![feature(ptr_internals)] | |
131 | #![feature(ptr_metadata)] | |
132 | #![feature(ptr_sub_ptr)] | |
133 | #![feature(receiver_trait)] | |
134 | #![feature(set_ptr_value)] | |
135 | #![feature(slice_group_by)] | |
136 | #![feature(slice_ptr_get)] | |
137 | #![feature(slice_ptr_len)] | |
138 | #![feature(slice_range)] | |
139 | #![feature(str_internals)] | |
140 | #![feature(strict_provenance)] | |
141 | #![feature(trusted_len)] | |
142 | #![feature(trusted_random_access)] | |
143 | #![feature(try_trait_v2)] | |
144 | #![feature(unchecked_math)] | |
145 | #![feature(unicode_internals)] | |
146 | #![feature(unsize)] | |
147 | // | |
148 | // Language features: | |
149 | #![feature(allocator_internals)] | |
150 | #![feature(allow_internal_unstable)] | |
151 | #![feature(associated_type_bounds)] | |
152 | #![feature(box_syntax)] | |
153 | #![feature(cfg_sanitize)] | |
154 | #![feature(const_deref)] | |
155 | #![feature(const_mut_refs)] | |
156 | #![feature(const_ptr_write)] | |
157 | #![feature(const_precise_live_drops)] | |
158 | #![feature(const_trait_impl)] | |
159 | #![feature(const_try)] | |
160 | #![feature(dropck_eyepatch)] | |
161 | #![feature(exclusive_range_pattern)] | |
162 | #![feature(fundamental)] | |
163 | #![cfg_attr(not(test), feature(generator_trait))] | |
164 | #![feature(hashmap_internals)] | |
165 | #![feature(lang_items)] | |
166 | #![feature(let_else)] | |
167 | #![feature(min_specialization)] | |
168 | #![feature(negative_impls)] | |
169 | #![feature(never_type)] | |
170 | #![feature(nll)] // Not necessary, but here to test the `nll` feature. | |
171 | #![feature(rustc_allow_const_fn_unstable)] | |
172 | #![feature(rustc_attrs)] | |
173 | #![feature(slice_internals)] | |
174 | #![feature(staged_api)] | |
175 | #![cfg_attr(test, feature(test))] | |
176 | #![feature(unboxed_closures)] | |
177 | #![feature(unsized_fn_params)] | |
178 | #![feature(c_unwind)] | |
179 | // | |
180 | // Rustdoc features: | |
181 | #![feature(doc_cfg)] | |
182 | #![feature(doc_cfg_hide)] | |
183 | // Technically, this is a bug in rustdoc: rustdoc sees the documentation on `#[lang = slice_alloc]` | |
184 | // blocks is for `&[T]`, which also has documentation using this feature in `core`, and gets mad | |
185 | // that the feature-gate isn't enabled. Ideally, it wouldn't check for the feature gate for docs | |
186 | // from other crates, but since this can only appear for lang items, it doesn't seem worth fixing. | |
187 | #![feature(intra_doc_pointers)] | |
188 | ||
189 | // Allow testing this library | |
190 | #[cfg(test)] | |
191 | #[macro_use] | |
192 | extern crate std; | |
193 | #[cfg(test)] | |
194 | extern crate test; | |
195 | ||
196 | // Module with internal macros used by other modules (needs to be included before other modules). | |
057b8d25 | 197 | #[cfg(not(no_macros))] |
753dece8 MO |
198 | #[macro_use] |
199 | mod macros; | |
200 | ||
201 | mod raw_vec; | |
202 | ||
203 | // Heaps provided for low-level allocation strategies | |
204 | ||
205 | pub mod alloc; | |
206 | ||
207 | // Primitive types using the heaps above | |
208 | ||
209 | // Need to conditionally define the mod from `boxed.rs` to avoid | |
210 | // duplicating the lang-items when building in test cfg; but also need | |
211 | // to allow code to have `use boxed::Box;` declarations. | |
212 | #[cfg(not(test))] | |
213 | pub mod boxed; | |
214 | #[cfg(test)] | |
215 | mod boxed { | |
216 | pub use std::boxed::Box; | |
217 | } | |
8909a80e | 218 | #[cfg(not(no_borrow))] |
753dece8 MO |
219 | pub mod borrow; |
220 | pub mod collections; | |
221 | #[cfg(not(no_global_oom_handling))] | |
222 | pub mod ffi; | |
057b8d25 | 223 | #[cfg(not(no_fmt))] |
753dece8 | 224 | pub mod fmt; |
057b8d25 | 225 | #[cfg(not(no_rc))] |
753dece8 MO |
226 | pub mod rc; |
227 | pub mod slice; | |
057b8d25 | 228 | #[cfg(not(no_str))] |
753dece8 | 229 | pub mod str; |
057b8d25 | 230 | #[cfg(not(no_string))] |
753dece8 | 231 | pub mod string; |
057b8d25 | 232 | #[cfg(not(no_sync))] |
753dece8 MO |
233 | #[cfg(target_has_atomic = "ptr")] |
234 | pub mod sync; | |
235 | #[cfg(all(not(no_global_oom_handling), target_has_atomic = "ptr"))] | |
236 | pub mod task; | |
237 | #[cfg(test)] | |
238 | mod tests; | |
239 | pub mod vec; | |
240 | ||
241 | #[doc(hidden)] | |
242 | #[unstable(feature = "liballoc_internals", issue = "none", reason = "implementation detail")] | |
243 | pub mod __export { | |
244 | pub use core::format_args; | |
245 | } |