(index<- ) ./libstd/rt/mod.rs
git branch: * master 5200215 auto merge of #14035 : alexcrichton/rust/experimental, r=huonw
modified: Fri May 9 13:02:28 2014
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 /*! Runtime services, including the task scheduler and I/O dispatcher
12
13 The `rt` module provides the private runtime infrastructure necessary
14 to support core language features like the exchange and local heap,
15 the garbage collector, logging, local data and unwinding. It also
16 implements the default task scheduler and task model. Initialization
17 routines are provided for setting up runtime resources in common
18 configurations, including that used by `rustc` when generating
19 executables.
20
21 It is intended that the features provided by `rt` can be factored in a
22 way such that the core library can be built with different 'profiles'
23 for different use cases, e.g. excluding the task scheduler. A number
24 of runtime features though are critical to the functioning of the
25 language and an implementation must be provided regardless of the
26 execution environment.
27
28 Of foremost importance is the global exchange heap, in the module
29 `global_heap`. Very little practical Rust code can be written without
30 access to the global heap. Unlike most of `rt` the global heap is
31 truly a global resource and generally operates independently of the
32 rest of the runtime.
33
34 All other runtime features are task-local, including the local heap,
35 the garbage collector, local storage, logging and the stack unwinder.
36
37 The relationship between `rt` and the rest of the core library is
38 not entirely clear yet and some modules will be moving into or
39 out of `rt` as development proceeds.
40
41 Several modules in `core` are clients of `rt`:
42
43 * `std::task` - The user-facing interface to the Rust task model.
44 * `std::local_data` - The interface to local data.
45 * `std::gc` - The garbage collector.
46 * `std::unstable::lang` - Miscellaneous lang items, some of which rely on `std::rt`.
47 * `std::cleanup` - Local heap destruction.
48 * `std::io` - In the future `std::io` will use an `rt` implementation.
49 * `std::logging`
50 * `std::comm`
51
52 */
53
54 // FIXME: this should not be here.
55 #![allow(missing_doc)]
56
57 use any::Any;
58 use kinds::Send;
59 use option::Option;
60 use owned::Box;
61 use result::Result;
62 use task::TaskOpts;
63
64 use self::task::{Task, BlockedTask};
65
66 // this is somewhat useful when a program wants to spawn a "reasonable" number
67 // of workers based on the constraints of the system that it's running on.
68 // Perhaps this shouldn't be a `pub use` though and there should be another
69 // method...
70 pub use self::util::default_sched_threads;
71
72 // Export unwinding facilities used by the failure macros
73 pub use self::unwind::{begin_unwind, begin_unwind_fmt};
74
75 pub use self::util::{Stdio, Stdout, Stderr};
76
77 // FIXME: these probably shouldn't be public...
78 #[doc(hidden)]
79 pub mod shouldnt_be_public {
80 #[cfg(not(test))]
81 pub use super::local_ptr::native::maybe_tls_key;
82 #[cfg(not(windows), not(target_os = "android"))]
83 pub use super::local_ptr::compiled::RT_TLS_PTR;
84 }
85
86 // Internal macros used by the runtime.
87 mod macros;
88
89 // The global (exchange) heap.
90 pub mod global_heap;
91
92 // Implementations of language-critical runtime features like @.
93 pub mod task;
94
95 // The EventLoop and internal synchronous I/O interface.
96 pub mod rtio;
97
98 // The Local trait for types that are accessible via thread-local
99 // or task-local storage.
100 pub mod local;
101
102 // Bindings to system threading libraries.
103 pub mod thread;
104
105 // The runtime configuration, read from environment variables.
106 pub mod env;
107
108 // The local, managed heap
109 pub mod local_heap;
110
111 // The runtime needs to be able to put a pointer into thread-local storage.
112 mod local_ptr;
113
114 // Bindings to pthread/windows thread-local storage.
115 mod thread_local_storage;
116
117 // Stack unwinding
118 pub mod unwind;
119
120 // The interface to libunwind that rust is using.
121 mod libunwind;
122
123 // Simple backtrace functionality (to print on failure)
124 pub mod backtrace;
125
126 // Just stuff
127 mod util;
128
129 // Global command line argument storage
130 pub mod args;
131
132 // Support for running procedures when a program has exited.
133 mod at_exit_imp;
134
135 // Bookkeeping for task counts
136 pub mod bookkeeping;
137
138 // Stack overflow protection
139 pub mod stack;
140
141 /// The default error code of the rust runtime if the main task fails instead
142 /// of exiting cleanly.
143 pub static DEFAULT_ERROR_CODE: int = 101;
144
145 /// The interface to the current runtime.
146 ///
147 /// This trait is used as the abstraction between 1:1 and M:N scheduling. The
148 /// two independent crates, libnative and libgreen, both have objects which
149 /// implement this trait. The goal of this trait is to encompass all the
150 /// fundamental differences in functionality between the 1:1 and M:N runtime
151 /// modes.
152 pub trait Runtime {
153 // Necessary scheduling functions, used for channels and blocking I/O
154 // (sometimes).
155 fn yield_now(~self, cur_task: Box<Task>);
156 fn maybe_yield(~self, cur_task: Box<Task>);
157 fn deschedule(~self, times: uint, cur_task: Box<Task>,
158 f: |BlockedTask| -> Result<(), BlockedTask>);
159 fn reawaken(~self, to_wake: Box<Task>);
160
161 // Miscellaneous calls which are very different depending on what context
162 // you're in.
163 fn spawn_sibling(~self,
164 cur_task: Box<Task>,
165 opts: TaskOpts,
166 f: proc():Send);
167 fn local_io<'a>(&'a mut self) -> Option<rtio::LocalIo<'a>>;
168 /// The (low, high) edges of the current stack.
169 fn stack_bounds(&self) -> (uint, uint); // (lo, hi)
170 fn can_block(&self) -> bool;
171
172 // FIXME: This is a serious code smell and this should not exist at all.
173 fn wrap(~self) -> Box<Any>;
174 }
175
176 /// One-time runtime initialization.
177 ///
178 /// Initializes global state, including frobbing
179 /// the crate's logging flags, registering GC
180 /// metadata, and storing the process arguments.
181 pub fn init(argc: int, argv: **u8) {
182 // FIXME: Derefing these pointers is not safe.
183 // Need to propagate the unsafety to `start`.
184 unsafe {
185 args::init(argc, argv);
186 env::init();
187 local_ptr::init();
188 at_exit_imp::init();
189 }
190 }
191
192 /// Enqueues a procedure to run when the runtime is cleaned up
193 ///
194 /// The procedure passed to this function will be executed as part of the
195 /// runtime cleanup phase. For normal rust programs, this means that it will run
196 /// after all other tasks have exited.
197 ///
198 /// The procedure is *not* executed with a local `Task` available to it, so
199 /// primitives like logging, I/O, channels, spawning, etc, are *not* available.
200 /// This is meant for "bare bones" usage to clean up runtime details, this is
201 /// not meant as a general-purpose "let's clean everything up" function.
202 ///
203 /// It is forbidden for procedures to register more `at_exit` handlers when they
204 /// are running, and doing so will lead to a process abort.
205 pub fn at_exit(f: proc():Send) {
206 at_exit_imp::push(f);
207 }
208
209 /// One-time runtime cleanup.
210 ///
211 /// This function is unsafe because it performs no checks to ensure that the
212 /// runtime has completely ceased running. It is the responsibility of the
213 /// caller to ensure that the runtime is entirely shut down and nothing will be
214 /// poking around at the internal components.
215 ///
216 /// Invoking cleanup while portions of the runtime are still in use may cause
217 /// undefined behavior.
218 pub unsafe fn cleanup() {
219 bookkeeping::wait_for_other_tasks();
220 at_exit_imp::run();
221 args::cleanup();
222 local_ptr::cleanup();
223 }