#
alloc/
lib.rs

    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(incomplete_features)]
    60#![allow(unused_attributes)]
    61#![stable(feature = "alloc", since = "1.36.0")]
    62#![doc(
    63    html_playground_url = "https://play.rust-lang.org/",
    64    issue_tracker_base_url = "https://github.com/rust-lang/rust/issues/",
    65    test(no_crate_inject, attr(allow(unused_variables), deny(warnings)))
    66)]
    67#![doc(cfg_hide(
    68    not(test),
    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#![warn(rustdoc::unescaped_backticks)]
    90#![deny(ffi_unwind_calls)]
    91#![warn(unreachable_pub)]
    92//
    93// Library features:
    94// tidy-alphabetical-start
    95#![feature(alloc_layout_extra)]
    96#![feature(allocator_api)]
    97#![feature(array_into_iter_constructors)]
    98#![feature(array_windows)]
    99#![feature(ascii_char)]
    100#![feature(assert_matches)]
    101#![feature(async_fn_traits)]
    102#![feature(async_iterator)]
    103#![feature(bstr)]
    104#![feature(bstr_internals)]
    105#![feature(cast_maybe_uninit)]
    106#![feature(char_internals)]
    107#![feature(char_max_len)]
    108#![feature(clone_to_uninit)]
    109#![feature(coerce_unsized)]
    110#![feature(const_default)]
    111#![feature(const_eval_select)]
    112#![feature(const_heap)]
    113#![feature(const_trait_impl)]
    114#![feature(core_intrinsics)]
    115#![feature(deprecated_suggestion)]
    116#![feature(deref_pure_trait)]
    117#![feature(dispatch_from_dyn)]
    118#![feature(ergonomic_clones)]
    119#![feature(error_generic_member_access)]
    120#![feature(exact_size_is_empty)]
    121#![feature(extend_one)]
    122#![feature(extend_one_unchecked)]
    123#![feature(fmt_internals)]
    124#![feature(fn_traits)]
    125#![feature(formatting_options)]
    126#![feature(generic_atomic)]
    127#![feature(hasher_prefixfree_extras)]
    128#![feature(inplace_iteration)]
    129#![feature(iter_advance_by)]
    130#![feature(iter_next_chunk)]
    131#![feature(layout_for_ptr)]
    132#![feature(legacy_receiver_trait)]
    133#![feature(local_waker)]
    134#![feature(maybe_uninit_slice)]
    135#![feature(maybe_uninit_uninit_array_transpose)]
    136#![feature(panic_internals)]
    137#![feature(pattern)]
    138#![feature(pin_coerce_unsized_trait)]
    139#![feature(ptr_alignment_type)]
    140#![feature(ptr_internals)]
    141#![feature(ptr_metadata)]
    142#![feature(set_ptr_value)]
    143#![feature(sized_type_properties)]
    144#![feature(slice_from_ptr_range)]
    145#![feature(slice_index_methods)]
    146#![feature(slice_iter_mut_as_mut_slice)]
    147#![feature(slice_ptr_get)]
    148#![feature(slice_range)]
    149#![feature(std_internals)]
    150#![feature(str_internals)]
    151#![feature(temporary_niche_types)]
    152#![feature(trusted_fused)]
    153#![feature(trusted_len)]
    154#![feature(trusted_random_access)]
    155#![feature(try_trait_v2)]
    156#![feature(try_with_capacity)]
    157#![feature(tuple_trait)]
    158#![feature(ub_checks)]
    159#![feature(unicode_internals)]
    160#![feature(unsize)]
    161#![feature(unwrap_infallible)]
    162// tidy-alphabetical-end
    163//
    164// Language features:
    165// tidy-alphabetical-start
    166#![feature(allocator_internals)]
    167#![feature(allow_internal_unstable)]
    168#![feature(cfg_sanitize)]
    169#![feature(const_precise_live_drops)]
    170#![feature(coroutine_trait)]
    171#![feature(decl_macro)]
    172#![feature(dropck_eyepatch)]
    173#![feature(fundamental)]
    174#![feature(hashmap_internals)]
    175#![feature(intrinsics)]
    176#![feature(lang_items)]
    177#![feature(min_specialization)]
    178#![feature(multiple_supertrait_upcastable)]
    179#![feature(negative_impls)]
    180#![feature(never_type)]
    181#![feature(optimize_attribute)]
    182#![feature(rustc_allow_const_fn_unstable)]
    183#![feature(rustc_attrs)]
    184#![feature(slice_internals)]
    185#![feature(staged_api)]
    186#![feature(stmt_expr_attributes)]
    187#![feature(strict_provenance_lints)]
    188#![feature(unboxed_closures)]
    189#![feature(unsized_fn_params)]
    190#![feature(with_negative_coherence)]
    191#![rustc_preserve_ub_checks]
    192// tidy-alphabetical-end
    193//
    194// Rustdoc features:
    195#![feature(doc_cfg)]
    196#![feature(doc_cfg_hide)]
    197// Technically, this is a bug in rustdoc: rustdoc sees the documentation on `#[lang = slice_alloc]`
    198// blocks is for `&[T]`, which also has documentation using this feature in `core`, and gets mad
    199// that the feature-gate isn't enabled. Ideally, it wouldn't check for the feature gate for docs
    200// from other crates, but since this can only appear for lang items, it doesn't seem worth fixing.
    201#![feature(intra_doc_pointers)]
    202
    203// Module with internal macros used by other modules (needs to be included before other modules).
    204#[macro_use]
    205mod macros;
    206
    207mod raw_vec;
    208
    209// Heaps provided for low-level allocation strategies
    210pub mod alloc;
    211
    212// Primitive types using the heaps above
    213
    214// Need to conditionally define the mod from `boxed.rs` to avoid
    215// duplicating the lang-items when building in test cfg; but also need
    216// to allow code to have `use boxed::Box;` declarations.
    217pub mod borrow;
    218pub mod boxed;
    219#[unstable(feature = "bstr", issue = "134915")]
    220pub mod bstr;
    221pub mod collections;
    222#[cfg(all(not(no_rc), not(no_sync), not(no_global_oom_handling)))]
    223pub mod ffi;
    224pub mod fmt;
    225#[cfg(not(no_rc))]
    226pub mod rc;
    227pub mod slice;
    228pub mod str;
    229pub mod string;
    230#[cfg(all(not(no_rc), not(no_sync), target_has_atomic = "ptr"))]
    231pub mod sync;
    232#[cfg(all(not(no_global_oom_handling), not(no_rc), not(no_sync)))]
    233pub mod task;
    234pub mod vec;
    235
    236#[doc(hidden)]
    237#[unstable(feature = "liballoc_internals", issue = "none", reason = "implementation detail")]
    238pub mod __export {
    239    pub use core::format_args;
    240    pub use core::hint::must_use;
    241}