]>
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 | //! | |
25 | //! The [`Box`](boxed/index.html) type is the core owned pointer type in Rust. | |
26 | //! There can only be one owner of a `Box`, and the owner can decide to mutate | |
27 | //! the contents, which live on the heap. | |
28 | //! | |
29 | //! This type can be sent among tasks efficiently as the size of a `Box` value | |
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 | |
36 | //! type intended for sharing memory within a task. An `Rc` pointer wraps a | |
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"] |
85aaf69f SL |
62 | #![unstable(feature = "alloc")] |
63 | #![feature(staged_api)] | |
1a4d82fc JJ |
64 | #![staged_api] |
65 | #![crate_type = "rlib"] | |
66 | #![doc(html_logo_url = "http://www.rust-lang.org/logos/rust-logo-128x128-blk-v2.png", | |
67 | html_favicon_url = "http://www.rust-lang.org/favicon.ico", | |
68 | html_root_url = "http://doc.rust-lang.org/nightly/")] | |
c34b1796 | 69 | #![doc(test(no_crate_inject))] |
1a4d82fc | 70 | |
85aaf69f | 71 | #![feature(no_std)] |
1a4d82fc | 72 | #![no_std] |
c34b1796 AL |
73 | #![feature(allocator)] |
74 | #![feature(custom_attribute)] | |
75 | #![feature(fundamental)] | |
1a4d82fc JJ |
76 | #![feature(lang_items, unsafe_destructor)] |
77 | #![feature(box_syntax)] | |
85aaf69f SL |
78 | #![feature(optin_builtin_traits)] |
79 | #![feature(unboxed_closures)] | |
c34b1796 | 80 | #![feature(unsafe_no_drop_flag, filling_drop)] |
85aaf69f | 81 | #![feature(core)] |
c34b1796 AL |
82 | #![feature(unique)] |
83 | #![cfg_attr(test, feature(test, alloc, rustc_private))] | |
85aaf69f SL |
84 | #![cfg_attr(all(not(feature = "external_funcs"), not(feature = "external_crate")), |
85 | feature(libc))] | |
86 | ||
1a4d82fc JJ |
87 | |
88 | #[macro_use] | |
89 | extern crate core; | |
90 | ||
91 | #[cfg(all(not(feature = "external_funcs"), not(feature = "external_crate")))] | |
92 | extern crate libc; | |
93 | ||
94 | // Allow testing this library | |
95 | ||
96 | #[cfg(test)] #[macro_use] extern crate std; | |
97 | #[cfg(test)] #[macro_use] extern crate log; | |
98 | ||
99 | // Heaps provided for low-level allocation strategies | |
100 | ||
101 | pub mod heap; | |
102 | ||
103 | // Primitive types using the heaps above | |
104 | ||
c34b1796 AL |
105 | // Need to conditionally define the mod from `boxed.rs` to avoid |
106 | // duplicating the lang-items when building in test cfg; but also need | |
107 | // to allow code to have `use boxed::HEAP;` | |
108 | // and `use boxed::Box;` declarations. | |
1a4d82fc JJ |
109 | #[cfg(not(test))] |
110 | pub mod boxed; | |
85aaf69f | 111 | #[cfg(test)] |
c34b1796 AL |
112 | mod boxed { pub use std::boxed::{Box, HEAP}; } |
113 | #[cfg(test)] | |
85aaf69f | 114 | mod boxed_test; |
1a4d82fc JJ |
115 | pub mod arc; |
116 | pub mod rc; | |
117 | ||
118 | /// Common out-of-memory routine | |
119 | #[cold] | |
120 | #[inline(never)] | |
121 | pub fn oom() -> ! { | |
122 | // FIXME(#14674): This really needs to do something other than just abort | |
123 | // here, but any printing done must be *guaranteed* to not | |
124 | // allocate. | |
125 | unsafe { core::intrinsics::abort() } | |
126 | } | |
127 | ||
128 | // FIXME(#14344): When linking liballoc with libstd, this library will be linked | |
129 | // as an rlib (it only exists as an rlib). It turns out that an | |
130 | // optimized standard library doesn't actually use *any* symbols | |
131 | // from this library. Everything is inlined and optimized away. | |
132 | // This means that linkers will actually omit the object for this | |
133 | // file, even though it may be needed in the future. | |
134 | // | |
135 | // To get around this for now, we define a dummy symbol which | |
136 | // will never get inlined so the stdlib can call it. The stdlib's | |
137 | // reference to this symbol will cause this library's object file | |
138 | // to get linked in to libstd successfully (the linker won't | |
139 | // optimize it out). | |
140 | #[doc(hidden)] | |
141 | pub fn fixme_14344_be_sure_to_link_to_collections() {} |