]>
Commit | Line | Data |
---|---|---|
1a4d82fc JJ |
1 | // Copyright 2014 The Rust Project Developers. See the COPYRIGHT |
2 | // file at the top-level directory of this distribution and at | |
3 | // http://rust-lang.org/COPYRIGHT. | |
4 | // | |
5 | // Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or | |
6 | // http://www.apache.org/licenses/LICENSE-2.0> or the MIT license | |
7 | // <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your | |
8 | // option. This file may not be copied, modified, or distributed | |
9 | // except according to those terms. | |
10 | ||
11 | //! # The Rust core allocation library | |
12 | //! | |
13 | //! This is the lowest level library through which allocation in Rust can be | |
14 | //! performed. | |
15 | //! | |
16 | //! This library, like libcore, is not intended for general usage, but rather as | |
17 | //! a building block of other libraries. The types and interfaces in this | |
18 | //! library are reexported through the [standard library](../std/index.html), | |
19 | //! and should not be used through this library. | |
20 | //! | |
21 | //! Currently, there are four major definitions in this library. | |
22 | //! | |
23 | //! ## Boxed values | |
24 | //! | |
62682a34 SL |
25 | //! The [`Box`](boxed/index.html) type is a smart pointer type. There can |
26 | //! only be one owner of a `Box`, and the owner can decide to mutate the | |
27 | //! contents, which live on the heap. | |
1a4d82fc | 28 | //! |
bd371182 | 29 | //! This type can be sent among threads efficiently as the size of a `Box` value |
1a4d82fc JJ |
30 | //! is the same as that of a pointer. Tree-like data structures are often built |
31 | //! with boxes because each node often has only one owner, the parent. | |
32 | //! | |
33 | //! ## Reference counted pointers | |
34 | //! | |
35 | //! The [`Rc`](rc/index.html) type is a non-threadsafe reference-counted pointer | |
bd371182 | 36 | //! type intended for sharing memory within a thread. An `Rc` pointer wraps a |
1a4d82fc JJ |
37 | //! type, `T`, and only allows access to `&T`, a shared reference. |
38 | //! | |
39 | //! This type is useful when inherited mutability (such as using `Box`) is too | |
40 | //! constraining for an application, and is often paired with the `Cell` or | |
41 | //! `RefCell` types in order to allow mutation. | |
42 | //! | |
43 | //! ## Atomically reference counted pointers | |
44 | //! | |
45 | //! The [`Arc`](arc/index.html) type is the threadsafe equivalent of the `Rc` | |
46 | //! type. It provides all the same functionality of `Rc`, except it requires | |
47 | //! that the contained type `T` is shareable. Additionally, `Arc<T>` is itself | |
48 | //! sendable while `Rc<T>` is not. | |
49 | //! | |
50 | //! This types allows for shared access to the contained data, and is often | |
51 | //! paired with synchronization primitives such as mutexes to allow mutation of | |
52 | //! shared resources. | |
53 | //! | |
54 | //! ## Heap interfaces | |
55 | //! | |
56 | //! The [`heap`](heap/index.html) module defines the low-level interface to the | |
57 | //! default global allocator. It is not compatible with the libc allocator API. | |
58 | ||
c34b1796 AL |
59 | // Do not remove on snapshot creation. Needed for bootstrap. (Issue #22364) |
60 | #![cfg_attr(stage0, feature(custom_attribute))] | |
1a4d82fc | 61 | #![crate_name = "alloc"] |
1a4d82fc | 62 | #![crate_type = "rlib"] |
92a42be0 | 63 | #![cfg_attr(stage0, staged_api)] |
e9174d1e | 64 | #![allow(unused_attributes)] |
62682a34 SL |
65 | #![unstable(feature = "alloc", |
66 | reason = "this library is unlikely to be stabilized in its current \ | |
e9174d1e SL |
67 | form or name", |
68 | issue = "27783")] | |
69 | #![doc(html_logo_url = "https://www.rust-lang.org/logos/rust-logo-128x128-blk-v2.png", | |
62682a34 | 70 | html_favicon_url = "https://doc.rust-lang.org/favicon.ico", |
e9174d1e SL |
71 | html_root_url = "https://doc.rust-lang.org/nightly/", |
72 | issue_tracker_base_url = "https://github.com/rust-lang/rust/issues/", | |
92a42be0 | 73 | test(no_crate_inject, attr(allow(unused_variables), deny(warnings))))] |
1a4d82fc | 74 | #![no_std] |
e9174d1e | 75 | #![cfg_attr(not(stage0), needs_allocator)] |
62682a34 | 76 | |
92a42be0 SL |
77 | #![cfg_attr(stage0, feature(rustc_attrs))] |
78 | #![cfg_attr(stage0, feature(no_std))] | |
79 | #![cfg_attr(stage0, allow(unused_attributes))] | |
c34b1796 | 80 | #![feature(allocator)] |
62682a34 SL |
81 | #![feature(box_syntax)] |
82 | #![feature(coerce_unsized)] | |
62682a34 | 83 | #![feature(core_intrinsics)] |
c34b1796 AL |
84 | #![feature(custom_attribute)] |
85 | #![feature(fundamental)] | |
d9579d0f | 86 | #![feature(lang_items)] |
62682a34 | 87 | #![feature(nonzero)] |
e9174d1e | 88 | #![feature(num_bits_bytes)] |
85aaf69f | 89 | #![feature(optin_builtin_traits)] |
c1a9b12d SL |
90 | #![feature(placement_in_syntax)] |
91 | #![feature(placement_new_protocol)] | |
62682a34 | 92 | #![feature(raw)] |
b039eaaf | 93 | #![feature(shared)] |
62682a34 | 94 | #![feature(staged_api)] |
85aaf69f | 95 | #![feature(unboxed_closures)] |
c34b1796 | 96 | #![feature(unique)] |
62682a34 | 97 | #![feature(unsafe_no_drop_flag, filling_drop)] |
b039eaaf SL |
98 | // SNAP 1af31d4 |
99 | #![allow(unused_features)] | |
100 | // SNAP 1af31d4 | |
101 | #![allow(unused_attributes)] | |
102 | #![feature(dropck_parametricity)] | |
62682a34 | 103 | #![feature(unsize)] |
92a42be0 SL |
104 | #![feature(drop_in_place)] |
105 | #![feature(fn_traits)] | |
106 | ||
e9174d1e SL |
107 | #![cfg_attr(stage0, feature(alloc_system))] |
108 | #![cfg_attr(not(stage0), feature(needs_allocator))] | |
62682a34 | 109 | |
b039eaaf | 110 | #![cfg_attr(test, feature(test, rustc_private, box_heap))] |
85aaf69f | 111 | |
e9174d1e SL |
112 | #[cfg(stage0)] |
113 | extern crate alloc_system; | |
1a4d82fc JJ |
114 | |
115 | // Allow testing this library | |
116 | ||
b039eaaf SL |
117 | #[cfg(test)] |
118 | #[macro_use] | |
119 | extern crate std; | |
120 | #[cfg(test)] | |
121 | #[macro_use] | |
122 | extern crate log; | |
1a4d82fc JJ |
123 | |
124 | // Heaps provided for low-level allocation strategies | |
125 | ||
126 | pub mod heap; | |
127 | ||
128 | // Primitive types using the heaps above | |
129 | ||
c34b1796 AL |
130 | // Need to conditionally define the mod from `boxed.rs` to avoid |
131 | // duplicating the lang-items when building in test cfg; but also need | |
132 | // to allow code to have `use boxed::HEAP;` | |
133 | // and `use boxed::Box;` declarations. | |
1a4d82fc JJ |
134 | #[cfg(not(test))] |
135 | pub mod boxed; | |
85aaf69f | 136 | #[cfg(test)] |
b039eaaf SL |
137 | mod boxed { |
138 | pub use std::boxed::{Box, HEAP}; | |
139 | } | |
c34b1796 | 140 | #[cfg(test)] |
85aaf69f | 141 | mod boxed_test; |
1a4d82fc JJ |
142 | pub mod arc; |
143 | pub mod rc; | |
c1a9b12d | 144 | pub mod raw_vec; |
1a4d82fc JJ |
145 | |
146 | /// Common out-of-memory routine | |
147 | #[cold] | |
148 | #[inline(never)] | |
e9174d1e SL |
149 | #[unstable(feature = "oom", reason = "not a scrutinized interface", |
150 | issue = "27700")] | |
1a4d82fc JJ |
151 | pub fn oom() -> ! { |
152 | // FIXME(#14674): This really needs to do something other than just abort | |
153 | // here, but any printing done must be *guaranteed* to not | |
154 | // allocate. | |
155 | unsafe { core::intrinsics::abort() } | |
156 | } |