chore: prepare 0.2.0-alpha.2 release (#1465)

2026-09-07 00:00:08 +02:00 · 2019-08-17 23:34:25 -07:00
parent 9f0daad5ac
commit 88b4ec84d7
35 changed files with 260 additions and 120 deletions
@@ -1,6 +1,16 @@
 This changelog only applies to the `tokio` crate proper. Each sub crate
 maintains its own changelog tracking changes made in each respective sub crate.

+# 0.2.0-alpha.2 (August 17, 2019)
+
+### Changed
+- Update `futures` dependency to 0.3.0-alpha.18.
+- Remove `reactor` module.
+
+### Added
+- Add `BufReader` / `BufWriter` (#1438).
+- Update `UdpFramed` to `std::future` (#1370).
+
 # 0.2.0-alpha.1 (August 8, 2019)

 - Switch to `async`, `await`, and `std::future`.
@@ -8,7 +8,7 @@ name = "tokio"
 #   - README.md
 # - Update CHANGELOG.md.
 # - Create "v0.2.x" git tag.
-version = "0.2.0-alpha.1"
+version = "0.2.0-alpha.2"
 edition = "2018"
 authors = ["Tokio Contributors <[email protected]>"]
 license = "MIT"
@@ -62,18 +62,18 @@ futures-util-preview = { version = "=0.3.0-alpha.18", features = ["sink"] }
 # Everything else is optional...
 bytes = { version = "0.4", optional = true }
 num_cpus = { version = "1.8.0", optional = true }
-tokio-codec = { version = "=0.2.0-alpha.1", optional = true, path = "../tokio-codec" }
-tokio-fs = { version = "=0.2.0-alpha.1", optional = true, path = "../tokio-fs" }
-tokio-io = { version = "=0.2.0-alpha.1", optional = true, features = ["util"], path = "../tokio-io" }
-tokio-executor = { version = "=0.2.0-alpha.1", optional = true, path = "../tokio-executor" }
-tokio-macros = { version = "=0.2.0-alpha.1", optional = true, path = "../tokio-macros" }
-tokio-net = { version = "=0.2.0-alpha.1", optional = true, features = ["async-traits"], path = "../tokio-net" }
-tokio-sync = { version = "=0.2.0-alpha.1", optional = true, path = "../tokio-sync", features = ["async-traits"] }
-tokio-timer = { version = "=0.3.0-alpha.1", optional = true, path = "../tokio-timer", features = ["async-traits"] }
+tokio-codec = { version = "=0.2.0-alpha.2", optional = true, path = "../tokio-codec" }
+tokio-fs = { version = "=0.2.0-alpha.2", optional = true, path = "../tokio-fs" }
+tokio-io = { version = "=0.2.0-alpha.2", optional = true, features = ["util"], path = "../tokio-io" }
+tokio-executor = { version = "=0.2.0-alpha.2", optional = true, path = "../tokio-executor" }
+tokio-macros = { version = "=0.2.0-alpha.2", optional = true, path = "../tokio-macros" }
+tokio-net = { version = "=0.2.0-alpha.2", optional = true, features = ["async-traits"], path = "../tokio-net" }
+tokio-sync = { version = "=0.2.0-alpha.2", optional = true, path = "../tokio-sync", features = ["async-traits"] }
+tokio-timer = { version = "=0.3.0-alpha.2", optional = true, path = "../tokio-timer", features = ["async-traits"] }
 tracing-core = { version = "0.1", optional = true }

 [dev-dependencies]
-tokio-test = { version = "=0.2.0-alpha.1", path = "../tokio-test" }
+tokio-test = { version = "0.2.0-alpha.1", path = "../tokio-test" }

 futures-preview = "=0.3.0-alpha.18"
 futures-util-preview = "=0.3.0-alpha.18"
@@ -1,5 +1,7 @@
 # Tokio

+ _NOTE_: Tokio's [`master`](https://github.com/tokio-rs/tokio) branch is currently in the process of moving to [`std::future::Future`](https://doc.rust-lang.org/std/future/trait.Future.html), for `v0.1.x` based tokio releases please check out the [`v0.1.x`](https://github.com/tokio-rs/tokio/tree/v0.1.x) branch.
+
 A runtime for writing reliable, asynchronous, and slim applications with
 the Rust programming language. It is:

@@ -20,7 +22,7 @@ the Rust programming language. It is:
 [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
+[mit-url]: LICENSE
 [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
@@ -28,7 +30,7 @@ the Rust programming language. It is:

 [Website](https://tokio.rs) |
 [Guides](https://tokio.rs/docs/) |
-[API Docs](https://docs.rs/tokio/0.2.0-alpha.1/tokio) |
+[API Docs](https://docs.rs/tokio/0.2.0-alpha.2/tokio) |
 [Chat](https://gitter.im/tokio-rs/tokio)

 ## Overview
@@ -38,61 +40,65 @@ 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,
+* 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.2.0-alpha.1/tokio/net/index.html
-[reactor]: https://docs.rs/tokio/0.2.0-alpha.1/tokio/reactor/index.html
-[scheduler]: https://docs.rs/tokio/0.2.0-alpha.1/tokio/runtime/index.html
+[net]: https://docs.rs/tokio/0.2.0-alpha.2/tokio/net/index.html
+[scheduler]: https://docs.rs/tokio/0.2.0-alpha.2/tokio/runtime/index.html

 ## Example

 A basic TCP echo server with Tokio:

 ```rust
-use tokio::prelude::*;
-use tokio::io::copy;
+#![feature(async_await)]
+
 use tokio::net::TcpListener;
+use tokio::prelude::*;

-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");
+#[tokio::main]
+async fn main() -> Result<(), Box<dyn std::error::Error>> {
+    let addr = "127.0.0.1:8080".parse()?;
+    let mut listener = TcpListener::bind(&addr).unwrap();

-    // 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();
+    loop {
+        let (mut socket, _) = listener.accept().await?;

-            // A future that echos the data and returns how
-            // many bytes were copied...
-            let bytes_copied = copy(reader, writer);
+        tokio::spawn(async move {
+            let mut buf = [0; 1024];

-            // ... 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)
-            });
+            // In a loop, read data from the socket and write the data back.
+            loop {
+                let n = match socket.read(&mut buf).await {
+                    // socket closed
+                    Ok(n) if n == 0 => return,
+                    Ok(n) => n,
+                    Err(e) => {
+                        println!("failed to read from socket; err = {:?}", e);
+                        return;
+                    }
+                };

-            // Spawn the future as a concurrent task.
-            tokio::spawn(handle_conn)
+                // Write the data back
+                if let Err(e) = socket.write_all(&buf[0..n]).await {
+                    println!("failed to write to socket; err = {:?}", e);
+                    return;
+                }
+            }
        });
-
-    // Start the Tokio runtime
-    tokio::run(server);
+    }
 }
 ```

-More examples can be found [here](examples).
+More examples can be found [here](tokio/examples). Note that the `master` branch
+is currently being updated to use `async` / `await`.  The examples are
+not fully ported. Examples for stable Tokio can be found
+[here](https://github.com/tokio-rs/tokio/tree/v0.1.x/tokio/examples).
+

 ## Getting Help

@@ -101,9 +107,69 @@ First, see if the answer to your question can be found in the [Guides] or the
 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.

+[Guides]: https://tokio.rs/docs/
+[API documentation]: https://docs.rs/tokio/0.2.0-alpha.2/tokio
 [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-executor`]: Task executors and related utilities. Includes a
+  single-threaded executor and a multi-threaded, work-stealing, executor.
+
+* [`tokio-fs`]: Filesystem (and standard in / out) APIs.
+
+* [`tokio-codec`]: Utilities for encoding and decoding protocol frames.
+
+* [`tokio-io`]: Asynchronous I/O related traits and utilities.
+
+* [`tokio-macros`]: Macros for usage with Tokio.
+
+* [`tokio-net`]: Event loop that drives I/O resources as well as TCP, UDP, and
+  unix domain socket apis.
+
+* [ `tokio-timer`]: Time related APIs.
+
+[`tokio-codec`]: tokio-codec
+[`tokio-current-thread`]: tokio-current-thread
+[`tokio-executor`]: tokio-executor
+[`tokio-fs`]: tokio-fs
+[`tokio-io`]: tokio-io
+[`tokio-macros`]: tokio-macros
+[`tokio-net`]: tokio-net
+[`tokio-timer`]: tokio-timer
+
+## Related Projects
+
+In addition to the crates in this repository, the Tokio project also maintains
+several other libraries, including:
+
+* [`tracing`] (formerly `tokio-trace`): A framework for application-level
+  tracing and async-aware diagnostics.
+
+* [`mio`]: A low-level, cross-platform abstraction over OS I/O APIs that powers
+  `tokio`.
+
+* [`bytes`]: Utilities for working with bytes, including efficient byte buffers.
+
+[`tracing`]: https://github.com/tokio-rs/tracing
+[`mio`]: https://github.com/tokio-rs/mio
+[`bytes`]: https://github.com/tokio-rs/bytes
+
 ## Supported Rust Versions

 Tokio is built against the latest stable, nightly, and beta Rust releases. The
@@ -1,4 +1,4 @@
-#![doc(html_root_url = "https://docs.rs/tokio/0.2.0-alpha.1")]
+#![doc(html_root_url = "https://docs.rs/tokio/0.2.0-alpha.2")]
 #![warn(
    missing_debug_implementations,
    missing_docs,