tokio-rs/tokio
1
0
Fork 0
mirror of https://github.com/tokio-rs/tokio.git synced 2026-08-27 00:00:12 +02:00
Code Issues Packages Projects Releases Wiki Activity

docs: update API documentation for some crates (#1380)

Browse Source 
Updates API documentation for

- tokio-buf
- tokio-codec
- tokio-current-thread
- tokio-executor
This commit is contained in:
Carl Lerche
2019-08-02 14:35:32 -07:00
committed by GitHub
parent 2c01b3e0e0
commit 878503f965
10 changed files with 80 additions and 84 deletions
Download Patch File Download Diff File Expand all files Collapse all files
tokio-buf/src/lib.rs
+11 -10
View File
@@ -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<Option<Result<Self::Item, Self::Error>>>;
/// Returns the bounds on the remaining length of the stream.
tokio-codec/src/encoder.rs
-3
View File
@@ -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;
tokio-codec/src/lib.rs
+5 -6
View File
@@ -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;
tokio-current-thread/src/lib.rs
+8 -15
View File
@@ -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;
tokio-executor/Cargo.toml
+2 -2
View File
@@ -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" }
tokio-executor/src/executor.rs
+16 -16
View File
@@ -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<Box<dyn Future<Output = ()> + 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");
/// }
tokio-executor/src/global.rs
+3 -5
View File
@@ -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<T>(future: T)
where
tokio-executor/src/lib.rs
+1 -1
View File
@@ -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;
tokio-executor/src/park.rs
+1 -1
View File
@@ -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
tokio-executor/src/typed.rs
+33 -25
View File
@@ -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<T, E>(stream: T, executor: &mut E)
/// -> impl Future<Item = (), Error = ()>
/// use futures_core::{ready, Stream};
/// use std::future::Future;
/// use std::pin::Pin;
/// use std::task::{Context, Poll};
///
/// async fn drain<T, E>(stream: T, executor: &mut E)
/// where
/// T: Stream,
/// T: Stream + Unpin,
/// E: TypedExecutor<Drain<T>>
/// {
/// 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<T: Stream> {
/// pub struct Drain<T> {
/// stream: T,
/// tx: Option<oneshot::Sender<()>>,
/// }
///
/// impl<T: Stream> Future for Drain<T> {
/// type Item = ();
/// type Error = ();
/// impl<T: Stream + Unpin> Future for Drain<T> {
/// type Output = ();
///
/// fn poll(&mut self) -> Poll<Self::Item, Self::Error> {
/// 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<T> {
///
/// ```rust
/// use tokio_executor::TypedExecutor;
/// use futures::{Future, Poll};
///
/// use std::future::Future;
/// use std::pin::Pin;
/// use std::task::{Context, Poll};
///
/// fn example<T>(my_executor: &mut T)
/// where
/// T: TypedExecutor<MyFuture>,
@@ -97,12 +104,11 @@ pub trait TypedExecutor<T> {
/// 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<T> {
///
/// ```rust
/// use tokio_executor::TypedExecutor;
/// use futures::{Future, Poll};
///
/// use std::future::Future;
/// use std::pin::Pin;
/// use std::task::{Context, Poll};
///
/// fn example<T>(my_executor: &mut T)
/// where
@@ -143,12 +152,11 @@ pub trait TypedExecutor<T> {
/// 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(())
/// }
/// }
/// ```