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