README.md
1## Examples of `tokio-core`
2
3This directory contains a number of examples showcasing various capabilities of
4the `tokio_core` crate. Most of these examples also leverage the `futures` and
5`tokio_io` crates, along with a number of other miscellaneous dependencies for
6various tasks.
7
8All examples can be executed with:
9
10```
11cargo run --example $name
12```
13
14A high level description of each example is:
15
16* `hello` - a tiny server that simply writes "Hello!" to all connected clients
17 and then terminates the connection, should help see how to create and
18 initialize `tokio_core`.
19* `echo` - this is your standard TCP "echo server" which simply accepts
20 connections and then echos back any contents that are read from each connected
21 client.
22* `echo-udp` - again your standard "echo server", except for UDP instead of TCP.
23 This will echo back any packets received to the original sender.
24* `echo-threads` - servers the same purpose as the `echo` example, except this
25 shows off using multiple cores on a machine for doing I/O processing.
26* `connect` - this is a `nc`-like clone which can be used to interact with most
27 other examples. The program creates a TCP connection or UDP socket to sends
28 all information read on stdin to the remote peer, displaying any data received
29 on stdout. Often quite useful when interacting with the various other servers
30 here!
31* `chat` - this spins up a local TCP server which will broadcast from any
32 connected client to all other connected clients. You can connect to this in
33 multiple terminals and use it to chat between the terminals.
34* `proxy` - an example proxy server that will forward all connected TCP clients
35 to the remote address specified when starting the program.
36* `sink` - a benchmark-like example which shows writing 0s infinitely to any
37 connected client.
38* `tinyhttp` - a tiny HTTP/1.1 server which doesn't support HTTP request bodies
39 showcasing running on multiple cores, working with futures and spawning
40 tasks, and finally framing a TCP connection to discrete request/response
41 objects.
42* `udp-codec` - an example of using the `UdpCodec` trait along with a small
43 ping-pong protocol happening locally.
44* `compress` - an echo-like server where instead of echoing back everything read
45 it echos back a gzip-compressed version of everything read! All compression
46 occurs on a CPU pool to offload work from the event loop.
47* `tinydb` - an in-memory database which shows sharing state between all
48 connected clients, notably the key/value store of this database.
49
50If you've got an example you'd like to see here, please feel free to open an
51issue. Otherwise if you've got an example you'd like to add, please feel free
52to make a PR!
53