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.
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.
11 //! Rust's core allocation library
13 //! This is the lowest level library through which allocation in Rust can be
14 //! performed where the allocation is assumed to succeed. This library will
15 //! trigger a task failure when allocation fails.
17 //! This library, like libcore, is not intended for general usage, but rather as
18 //! a building block of other libraries. The types and interfaces in this
19 //! library are reexported through the [standard library](../std/index.html),
20 //! and should not be used through this library.
22 //! Currently, there are four major definitions in this library.
26 //! The [`Box`](owned/index.html) type is the core owned pointer type in rust.
27 //! There can only be one owner of a `Box`, and the owner can decide to mutate
30 //! This type can be sent among tasks efficiently as the size of a `Box` value
31 //! is just a pointer. Tree-like data structures are often built on owned
32 //! pointers because each node often has only one owner, the parent.
34 //! ## Reference counted pointers
36 //! The [`Rc`](rc/index.html) type is a non-threadsafe reference-counted pointer
37 //! type intended for sharing memory within a task. An `Rc` pointer wraps a
38 //! type, `T`, and only allows access to `&T`, a shared reference.
40 //! This type is useful when inherited mutability is too constraining for an
41 //! application (such as using `Box`), and is often paired with the `Cell` or
42 //! `RefCell` types in order to allow mutation.
44 //! ## Atomically reference counted pointers
46 //! The [`Arc`](arc/index.html) type is the threadsafe equivalent of the `Rc`
47 //! type. It provides all the same functionality of `Rc`, except it requires
48 //! that the contained type `T` is shareable. Additionally, `Arc<T>` is itself
49 //! sendable while `Rc<T>` is not.
51 //! This types allows for shared access to the contained data, and is often
52 //! paired with synchronization primitives such as mutexes to allow mutation of
55 //! ## Heap interfaces
57 //! The [`heap`](heap/index.html) and [`libc_heap`](libc_heap/index.html)
58 //! modules are the unsafe interfaces to the underlying allocation systems. The
59 //! `heap` module is considered the default heap, and is not necessarily backed
60 //! by libc malloc/free. The `libc_heap` module is defined to be wired up to
61 //! the system malloc/free.
63 #![crate_id = "alloc#0.11.0-pre"]
64 #![license = "MIT/ASL2"]
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/")]
74 #[phase(syntax, link)]
78 #[phase(plugin, link)]
84 // Allow testing this library
86 #[cfg(test)] extern crate debug;
87 #[cfg(test)] extern crate native;
88 #[cfg(test, stage0)] #[phase(syntax, link)] extern crate std;
89 #[cfg(test, stage0)] #[phase(syntax, link)] extern crate log;
90 #[cfg(test, not(stage0))] #[phase(plugin, link)] extern crate std;
91 #[cfg(test, not(stage0))] #[phase(plugin, link)] extern crate log;
93 // Heaps provided for low-level allocation strategies
99 // Primitive types using the heaps above
106 // FIXME(#14344): When linking liballoc with libstd, this library will be linked
107 // as an rlib (it only exists as an rlib). It turns out that an
108 // optimized standard library doesn't actually use *any* symbols
109 // from this library. Everything is inlined and optimized away.
110 // This means that linkers will actually omit the object for this
111 // file, even though it may be needed in the future.
113 // To get around this for now, we define a dummy symbol which
114 // will never get inlined so the stdlib can call it. The stdlib's
115 // reference to this symbol will cause this library's object file
116 // to get linked in to libstd successfully (the linker won't
119 pub fn fixme_14344_be_sure_to_link_to_collections() {}
125 pub use core::option;