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