Introduce the Tokio runtime: Reactor + Threadpool (#141)

This patch is an intial implementation of the Tokio runtime. The Tokio
runtime provides an out of the box configuration for running I/O heavy
asynchronous applications.

As of now, the Tokio runtime is a combination of a work-stealing thread
pool as well as a background reactor to drive I/O resources.

This patch also includes tokio-executor, a hopefully short lived crate
that is based on the futures 0.2 executor RFC.

* Implement `Park` for `Reactor`

This enables the reactor to be used as the thread parker for executors.
This also adds an `Error` component to `Park`. With this change, a
`Reactor` and a `CurrentThread` can be combined to achieve the
capabilities of tokio-core.

tokio-executor/src/enter.rs

@@ -0,0 +1,97 @@
+use std::prelude::v1::*;
+use std::cell::Cell;
+use std::fmt;
+
+thread_local!(static ENTERED: Cell<bool> = Cell::new(false));
+
+/// Represents an executor context.
+///
+/// For more details, see [`enter` documentation](fn.enter.html)
+pub struct Enter {
+    on_exit: Vec<Box<Callback>>,
+    permanent: bool,
+}
+
+/// An error returned by `enter` if an execution scope has already been
+/// entered.
+#[derive(Debug)]
+pub struct EnterError {
+    _a: (),
+}
+
+/// Marks the current thread as being within the dynamic extent of an
+/// executor.
+///
+/// Executor implementations should call this function before blocking the
+/// thread. If `None` is returned, the executor should fail by panicking or
+/// taking some other action without blocking the current thread. This prevents
+/// deadlocks due to multiple executors competing for the same thread.
+///
+/// # Error
+///
+/// Returns an error if the current thread is already marked
+pub fn enter() -> Result<Enter, EnterError> {
+    ENTERED.with(|c| {
+        if c.get() {
+            Err(EnterError { _a: () })
+        } else {
+            c.set(true);
+
+            Ok(Enter {
+                on_exit: Vec::new(),
+                permanent: false,
+            })
+        }
+    })
+}
+
+impl Enter {
+    /// Register a callback to be invoked if and when the thread
+    /// ceased to act as an executor.
+    pub fn on_exit<F>(&mut self, f: F) where F: FnOnce() + 'static {
+        self.on_exit.push(Box::new(f));
+    }
+
+    /// Treat the remainder of execution on this thread as part of an
+    /// executor; used mostly for thread pool worker threads.
+    ///
+    /// All registered `on_exit` callbacks are *dropped* without being
+    /// invoked.
+    pub fn make_permanent(mut self) {
+        self.permanent = true;
+    }
+}
+
+impl fmt::Debug for Enter {
+    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+        f.debug_struct("Enter").finish()
+    }
+}
+
+impl Drop for Enter {
+    fn drop(&mut self) {
+        ENTERED.with(|c| {
+            assert!(c.get());
+
+            if self.permanent {
+                return
+            }
+
+            for callback in self.on_exit.drain(..) {
+                callback.call();
+            }
+
+            c.set(false);
+        });
+    }
+}
+
+trait Callback: 'static {
+    fn call(self: Box<Self>);
+}
+
+impl<F: FnOnce() + 'static> Callback for F {
+    fn call(self: Box<Self>) {
+        (*self)()
+    }
+}