Filesystem manipulation APIs. (#323)

This patch adds a new crate: tokio-fs. This crate provides a wrapper
around `std` functionality that can only be performed using blocking
operations. This primarily includes filesystem operations, but it also
includes standard input, output, and error access as these streams
cannot be safely switched to non-blocking mode in a portable way.

These wrappers call the `std` functions from within a `blocking`
annotation which allows the runtime to compensate for the fact that the
thread will potentially remain blocked in a system call.

tokio-threadpool/src/blocking.rs

@@ -2,6 +2,9 @@ use worker::Worker;
 
 use futures::Poll;
 
+use std::error::Error;
+use std::fmt;
+
 /// Error raised by `blocking`.
 #[derive(Debug)]
 pub struct BlockingError {
@@ -124,7 +127,7 @@ where F: FnOnce() -> T,
         };
 
         // Transition the worker state to blocking. This will exit the fn early
-        // with `NotRead` if the pool does not have enough capacity to enter
+        // with `NotReady` if the pool does not have enough capacity to enter
         // blocking mode.
         worker.transition_to_blocking()
     });
@@ -146,3 +149,15 @@ where F: FnOnce() -> T,
     // Return the result
     Ok(ret.into())
 }
+
+impl fmt::Display for BlockingError {
+    fn fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result {
+        write!(fmt, "{}", self.description())
+    }
+}
+
+impl Error for BlockingError {
+    fn description(&self) -> &str {
+        "`blocking` annotation used from outside the context of a thread pool"
+    }
+}