It took a bit longer than I had initially hoped (as it always does), but a new Tokio version has been released. This release includes, among other features, a new set of APIs that allow performing filesystem operations from an asynchronous context.
Interacting with files (and other filesystem types) requires* blocking system calls and we all know that blocking and asynchronous do not mix. So, historically, when people ask "how do I read from and write to files?", the answer is to use a thread pool. The idea is that when a blocking read or write must be performed, it is done on a thread pool so that it does not block the asynchronous reactor.
Requiring a separate thread pool for performing file operations requires message passing. The asynchronous task must send a message to the thread pool asking it to do a read from the file, the thread pool does the read and fills a buffer with the result. Then the thread pool sends the buffer back to the asynchronous task. Not only does this add the overhead for dispatching messages, but it also requires allocating buffers to send the data back and forth.
Now, with Tokio's new filesystem APIs, this message passing overhead is no
longer needed. A new
File type is added. This type looks very similar to the
type provided by
std, but it implements
it safe to use directly from an asynchronous task running on the Tokio
File type implements
AsyncWrite, it can be
used in much the same way that a TCP socket would be used from Tokio.
As of today, the filesystem APIs are pretty minimal. There are many other APIs
that need to be implemented to bring the Tokio filesystem APIs in line with
std, but those are left as an exercise to the reader to submit as PRs!
* Yes, there are some operating systems that provide fully asynchronous filesystem APIs, but these are either incomplete or not portable.
This release of Tokio also includes asynchronous standard input and standard output APIs. Because it is difficult to provide true asynchronous standard input and output in a portable way, the Tokio versions use a similar strategy as the blocking file operation APIs.
These new APIs are made possible thanks to a new
blocking API that allows
annotating sections of code that will block the current thread. These blocking
sections can include blocking system calls, waiting on mutexes, or CPU heavy
By informing the Tokio runtime that the current thread will block, the runtime is able to move the event loop from the current thread to another thread, freeing the current thread up to permit blocking.
This is the opposite of using message passing to run blocking operations on a threadpool. Instead of moving the blocking operation to another thread, the entire event loop is moved.
In practice, moving the event loop to another thread is much cheaper than moving the blocking operation. Doing so only requires a few atomic operations. The Tokio runtime also keeps a pool of standby threads ready to allow moving the event loop as fast as possible.
This also means that using the
blocking annotation and
tokio-fs must be done
from the context of the Tokio runtime and not other futures aware executors.
The release also includes a "current thread" version of the runtime
(thanks kpp). This is similar to the existing runtime,
but runs all components on the current thread. This allows running futures that
do not implement