From ecedea3404a04614da967c6a43a3f802573c9261 Mon Sep 17 00:00:00 2001 From: Alex Crichton Date: Mon, 11 Sep 2017 13:30:45 -0700 Subject: Add a README for the examples --- examples/README.md | 47 +++++++++++++++++++++++++++++++++++++++++++++++ examples/echo-threads.rs | 2 +- examples/proxy.rs | 15 +++++++++++++++ 3 files changed, 63 insertions(+), 1 deletion(-) create mode 100644 examples/README.md (limited to 'examples') diff --git a/examples/README.md b/examples/README.md new file mode 100644 index 00000000..2ae05b53 --- /dev/null +++ b/examples/README.md @@ -0,0 +1,47 @@ +## Examples of `tokio-core` + +This directory contains a number of examples showcasing various capabilities of +the `tokio_core` crate. Most of these examples also leverage the `futures` and +`tokio_io` crates, along with a number of other miscellaneous dependencies for +various tasks. + +All examples can be executed with: + +``` +cargo run --example $name +``` + +A high level description of each example is: + +* `hello` - a tiny server that simply writes "Hello!" to all connected clients + and then terminates the connection, should help see how to create and + initialize `tokio_core`. +* `echo` - this is your standard TCP "echo server" which simply accepts + connections and then echos back any contents that are read from each connected + client. +* `echo-udp` - again your standard "echo server", except for UDP instead of TCP. + This will echo back any packets received to the original sender. +* `echo-threads` - servers the same purpose as the `echo` example, except this + shows off using multiple cores on a machine for doing I/O processing. +* `connect` - this is a `nc`-like clone which can be used to interact with most + other examples. The program creates a TCP connection or UDP socket to sends + all information read on stdin to the remote peer, displaying any data received + on stdout. Often quite useful when interacting with the various other servers + here! +* `chat` - this spins up a local TCP server which will broadcast from any + connected client to all other connected clients. You can connect to this in + multiple terminals and use it to chat between the terminals. +* `proxy` - an example proxy server that will forward all connected TCP clients + to the remote address specified when starting the program. +* `sink` - a benchmark-like example which shows writing 0s infinitely to any + connected client. +* `tinyhttp` - a tiny HTTP/1.1 server which doesn't support HTTP request bodies + showcasing running on multiple cores, working with futures and spawning + tasks, and finally framing a TCP connection to discrete request/response + objects. +* `udp-codec` - an example of using the `UdpCodec` trait along with a small + ping-pong protocol happening locally. + +If you've got an example you'd like to see here, please feel free to open an +issue. Otherwise if you've got an example you'd like to add, please feel free +to make a PR! diff --git a/examples/echo-threads.rs b/examples/echo-threads.rs index 1cb94e87..810fd048 100644 --- a/examples/echo-threads.rs +++ b/examples/echo-threads.rs @@ -7,7 +7,7 @@ //! //! To see this server in action, you can run this in one terminal: //! -//! cargo run --example echoe-threads +//! cargo run --example echo-threads //! //! and in another terminal you can run: //! diff --git a/examples/proxy.rs b/examples/proxy.rs index 4920cc9f..7bc53819 100644 --- a/examples/proxy.rs +++ b/examples/proxy.rs @@ -1,5 +1,20 @@ //! A proxy that forwards data to another server and forwards that server's //! responses back to clients. +//! +//! You can showcase this by running this in one terminal: +//! +//! cargo run --example proxy +//! +//! This in another terminal +//! +//! cargo run --example echo +//! +//! And finally this in another terminal +//! +//! cargo run --example connect 127.0.0.1:8081 +//! +//! This final terminal will connect to our proxy, which will in turn connect to +//! the echo server, and you'll be able to see data flowing between them. extern crate futures; extern crate tokio_core; -- cgit v1.2.3