From 878503f9654e4177627b19e8022826a3d4404002 Mon Sep 17 00:00:00 2001 From: Carl Lerche Date: Fri, 2 Aug 2019 14:35:32 -0700 Subject: [PATCH] docs: update API documentation for some crates (#1380) Updates API documentation for - tokio-buf - tokio-codec - tokio-current-thread - tokio-executor --- tokio-buf/src/lib.rs | 21 ++++++------ tokio-codec/src/encoder.rs | 3 -- tokio-codec/src/lib.rs | 11 +++---- tokio-current-thread/src/lib.rs | 23 +++++-------- tokio-executor/Cargo.toml | 4 +-- tokio-executor/src/executor.rs | 32 +++++++++--------- tokio-executor/src/global.rs | 8 ++--- tokio-executor/src/lib.rs | 2 +- tokio-executor/src/park.rs | 2 +- tokio-executor/src/typed.rs | 58 +++++++++++++++++++-------------- 10 files changed, 80 insertions(+), 84 deletions(-) diff --git a/tokio-buf/src/lib.rs b/tokio-buf/src/lib.rs index fd24f6b95..38575f8ce 100644 --- a/tokio-buf/src/lib.rs +++ b/tokio-buf/src/lib.rs @@ -53,21 +53,22 @@ pub trait BufStream { /// There are several possible return values, each indicating a distinct /// stream state: /// - /// - `Ok(Async::NotReady)` means that this stream's next value is not ready - /// yet. Implementations will ensure that the current task will be notified - /// when the next value may be ready. + /// - `Poll::Pending` means that this stream's next value is not ready yet. + /// Implementations will ensure that the current task will be notified + /// when the next value may be ready. /// - /// - `Ok(Async::Ready(Some(buf)))` means that the stream has successfully - /// produced a value, `buf`, and may produce further values on subsequent - /// `poll_buf` calls. + /// - `Poll::Ready(Some(Ok(buf)))` means that the stream has successfully + /// produced a value, `buf`, and may produce further values on subsequent + /// `poll_buf` calls. /// - /// - `Ok(Async::Ready(None))` means that the stream has terminated, and - /// `poll_buf` should not be invoked again. + /// - `Poll::Ready(None)` means that the stream has terminated, and + /// `poll_buf` should not be invoked again. /// /// # Panics /// - /// Once a stream is finished, i.e. `Ready(None)` has been returned, further - /// calls to `poll_buf` may result in a panic or other "bad behavior". + /// Once a stream is finished, i.e. `Poll::Ready(None)` has been returned, + /// further calls to `poll_buf` may result in a panic or other "bad + /// behavior". fn poll_buf(&mut self, cx: &mut Context<'_>) -> Poll>>; /// Returns the bounds on the remaining length of the stream. diff --git a/tokio-codec/src/encoder.rs b/tokio-codec/src/encoder.rs index 506508032..76fa9dbae 100644 --- a/tokio-codec/src/encoder.rs +++ b/tokio-codec/src/encoder.rs @@ -3,9 +3,6 @@ use std::io; /// Trait of helper objects to write out messages as bytes, for use with /// `FramedWrite`. - -// Note: We can't deprecate this trait, because the deprecation carries through to tokio-codec, and -// there doesn't seem to be a way to un-deprecate the re-export. pub trait Encoder { /// The type of items consumed by the `Encoder` type Item; diff --git a/tokio-codec/src/lib.rs b/tokio-codec/src/lib.rs index 0db815023..437e4d286 100644 --- a/tokio-codec/src/lib.rs +++ b/tokio-codec/src/lib.rs @@ -7,13 +7,12 @@ //! //! Contains adapters to go from streams of bytes, [`AsyncRead`] and //! [`AsyncWrite`], to framed streams implementing [`Sink`] and [`Stream`]. -//! Framed streams are also known as [transports]. +//! Framed streams are also known as transports. //! -//! [`AsyncRead`]: # -//! [`AsyncWrite`]: # -//! [`Sink`]: # -//! [`Stream`]: # -//! [transports]: # +//! [`AsyncRead`]: https://docs.rs/tokio/*/tokio/io/trait.AsyncRead.html +//! [`AsyncWrite`]: https://docs.rs/tokio/*/tokio/io/trait.AsyncWrite.html +//! [`Sink`]: https://docs.rs/futures-sink-preview/*/futures_sink/trait.Sink.html +//! [`Stream`]: https://docs.rs/futures-core-preview/*/futures_core/stream/trait.Stream.html #[macro_use] mod macros; diff --git a/tokio-current-thread/src/lib.rs b/tokio-current-thread/src/lib.rs index 009b13724..7d32b87c6 100644 --- a/tokio-current-thread/src/lib.rs +++ b/tokio-current-thread/src/lib.rs @@ -6,26 +6,19 @@ //! A single-threaded executor which executes tasks on the same thread from which //! they are spawned. //! +//! [`CurrentThread`] is the main type of this crate. It executes tasks on the +//! current thread. The easiest way to start a new [`CurrentThread`] executor +//! is to call [`block_on_all`] with an initial task to seed the executor. All +//! tasks that are being managed by a [`CurrentThread`] executor are able to +//! spawn additional tasks by calling [`spawn`]. //! -//! The crate provides: -//! -//! * [`CurrentThread`] is the main type of this crate. It executes tasks on the current thread. -//! The easiest way to start a new [`CurrentThread`] executor is to call -//! [`block_on_all`] with an initial task to seed the executor. -//! All tasks that are being managed by a [`CurrentThread`] executor are able to -//! spawn additional tasks by calling [`spawn`]. -//! -//! -//! Application authors will not use this crate directly. Instead, they will use the -//! `tokio` crate. Library authors should only depend on `tokio-current-thread` if they -//! are building a custom task executor. -//! -//! For more details, see [executor module] documentation in the Tokio crate. +//! Application authors will not use this crate directly. Instead, they will use +//! the `tokio` crate. Library authors should only depend on +//! `tokio-current-thread` if they are building a custom task executor. //! //! [`CurrentThread`]: struct.CurrentThread.html //! [`spawn`]: fn.spawn.html //! [`block_on_all`]: fn.block_on_all.html -//! [executor module]: https://docs.rs/tokio/0.1/tokio/executor/index.html mod scheduler; diff --git a/tokio-executor/Cargo.toml b/tokio-executor/Cargo.toml index da2303469..68f50f79e 100644 --- a/tokio-executor/Cargo.toml +++ b/tokio-executor/Cargo.toml @@ -23,8 +23,8 @@ categories = ["concurrency", "asynchronous"] publish = false [dependencies] -# crossbeam-utils = "0.6.2" crossbeam-utils = { git = "https://github.com/stjepang/crossbeam", branch = "raw-parker" } [dev-dependencies] -# tokio = { version = "0.2.0", path = "../tokio" } +futures-core-preview = "=0.3.0-alpha.17" +tokio = { version = "*", path = "../tokio" } diff --git a/tokio-executor/src/executor.rs b/tokio-executor/src/executor.rs index 45a65ca15..c03367e39 100644 --- a/tokio-executor/src/executor.rs +++ b/tokio-executor/src/executor.rs @@ -48,20 +48,20 @@ use std::pin::Pin; /// /// # Examples /// -/// ```rust +/// ``` +/// #![feature(async_await)] +/// /// use tokio_executor::Executor; -/// use futures::future::lazy; /// /// # fn docs(my_executor: &mut dyn Executor) { -/// my_executor.spawn(Box::new(lazy(|| { +/// my_executor.spawn(Box::pin(async { /// println!("running on the executor"); -/// Ok(()) -/// }))).unwrap(); +/// })).unwrap(); /// # } /// ``` /// /// [`spawn`]: #tymethod.spawn -/// [`poll`]: https://docs.rs/futures/0.1/futures/future/trait.Future.html#tymethod.poll +/// [`poll`]: https://doc.rust-lang.org/std/future/trait.Future.html#tymethod.poll /// [`TypedExecutor`]: ../trait.TypedExecutor.html pub trait Executor { /// Spawns a future object to run on this executor. @@ -78,15 +78,15 @@ pub trait Executor { /// /// # Examples /// - /// ```rust + /// ``` + /// #![feature(async_await)] + /// /// use tokio_executor::Executor; - /// use futures::future::lazy; /// /// # fn docs(my_executor: &mut dyn Executor) { - /// my_executor.spawn(Box::pin(lazy(|| { + /// my_executor.spawn(Box::pin(async { /// println!("running on the executor"); - /// Ok(()) - /// }))).unwrap(); + /// })).unwrap(); /// # } /// ``` fn spawn(&mut self, future: Pin + Send>>) @@ -109,16 +109,16 @@ pub trait Executor { /// /// # Examples /// - /// ```rust + /// ``` + /// #![feature(async_await)] + /// /// use tokio_executor::Executor; - /// use futures::future::lazy; /// /// # fn docs(my_executor: &mut dyn Executor) { /// if my_executor.status().is_ok() { - /// my_executor.spawn(Box::pin(lazy(|| { + /// my_executor.spawn(Box::pin(async { /// println!("running on the executor"); - /// Ok(()) - /// }))).unwrap(); + /// })).unwrap(); /// } else { /// println!("the executor is not in a good state"); /// } diff --git a/tokio-executor/src/global.rs b/tokio-executor/src/global.rs index 6017d5f73..f95a14863 100644 --- a/tokio-executor/src/global.rs +++ b/tokio-executor/src/global.rs @@ -124,13 +124,11 @@ where /// # Examples /// /// ```no_run -/// use tokio_executor::spawn; -/// use futures::future::lazy; +/// #![feature(async_await)] /// -/// spawn(lazy(|| { +/// tokio::spawn(async { /// println!("running on the default executor"); -/// Ok(()) -/// })); +/// }); /// ``` pub fn spawn(future: T) where diff --git a/tokio-executor/src/lib.rs b/tokio-executor/src/lib.rs index 4e2d32826..37b7751a4 100644 --- a/tokio-executor/src/lib.rs +++ b/tokio-executor/src/lib.rs @@ -51,7 +51,7 @@ //! [`enter`]: fn.enter.html //! [`DefaultExecutor`]: struct.DefaultExecutor.html //! [`Park`]: park/index.html -//! [`Future::poll`]: https://docs.rs/futures/0.1/futures/future/trait.Future.html#tymethod.poll +//! [`Future::poll`]: https://doc.rust-lang.org/std/future/trait.Future.html#tymethod.poll mod enter; mod error; diff --git a/tokio-executor/src/park.rs b/tokio-executor/src/park.rs index e5d6acf4b..750281767 100644 --- a/tokio-executor/src/park.rs +++ b/tokio-executor/src/park.rs @@ -28,7 +28,7 @@ //! Some things to note: //! //! * If [`unpark`] is called before [`park`], the next call to [`park`] will -//! **not** block the thread. +//! **not** block the thread. //! * **Spurious** wakeups are permitted, i.e., the [`park`] method may unblock //! even if [`unpark`] was not called. //! * [`park_timeout`] does the same as [`park`] but allows specifying a maximum diff --git a/tokio-executor/src/typed.rs b/tokio-executor/src/typed.rs index 5fd0f272d..a1125a126 100644 --- a/tokio-executor/src/typed.rs +++ b/tokio-executor/src/typed.rs @@ -20,15 +20,20 @@ use crate::SpawnError; /// such, the function takes a stream and an executor on which the background /// task is spawned. /// -/// ```rust -/// use futures::{try_ready, Future, Stream, Poll}; +/// ``` +/// #![feature(async_await)] +/// /// use tokio::executor::TypedExecutor; /// use tokio::sync::oneshot; /// -/// pub fn drain(stream: T, executor: &mut E) -/// -> impl Future +/// use futures_core::{ready, Stream}; +/// use std::future::Future; +/// use std::pin::Pin; +/// use std::task::{Context, Poll}; +/// +/// async fn drain(stream: T, executor: &mut E) /// where -/// T: Stream, +/// T: Stream + Unpin, /// E: TypedExecutor> /// { /// let (tx, rx) = oneshot::channel(); @@ -38,31 +43,29 @@ use crate::SpawnError; /// tx: Some(tx), /// }).unwrap(); /// -/// rx.map_err(|_| ()) +/// rx.await.unwrap() /// } /// /// // The background task -/// pub struct Drain { +/// pub struct Drain { /// stream: T, /// tx: Option>, /// } /// -/// impl Future for Drain { -/// type Item = (); -/// type Error = (); +/// impl Future for Drain { +/// type Output = (); /// -/// fn poll(&mut self) -> Poll { +/// fn poll(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<()> { /// loop { -/// let item = try_ready!( -/// self.stream.poll() -/// .map_err(|_| ()) +/// let item = ready!( +/// Pin::new(&mut self.stream).poll_next(cx) /// ); /// /// if item.is_none() { break; } /// } /// /// self.tx.take().unwrap().send(()).map_err(|_| ()); -/// Ok(().into()) +/// Poll::Ready(()) /// } /// } /// ``` @@ -86,7 +89,11 @@ pub trait TypedExecutor { /// /// ```rust /// use tokio_executor::TypedExecutor; - /// use futures::{Future, Poll}; + /// + /// use std::future::Future; + /// use std::pin::Pin; + /// use std::task::{Context, Poll}; + /// /// fn example(my_executor: &mut T) /// where /// T: TypedExecutor, @@ -97,12 +104,11 @@ pub trait TypedExecutor { /// struct MyFuture; /// /// impl Future for MyFuture { - /// type Item = (); - /// type Error = (); + /// type Output = (); /// - /// fn poll(&mut self) -> Poll<(), ()> { + /// fn poll(self: Pin<&mut Self>, _cx: &mut Context<'_>) -> Poll<()> { /// println!("running on the executor"); - /// Ok(().into()) + /// Poll::Ready(()) /// } /// } /// ``` @@ -127,7 +133,10 @@ pub trait TypedExecutor { /// /// ```rust /// use tokio_executor::TypedExecutor; - /// use futures::{Future, Poll}; + /// + /// use std::future::Future; + /// use std::pin::Pin; + /// use std::task::{Context, Poll}; /// /// fn example(my_executor: &mut T) /// where @@ -143,12 +152,11 @@ pub trait TypedExecutor { /// struct MyFuture; /// /// impl Future for MyFuture { - /// type Item = (); - /// type Error = (); + /// type Output = (); /// - /// fn poll(&mut self) -> Poll<(), ()> { + /// fn poll(self: Pin<&mut Self>, _cx: &mut Context<'_>) -> Poll<()> { /// println!("running on the executor"); - /// Ok(().into()) + /// Poll::Ready(()) /// } /// } /// ```