src/libnative/lib.rs

   1 // Copyright 2013-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 //! The native I/O and threading crate
  12 //!
  13 //! This crate contains an implementation of 1:1 scheduling for a "native"
  14 //! runtime. In addition, all I/O provided by this crate is the thread blocking
  15 //! version of I/O.
  16 //!
  17 //! # Starting with libnative
  18 //!
  19 //! ```rust
  20 //! extern crate native;
  21 //!
  22 //! #[start]
  23 //! fn start(argc: int, argv: **u8) -> int { native::start(argc, argv, main) }
  24 //!
  25 //! fn main() {
  26 //!     // this code is running on the main OS thread
  27 //! }
  28 //! ```
  29 //!
  30 //! # Force spawning a native task
  31 //!
  32 //! ```rust
  33 //! extern crate native;
  34 //!
  35 //! fn main() {
  36 //!     // We're not sure whether this main function is run in 1:1 or M:N mode.
  37 //!
  38 //!     native::task::spawn(proc() {
  39 //!         // this code is guaranteed to be run on a native thread
  40 //!     });
  41 //! }
  42 //! ```
  43
  44 #[crate_id = "native#0.10-pre"];
  45 #[license = "MIT/ASL2"];
  46 #[crate_type = "rlib"];
  47 #[crate_type = "dylib"];
  48 #[doc(html_logo_url = "http://www.rust-lang.org/logos/rust-logo-128x128-blk-v2.png",
  49       html_favicon_url = "http://www.rust-lang.org/favicon.ico",
  50       html_root_url = "http://static.rust-lang.org/doc/master")];
  51 #[deny(unused_result, unused_must_use)];
  52 #[allow(non_camel_case_types)];
  53 #[allow(deprecated_owned_vector)]; // NOTE: remove after stage0
  54
  55 // NB this crate explicitly does *not* allow glob imports, please seriously
  56 //    consider whether they're needed before adding that feature here (the
  57 //    answer is that you don't need them)
  58
  59 use std::os;
  60 use std::rt;
  61
  62 pub mod io;
  63 pub mod task;
  64
  65 #[cfg(windows)]
  66 #[cfg(android)]
  67 static OS_DEFAULT_STACK_ESTIMATE: uint = 1 << 20;
  68 #[cfg(unix, not(android))]
  69 static OS_DEFAULT_STACK_ESTIMATE: uint = 2 * (1 << 20);
  70
  71 /// Executes the given procedure after initializing the runtime with the given
  72 /// argc/argv.
  73 ///
  74 /// This procedure is guaranteed to run on the thread calling this function, but
  75 /// the stack bounds for this rust task will *not* be set. Care must be taken
  76 /// for this function to not overflow its stack.
  77 ///
  78 /// This function will only return once *all* native threads in the system have
  79 /// exited.
  80 pub fn start(argc: int, argv: **u8, main: proc()) -> int {
  81     let something_around_the_top_of_the_stack = 1;
  82     let addr = &something_around_the_top_of_the_stack as *int;
  83     let my_stack_top = addr as uint;
  84
  85     // FIXME #11359 we just assume that this thread has a stack of a
  86     // certain size, and estimate that there's at most 20KB of stack
  87     // frames above our current position.
  88     let my_stack_bottom = my_stack_top + 20000 - OS_DEFAULT_STACK_ESTIMATE;
  89
  90     rt::init(argc, argv);
  91     let mut exit_code = None;
  92     let mut main = Some(main);
  93     let t = task::new((my_stack_bottom, my_stack_top)).run(|| {
  94         exit_code = Some(run(main.take_unwrap()));
  95     });
  96     drop(t);
  97     unsafe { rt::cleanup(); }
  98     // If the exit code wasn't set, then the task block must have failed.
  99     return exit_code.unwrap_or(rt::DEFAULT_ERROR_CODE);
 100 }
 101
 102 /// Executes a procedure on the current thread in a Rust task context.
 103 ///
 104 /// This function has all of the same details as `start` except for a different
 105 /// number of arguments.
 106 pub fn run(main: proc()) -> int {
 107     main();
 108     os::get_exit_status()
 109 }