src/librustrt/lib.rs

   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 #![crate_name = "rustrt"]
  12 #![license = "MIT/ASL2"]
  13 #![crate_type = "rlib"]
  14 #![crate_type = "dylib"]
  15 #![doc(html_logo_url = "http://www.rust-lang.org/logos/rust-logo-128x128-blk-v2.png",
  16        html_favicon_url = "http://www.rust-lang.org/favicon.ico",
  17        html_root_url = "http://doc.rust-lang.org/master/")]
  18
  19 #![feature(macro_rules, phase, globs, thread_local, managed_boxes, asm)]
  20 #![feature(linkage, lang_items, unsafe_destructor, default_type_params)]
  21 #![no_std]
  22 #![experimental]
  23
  24 #[phase(plugin, link)] extern crate core;
  25 extern crate alloc;
  26 extern crate libc;
  27 extern crate collections;
  28
  29 #[cfg(test)] extern crate realrustrt = "rustrt";
  30 #[cfg(test)] extern crate test;
  31 #[cfg(test)] extern crate native;
  32
  33 #[cfg(test)] #[phase(plugin, link)] extern crate std;
  34
  35 pub use self::util::{Stdio, Stdout, Stderr};
  36 pub use self::unwind::{begin_unwind, begin_unwind_fmt};
  37
  38 use core::prelude::*;
  39
  40 use alloc::boxed::Box;
  41 use core::any::Any;
  42
  43 use task::{Task, BlockedTask, TaskOpts};
  44
  45 mod macros;
  46
  47 mod at_exit_imp;
  48 mod local_ptr;
  49 mod thread_local_storage;
  50 mod util;
  51 mod libunwind;
  52
  53 pub mod args;
  54 pub mod bookkeeping;
  55 pub mod c_str;
  56 pub mod exclusive;
  57 pub mod local;
  58 pub mod local_data;
  59 pub mod local_heap;
  60 pub mod mutex;
  61 pub mod rtio;
  62 pub mod stack;
  63 pub mod task;
  64 pub mod thread;
  65 pub mod unwind;
  66
  67 /// The interface to the current runtime.
  68 ///
  69 /// This trait is used as the abstraction between 1:1 and M:N scheduling. The
  70 /// two independent crates, libnative and libgreen, both have objects which
  71 /// implement this trait. The goal of this trait is to encompass all the
  72 /// fundamental differences in functionality between the 1:1 and M:N runtime
  73 /// modes.
  74 pub trait Runtime {
  75     // Necessary scheduling functions, used for channels and blocking I/O
  76     // (sometimes).
  77     fn yield_now(~self, cur_task: Box<Task>);
  78     fn maybe_yield(~self, cur_task: Box<Task>);
  79     fn deschedule(~self, times: uint, cur_task: Box<Task>,
  80                   f: |BlockedTask| -> Result<(), BlockedTask>);
  81     fn reawaken(~self, to_wake: Box<Task>);
  82
  83     // Miscellaneous calls which are very different depending on what context
  84     // you're in.
  85     fn spawn_sibling(~self,
  86                      cur_task: Box<Task>,
  87                      opts: TaskOpts,
  88                      f: proc():Send);
  89     fn local_io<'a>(&'a mut self) -> Option<rtio::LocalIo<'a>>;
  90     /// The (low, high) edges of the current stack.
  91     fn stack_bounds(&self) -> (uint, uint); // (lo, hi)
  92     fn can_block(&self) -> bool;
  93
  94     // FIXME: This is a serious code smell and this should not exist at all.
  95     fn wrap(~self) -> Box<Any>;
  96 }
  97
  98 /// The default error code of the rust runtime if the main task fails instead
  99 /// of exiting cleanly.
 100 pub static DEFAULT_ERROR_CODE: int = 101;
 101
 102 /// One-time runtime initialization.
 103 ///
 104 /// Initializes global state, including frobbing
 105 /// the crate's logging flags, registering GC
 106 /// metadata, and storing the process arguments.
 107 pub fn init(argc: int, argv: *const *const u8) {
 108     // FIXME: Derefing these pointers is not safe.
 109     // Need to propagate the unsafety to `start`.
 110     unsafe {
 111         args::init(argc, argv);
 112         local_ptr::init();
 113         at_exit_imp::init();
 114     }
 115
 116     // FIXME(#14344) this shouldn't be necessary
 117     collections::fixme_14344_be_sure_to_link_to_collections();
 118     alloc::fixme_14344_be_sure_to_link_to_collections();
 119     libc::issue_14344_workaround();
 120 }
 121
 122 /// Enqueues a procedure to run when the runtime is cleaned up
 123 ///
 124 /// The procedure passed to this function will be executed as part of the
 125 /// runtime cleanup phase. For normal rust programs, this means that it will run
 126 /// after all other tasks have exited.
 127 ///
 128 /// The procedure is *not* executed with a local `Task` available to it, so
 129 /// primitives like logging, I/O, channels, spawning, etc, are *not* available.
 130 /// This is meant for "bare bones" usage to clean up runtime details, this is
 131 /// not meant as a general-purpose "let's clean everything up" function.
 132 ///
 133 /// It is forbidden for procedures to register more `at_exit` handlers when they
 134 /// are running, and doing so will lead to a process abort.
 135 pub fn at_exit(f: proc():Send) {
 136     at_exit_imp::push(f);
 137 }
 138
 139 /// One-time runtime cleanup.
 140 ///
 141 /// This function is unsafe because it performs no checks to ensure that the
 142 /// runtime has completely ceased running. It is the responsibility of the
 143 /// caller to ensure that the runtime is entirely shut down and nothing will be
 144 /// poking around at the internal components.
 145 ///
 146 /// Invoking cleanup while portions of the runtime are still in use may cause
 147 /// undefined behavior.
 148 pub unsafe fn cleanup() {
 149     bookkeeping::wait_for_other_tasks();
 150     at_exit_imp::run();
 151     args::cleanup();
 152     local_ptr::cleanup();
 153 }
 154
 155 // FIXME: these probably shouldn't be public...
 156 #[doc(hidden)]
 157 pub mod shouldnt_be_public {
 158     #[cfg(not(test))]
 159     pub use super::local_ptr::native::maybe_tls_key;
 160     #[cfg(not(windows), not(target_os = "android"), not(target_os = "ios"))]
 161     pub use super::local_ptr::compiled::RT_TLS_PTR;
 162 }
 163
 164 #[cfg(not(test))]
 165 mod std {
 166     pub use core::{fmt, option, cmp};
 167 }