auto merge of #17432 : nick29581/rust/contrib, r=brson

[rust.git] / src / doc / guide-runtime.md

diff --git a/src/doc/guide-runtime.md b/src/doc/guide-runtime.md
index 6d5d90e2617fe5f5dfbbaff0f1a85054cc0d6f4c..24b5834ef7c085fc6ffdf8f667b799063e783a2c 100644 (file)
--- a/src/doc/guide-runtime.md
+++ b/src/doc/guide-runtime.md
@@ -45,7 +45,7 @@ The runtime is designed with a few goals in mind:
   support as well.
 
 * The runtime should not enforce separate "modes of compilation" in order to
-  work in multiple circumstances. Is it an explicit goal that you compile a Rust
+  work in multiple circumstances. It is an explicit goal that you compile a Rust
   library once and use it forever (in all environments).
 
 * The runtime should be fast. There should be no architectural design barrier
@@ -128,7 +128,7 @@ itself, yet again implying that they are not defined in the standard library.
 The full complement of runtime features is defined by the [`Runtime`
 trait](std/rt/trait.Runtime.html) and the [`Task`
 struct](std/rt/task/struct.Task.html). A `Task` is constant among all runtime
-implementations, but each runtime implements has its own implementation of the
+implementations, but each runtime has its own implementation of the
 `Runtime` trait.
 
 The local `Task` stores the runtime value inside of itself, and then ownership
@@ -216,34 +216,57 @@ into the pool of schedulers in order to spawn a new task.
 
 With two implementations of the runtime available, a choice obviously needs to
 be made to see which will be used. The compiler itself will always by-default
-link to one of these runtimes. At the time of this writing, the default runtime
-is `libgreen` but in the future this will become `libnative`.
+link to one of these runtimes.
 
 Having a default decision made in the compiler is done out of necessity and
 convenience. The compiler's decision of runtime to link to is *not* an
 endorsement of one over the other. As always, this decision can be overridden.
 
-For example, this program will be linked to "the default runtime"
+For example, this program will be linked to "the default runtime". The current
+default runtime is to use libnative.
 
 ~~~{.rust}
 fn main() {}
 ~~~
 
-Whereas this program explicitly opts into using a particular runtime
+### Force booting with libgreen
+
+In this example, the `main` function will be booted with I/O support powered by
+libuv. This is done by linking to the `rustuv` crate and specifying the
+`rustuv::event_loop` function as the event loop factory.
+
+To create a pool of green tasks which have no I/O support, you may shed the
+`rustuv` dependency and use the `green::basic::event_loop` function instead of
+`rustuv::event_loop`. All tasks will have no I/O support, but they will still be
+able to deschedule/reschedule (use channels, locks, etc).
 
 ~~~{.rust}
 extern crate green;
+extern crate rustuv;
 
 #[start]
-fn start(argc: int, argv: **u8) -> int {
-    green::start(argc, argv, main)
+fn start(argc: int, argv: *const *const u8) -> int {
+    green::start(argc, argv, rustuv::event_loop, main)
 }
 
 fn main() {}
 ~~~
 
-Both libgreen/libnative provide a top-level `start` function which is used to
-boot an initial Rust task in that specified runtime.
+### Force booting with libnative
+
+This program's `main` function will always be booted with libnative, running
+inside of an OS thread.
+
+~~~{.rust}
+extern crate native;
+
+#[start]
+fn start(argc: int, argv: *const *const u8) -> int {
+    native::start(argc, argv, main)
+}
+
+fn main() {}
+~~~
 
 # Finding the runtime