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