|
| 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 libcore, 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 | +// To run liballoc tests without x.py without ending up with two copies of liballoc, Miri needs to be |
| 60 | +// able to "empty" this crate. See <https://github.com/rust-lang/miri-test-libstd/issues/4>. |
| 61 | +// rustc itself never sets the feature, so this line has no affect there. |
| 62 | +#![cfg(any(not(feature = "miri-test-libstd"), test, doctest))] |
| 63 | +#![allow(unused_attributes)] |
| 64 | +#![stable(feature = "alloc", since = "1.36.0")] |
| 65 | +#![doc( |
| 66 | + html_playground_url = "https://play.rust-lang.org/", |
| 67 | + issue_tracker_base_url = "https://github.com/rust-lang/rust/issues/", |
| 68 | + test(no_crate_inject, attr(allow(unused_variables), deny(warnings))) |
| 69 | +)] |
| 70 | +#![doc(cfg_hide( |
| 71 | + not(test), |
| 72 | + not(any(test, bootstrap)), |
| 73 | + any(not(feature = "miri-test-libstd"), test, doctest), |
| 74 | + no_global_oom_handling, |
| 75 | + not(no_global_oom_handling), |
| 76 | + target_has_atomic = "ptr" |
| 77 | +))] |
| 78 | +#![no_std] |
| 79 | +#![needs_allocator] |
| 80 | +// |
| 81 | +// Lints: |
| 82 | +#![deny(unsafe_op_in_unsafe_fn)] |
| 83 | +#![warn(deprecated_in_future)] |
| 84 | +#![warn(missing_debug_implementations)] |
| 85 | +#![warn(missing_docs)] |
| 86 | +#![allow(explicit_outlives_requirements)] |
| 87 | +// |
| 88 | +// Library features: |
| 89 | +#![cfg_attr(not(no_global_oom_handling), feature(alloc_c_string))] |
| 90 | +#![feature(alloc_layout_extra)] |
| 91 | +#![feature(allocator_api)] |
| 92 | +#![feature(array_chunks)] |
| 93 | +#![feature(array_methods)] |
| 94 | +#![feature(array_windows)] |
| 95 | +#![feature(assert_matches)] |
| 96 | +#![feature(async_iterator)] |
| 97 | +#![feature(coerce_unsized)] |
| 98 | +#![cfg_attr(not(no_global_oom_handling), feature(const_alloc_error))] |
| 99 | +#![feature(const_box)] |
| 100 | +#![cfg_attr(not(no_global_oom_handling), feature(const_btree_new))] |
| 101 | +#![feature(const_cow_is_borrowed)] |
| 102 | +#![feature(const_convert)] |
| 103 | +#![feature(const_size_of_val)] |
| 104 | +#![feature(const_align_of_val)] |
| 105 | +#![feature(const_ptr_read)] |
| 106 | +#![feature(const_maybe_uninit_write)] |
| 107 | +#![feature(const_maybe_uninit_as_mut_ptr)] |
| 108 | +#![feature(const_refs_to_cell)] |
| 109 | +#![feature(core_c_str)] |
| 110 | +#![feature(core_intrinsics)] |
| 111 | +#![feature(core_ffi_c)] |
| 112 | +#![feature(const_eval_select)] |
| 113 | +#![feature(const_pin)] |
| 114 | +#![feature(cstr_from_bytes_until_nul)] |
| 115 | +#![feature(dispatch_from_dyn)] |
| 116 | +#![feature(exact_size_is_empty)] |
| 117 | +#![feature(extend_one)] |
| 118 | +#![feature(fmt_internals)] |
| 119 | +#![feature(fn_traits)] |
| 120 | +#![feature(hasher_prefixfree_extras)] |
| 121 | +#![feature(inplace_iteration)] |
| 122 | +#![feature(iter_advance_by)] |
| 123 | +#![feature(layout_for_ptr)] |
| 124 | +#![feature(maybe_uninit_slice)] |
| 125 | +#![cfg_attr(test, feature(new_uninit))] |
| 126 | +#![feature(nonnull_slice_from_raw_parts)] |
| 127 | +#![feature(pattern)] |
| 128 | +#![feature(ptr_internals)] |
| 129 | +#![feature(ptr_metadata)] |
| 130 | +#![feature(ptr_sub_ptr)] |
| 131 | +#![feature(receiver_trait)] |
| 132 | +#![feature(set_ptr_value)] |
| 133 | +#![feature(slice_group_by)] |
| 134 | +#![feature(slice_ptr_get)] |
| 135 | +#![feature(slice_ptr_len)] |
| 136 | +#![feature(slice_range)] |
| 137 | +#![feature(str_internals)] |
| 138 | +#![feature(strict_provenance)] |
| 139 | +#![feature(trusted_len)] |
| 140 | +#![feature(trusted_random_access)] |
| 141 | +#![feature(try_trait_v2)] |
| 142 | +#![feature(unchecked_math)] |
| 143 | +#![feature(unicode_internals)] |
| 144 | +#![feature(unsize)] |
| 145 | +// |
| 146 | +// Language features: |
| 147 | +#![feature(allocator_internals)] |
| 148 | +#![feature(allow_internal_unstable)] |
| 149 | +#![feature(associated_type_bounds)] |
| 150 | +#![feature(box_syntax)] |
| 151 | +#![feature(cfg_sanitize)] |
| 152 | +#![feature(const_deref)] |
| 153 | +#![feature(const_mut_refs)] |
| 154 | +#![feature(const_ptr_write)] |
| 155 | +#![feature(const_precise_live_drops)] |
| 156 | +#![feature(const_trait_impl)] |
| 157 | +#![feature(const_try)] |
| 158 | +#![feature(dropck_eyepatch)] |
| 159 | +#![feature(exclusive_range_pattern)] |
| 160 | +#![feature(fundamental)] |
| 161 | +#![cfg_attr(not(test), feature(generator_trait))] |
| 162 | +#![feature(hashmap_internals)] |
| 163 | +#![feature(lang_items)] |
| 164 | +#![feature(let_else)] |
| 165 | +#![feature(min_specialization)] |
| 166 | +#![feature(negative_impls)] |
| 167 | +#![feature(never_type)] |
| 168 | +#![feature(nll)] // Not necessary, but here to test the `nll` feature. |
| 169 | +#![feature(rustc_allow_const_fn_unstable)] |
| 170 | +#![feature(rustc_attrs)] |
| 171 | +#![feature(slice_internals)] |
| 172 | +#![feature(staged_api)] |
| 173 | +#![cfg_attr(test, feature(test))] |
| 174 | +#![feature(unboxed_closures)] |
| 175 | +#![feature(unsized_fn_params)] |
| 176 | +#![feature(c_unwind)] |
| 177 | +// |
| 178 | +// Rustdoc features: |
| 179 | +#![feature(doc_cfg)] |
| 180 | +#![feature(doc_cfg_hide)] |
| 181 | +// Technically, this is a bug in rustdoc: rustdoc sees the documentation on `#[lang = slice_alloc]` |
| 182 | +// blocks is for `&[T]`, which also has documentation using this feature in `core`, and gets mad |
| 183 | +// that the feature-gate isn't enabled. Ideally, it wouldn't check for the feature gate for docs |
| 184 | +// from other crates, but since this can only appear for lang items, it doesn't seem worth fixing. |
| 185 | +#![feature(intra_doc_pointers)] |
| 186 | + |
| 187 | +// Allow testing this library |
| 188 | +#[cfg(test)] |
| 189 | +#[macro_use] |
| 190 | +extern crate std; |
| 191 | +#[cfg(test)] |
| 192 | +extern crate test; |
| 193 | + |
| 194 | +// Module with internal macros used by other modules (needs to be included before other modules). |
| 195 | +#[macro_use] |
| 196 | +mod macros; |
| 197 | + |
| 198 | +mod raw_vec; |
| 199 | + |
| 200 | +// Heaps provided for low-level allocation strategies |
| 201 | + |
| 202 | +pub mod alloc; |
| 203 | + |
| 204 | +// Primitive types using the heaps above |
| 205 | + |
| 206 | +// Need to conditionally define the mod from `boxed.rs` to avoid |
| 207 | +// duplicating the lang-items when building in test cfg; but also need |
| 208 | +// to allow code to have `use boxed::Box;` declarations. |
| 209 | +#[cfg(not(test))] |
| 210 | +pub mod boxed; |
| 211 | +#[cfg(test)] |
| 212 | +mod boxed { |
| 213 | + pub use std::boxed::Box; |
| 214 | +} |
| 215 | +pub mod borrow; |
| 216 | +pub mod collections; |
| 217 | +#[cfg(not(no_global_oom_handling))] |
| 218 | +pub mod ffi; |
| 219 | +pub mod fmt; |
| 220 | +pub mod rc; |
| 221 | +pub mod slice; |
| 222 | +pub mod str; |
| 223 | +pub mod string; |
| 224 | +#[cfg(target_has_atomic = "ptr")] |
| 225 | +pub mod sync; |
| 226 | +#[cfg(all(not(no_global_oom_handling), target_has_atomic = "ptr"))] |
| 227 | +pub mod task; |
| 228 | +#[cfg(test)] |
| 229 | +mod tests; |
| 230 | +pub mod vec; |
| 231 | + |
| 232 | +#[doc(hidden)] |
| 233 | +#[unstable(feature = "liballoc_internals", issue = "none", reason = "implementation detail")] |
| 234 | +pub mod __export { |
| 235 | + pub use core::format_args; |
| 236 | +} |
0 commit comments