mirror of
https://github.com/tokio-rs/tokio.git
synced 2025-09-28 12:10:37 +00:00
30330da11a
* chore: Fix examples not working with `cargo run` ## Motivation PR #991 moved the `tokio` crate to its own subdirectory, but did not move the `examples` directory into `tokio/examples`. While attempting to use the examples for testing another change, I noticed that #991 had broken the ability to use `cargo run`, as the examples were no longer considered part of a crate that cargo was aware of: ``` tokio on master [$] via 🦀v1.33.0 at ☸️ aks-eliza-dev ➜ cargo run --example chat error: no example target named `chat` Did you mean `echo`? ``` ## Solution This branch moves the examples into the `tokio` directory, so cargo is now once again aware of them: ``` tokio on eliza/fix-examples [$] via 🦀v1.33.0 at ☸️ aks-eliza-dev ➜ cargo run --example chat Compiling tokio-executor v0.1.7 (/Users/eliza/Code/tokio/tokio-executor) Compiling tokio-reactor v0.1.9 Compiling tokio-threadpool v0.1.13 Compiling tokio-current-thread v0.1.6 Compiling tokio-timer v0.2.10 Compiling tokio-uds v0.2.5 Compiling tokio-udp v0.1.3 Compiling tokio-tcp v0.1.3 Compiling tokio-fs v0.1.6 Compiling tokio v0.1.18 (/Users/eliza/Code/tokio/tokio) Finished dev [unoptimized + debuginfo] target(s) in 7.04s Running `target/debug/examples/chat` server running on localhost:6142 ``` Signed-off-by: Eliza Weisman <eliza@buoyant.io> Signed-off-by: Eliza Weisman <eliza@buoyant.io>
187 lines
6.1 KiB
Markdown
187 lines
6.1 KiB
Markdown
# Tokio
|
|
|
|
A runtime for writing reliable, asynchronous, and slim applications with
|
|
the Rust programming language. It is:
|
|
|
|
* **Fast**: Tokio's zero-cost abstractions give you bare-metal
|
|
performance.
|
|
|
|
* **Reliable**: Tokio leverages Rust's ownership, type system, and
|
|
concurrency model to reduce bugs and ensure thread safety.
|
|
|
|
* **Scalable**: Tokio has a minimal footprint, and handles backpressure
|
|
and cancellation naturally.
|
|
|
|
[![Crates.io][crates-badge]][crates-url]
|
|
[![MIT licensed][mit-badge]][mit-url]
|
|
[![Build Status][azure-badge]][azure-url]
|
|
[![Gitter chat][gitter-badge]][gitter-url]
|
|
|
|
[crates-badge]: https://img.shields.io/crates/v/tokio.svg
|
|
[crates-url]: https://crates.io/crates/tokio
|
|
[mit-badge]: https://img.shields.io/badge/license-MIT-blue.svg
|
|
[mit-url]: LICENSE-MIT
|
|
[azure-badge]: https://dev.azure.com/tokio-rs/Tokio/_apis/build/status/tokio-rs.tokio?branchName=master
|
|
[azure-url]: https://dev.azure.com/tokio-rs/Tokio/_build/latest?definitionId=1&branchName=master
|
|
[gitter-badge]: https://img.shields.io/gitter/room/tokio-rs/tokio.svg
|
|
[gitter-url]: https://gitter.im/tokio-rs/tokio
|
|
|
|
[Website](https://tokio.rs) |
|
|
[Guides](https://tokio.rs/docs/getting-started/hello-world/) |
|
|
[API Docs](https://docs.rs/tokio/0.1.18/tokio) |
|
|
[Chat](https://gitter.im/tokio-rs/tokio)
|
|
|
|
The API docs for the master branch are published [here][master-dox].
|
|
|
|
[master-dox]: https://tokio-rs.github.io/tokio/doc/tokio/
|
|
|
|
## Overview
|
|
|
|
Tokio is an event-driven, non-blocking I/O platform for writing
|
|
asynchronous applications with the Rust programming language. At a high
|
|
level, it provides a few major components:
|
|
|
|
* A multithreaded, work-stealing based task [scheduler].
|
|
* A [reactor] backed by the operating system's event queue (epoll, kqueue,
|
|
IOCP, etc...).
|
|
* Asynchronous [TCP and UDP][net] sockets.
|
|
|
|
These components provide the runtime components necessary for building
|
|
an asynchronous application.
|
|
|
|
[net]: https://docs.rs/tokio/0.1.18/tokio/net/index.html
|
|
[reactor]: https://docs.rs/tokio/0.1.18/tokio/reactor/index.html
|
|
[scheduler]: https://docs.rs/tokio/0.1.18/tokio/runtime/index.html
|
|
|
|
## Example
|
|
|
|
A basic TCP echo server with Tokio:
|
|
|
|
```rust
|
|
extern crate tokio;
|
|
|
|
use tokio::prelude::*;
|
|
use tokio::io::copy;
|
|
use tokio::net::TcpListener;
|
|
|
|
fn main() {
|
|
// Bind the server's socket.
|
|
let addr = "127.0.0.1:12345".parse().unwrap();
|
|
let listener = TcpListener::bind(&addr)
|
|
.expect("unable to bind TCP listener");
|
|
|
|
// Pull out a stream of sockets for incoming connections
|
|
let server = listener.incoming()
|
|
.map_err(|e| eprintln!("accept failed = {:?}", e))
|
|
.for_each(|sock| {
|
|
// Split up the reading and writing parts of the
|
|
// socket.
|
|
let (reader, writer) = sock.split();
|
|
|
|
// A future that echos the data and returns how
|
|
// many bytes were copied...
|
|
let bytes_copied = copy(reader, writer);
|
|
|
|
// ... after which we'll print what happened.
|
|
let handle_conn = bytes_copied.map(|amt| {
|
|
println!("wrote {:?} bytes", amt)
|
|
}).map_err(|err| {
|
|
eprintln!("IO error {:?}", err)
|
|
});
|
|
|
|
// Spawn the future as a concurrent task.
|
|
tokio::spawn(handle_conn)
|
|
});
|
|
|
|
// Start the Tokio runtime
|
|
tokio::run(server);
|
|
}
|
|
```
|
|
|
|
More examples can be found [here](tokio/examples).
|
|
|
|
## Getting Help
|
|
|
|
First, see if the answer to your question can be found in the [Guides] or the
|
|
[API documentation]. If the answer is not there, there is an active community in
|
|
the [Tokio Gitter channel][chat]. We would be happy to try to answer your
|
|
question. Last, if that doesn't work, try opening an [issue] with the question.
|
|
|
|
[chat]: https://gitter.im/tokio-rs/tokio
|
|
[issue]: https://github.com/tokio-rs/tokio/issues/new
|
|
|
|
## Contributing
|
|
|
|
:balloon: Thanks for your help improving the project! We are so happy to have
|
|
you! We have a [contributing guide][guide] to help you get involved in the Tokio
|
|
project.
|
|
|
|
[guide]: CONTRIBUTING.md
|
|
|
|
## Project layout
|
|
|
|
The `tokio` crate, found at the root, is primarily intended for use by
|
|
application developers. Library authors should depend on the sub crates, which
|
|
have greater guarantees of stability.
|
|
|
|
The crates included as part of Tokio are:
|
|
|
|
* [`tokio-async-await`]: Experimental `async` / `await` support.
|
|
|
|
* [`tokio-codec`]: Utilities for encoding and decoding protocol frames.
|
|
|
|
* [`tokio-current-thread`]: Schedule the execution of futures on the current
|
|
thread.
|
|
|
|
* [`tokio-executor`]: Task execution related traits and utilities.
|
|
|
|
* [`tokio-fs`]: Filesystem (and standard in / out) APIs.
|
|
|
|
* [`tokio-io`]: Asynchronous I/O related traits and utilities.
|
|
|
|
* [`tokio-reactor`]: Event loop that drives I/O resources (like TCP and UDP
|
|
sockets).
|
|
|
|
* [`tokio-tcp`]: TCP bindings for use with `tokio-io` and `tokio-reactor`.
|
|
|
|
* [`tokio-threadpool`]: Schedules the execution of futures across a pool of
|
|
threads.
|
|
|
|
* [ `tokio-timer`]: Time related APIs.
|
|
|
|
* [`tokio-udp`]: UDP bindings for use with `tokio-io` and `tokio-reactor`.
|
|
|
|
* [`tokio-uds`]: Unix Domain Socket bindings for use with `tokio-io` and
|
|
`tokio-reactor`.
|
|
|
|
[`tokio-async-await`]: tokio-async-await
|
|
[`tokio-codec`]: tokio-codec
|
|
[`tokio-current-thread`]: tokio-current-thread
|
|
[`tokio-executor`]: tokio-executor
|
|
[`tokio-fs`]: tokio-fs
|
|
[`tokio-io`]: tokio-io
|
|
[`tokio-reactor`]: tokio-reactor
|
|
[`tokio-tcp`]: tokio-tcp
|
|
[`tokio-threadpool`]: tokio-threadpool
|
|
[`tokio-timer`]: tokio-timer
|
|
[`tokio-udp`]: tokio-udp
|
|
[`tokio-uds`]: tokio-uds
|
|
|
|
## Supported Rust Versions
|
|
|
|
Tokio is built against the latest stable, nightly, and beta Rust releases. The
|
|
minimum version supported is the stable release from three months before the
|
|
current stable release version. For example, if the latest stable Rust is 1.29,
|
|
the minimum version supported is 1.26. The current Tokio version is not
|
|
guaranteed to build on Rust versions earlier than the minimum supported version.
|
|
|
|
## License
|
|
|
|
This project is licensed under the [MIT license](LICENSE).
|
|
|
|
### Contribution
|
|
|
|
Unless you explicitly state otherwise, any contribution intentionally submitted
|
|
for inclusion in Tokio by you, shall be licensed as MIT, without any additional
|
|
terms or conditions.
|