wasmtime 17.0.1 → 18.0.3

data/ext/cargo-vendor/tokio-1.36.0/src/io/mod.rs

@@ -0,0 +1,292 @@
+//! Traits, helpers, and type definitions for asynchronous I/O functionality.
+//!
+//! This module is the asynchronous version of `std::io`. Primarily, it
+//! defines two traits, [`AsyncRead`] and [`AsyncWrite`], which are asynchronous
+//! versions of the [`Read`] and [`Write`] traits in the standard library.
+//!
+//! # `AsyncRead` and `AsyncWrite`
+//!
+//! Like the standard library's [`Read`] and [`Write`] traits, [`AsyncRead`] and
+//! [`AsyncWrite`] provide the most general interface for reading and writing
+//! input and output. Unlike the standard library's traits, however, they are
+//! _asynchronous_ — meaning that reading from or writing to a `tokio::io`
+//! type will _yield_ to the Tokio scheduler when IO is not ready, rather than
+//! blocking. This allows other tasks to run while waiting on IO.
+//!
+//! Another difference is that `AsyncRead` and `AsyncWrite` only contain
+//! core methods needed to provide asynchronous reading and writing
+//! functionality. Instead, utility methods are defined in the [`AsyncReadExt`]
+//! and [`AsyncWriteExt`] extension traits. These traits are automatically
+//! implemented for all values that implement `AsyncRead` and `AsyncWrite`
+//! respectively.
+//!
+//! End users will rarely interact directly with `AsyncRead` and
+//! `AsyncWrite`. Instead, they will use the async functions defined in the
+//! extension traits. Library authors are expected to implement `AsyncRead`
+//! and `AsyncWrite` in order to provide types that behave like byte streams.
+//!
+//! Even with these differences, Tokio's `AsyncRead` and `AsyncWrite` traits
+//! can be used in almost exactly the same manner as the standard library's
+//! `Read` and `Write`. Most types in the standard library that implement `Read`
+//! and `Write` have asynchronous equivalents in `tokio` that implement
+//! `AsyncRead` and `AsyncWrite`, such as [`File`] and [`TcpStream`].
+//!
+//! For example, the standard library documentation introduces `Read` by
+//! [demonstrating][std_example] reading some bytes from a [`std::fs::File`]. We
+//! can do the same with [`tokio::fs::File`][`File`]:
+//!
+//! ```no_run
+//! use tokio::io::{self, AsyncReadExt};
+//! use tokio::fs::File;
+//!
+//! #[tokio::main]
+//! async fn main() -> io::Result<()> {
+//!     let mut f = File::open("foo.txt").await?;
+//!     let mut buffer = [0; 10];
+//!
+//!     // read up to 10 bytes
+//!     let n = f.read(&mut buffer).await?;
+//!
+//!     println!("The bytes: {:?}", &buffer[..n]);
+//!     Ok(())
+//! }
+//! ```
+//!
+//! [`File`]: crate::fs::File
+//! [`TcpStream`]: crate::net::TcpStream
+//! [`std::fs::File`]: std::fs::File
+//! [std_example]: std::io#read-and-write
+//!
+//! ## Buffered Readers and Writers
+//!
+//! Byte-based interfaces are unwieldy and can be inefficient, as we'd need to be
+//! making near-constant calls to the operating system. To help with this,
+//! `std::io` comes with [support for _buffered_ readers and writers][stdbuf],
+//! and therefore, `tokio::io` does as well.
+//!
+//! Tokio provides an async version of the [`std::io::BufRead`] trait,
+//! [`AsyncBufRead`]; and async [`BufReader`] and [`BufWriter`] structs, which
+//! wrap readers and writers. These wrappers use a buffer, reducing the number
+//! of calls and providing nicer methods for accessing exactly what you want.
+//!
+//! For example, [`BufReader`] works with the [`AsyncBufRead`] trait to add
+//! extra methods to any async reader:
+//!
+//! ```no_run
+//! use tokio::io::{self, BufReader, AsyncBufReadExt};
+//! use tokio::fs::File;
+//!
+//! #[tokio::main]
+//! async fn main() -> io::Result<()> {
+//!     let f = File::open("foo.txt").await?;
+//!     let mut reader = BufReader::new(f);
+//!     let mut buffer = String::new();
+//!
+//!     // read a line into buffer
+//!     reader.read_line(&mut buffer).await?;
+//!
+//!     println!("{}", buffer);
+//!     Ok(())
+//! }
+//! ```
+//!
+//! [`BufWriter`] doesn't add any new ways of writing; it just buffers every call
+//! to [`write`](crate::io::AsyncWriteExt::write). However, you **must** flush
+//! [`BufWriter`] to ensure that any buffered data is written.
+//!
+//! ```no_run
+//! use tokio::io::{self, BufWriter, AsyncWriteExt};
+//! use tokio::fs::File;
+//!
+//! #[tokio::main]
+//! async fn main() -> io::Result<()> {
+//!     let f = File::create("foo.txt").await?;
+//!     {
+//!         let mut writer = BufWriter::new(f);
+//!
+//!         // Write a byte to the buffer.
+//!         writer.write(&[42u8]).await?;
+//!
+//!         // Flush the buffer before it goes out of scope.
+//!         writer.flush().await?;
+//!
+//!     } // Unless flushed or shut down, the contents of the buffer is discarded on drop.
+//!
+//!     Ok(())
+//! }
+//! ```
+//!
+//! [stdbuf]: std::io#bufreader-and-bufwriter
+//! [`std::io::BufRead`]: std::io::BufRead
+//! [`AsyncBufRead`]: crate::io::AsyncBufRead
+//! [`BufReader`]: crate::io::BufReader
+//! [`BufWriter`]: crate::io::BufWriter
+//!
+//! ## Implementing `AsyncRead` and `AsyncWrite`
+//!
+//! Because they are traits, we can implement [`AsyncRead`] and [`AsyncWrite`] for
+//! our own types, as well. Note that these traits must only be implemented for
+//! non-blocking I/O types that integrate with the futures type system. In
+//! other words, these types must never block the thread, and instead the
+//! current task is notified when the I/O resource is ready.
+//!
+//! ## Conversion to and from Stream/Sink
+//!
+//! It is often convenient to encapsulate the reading and writing of bytes in a
+//! [`Stream`] or [`Sink`] of data.
+//!
+//! Tokio provides simple wrappers for converting [`AsyncRead`] to [`Stream`]
+//! and vice-versa in the [tokio-util] crate, see [`ReaderStream`] and
+//! [`StreamReader`].
+//!
+//! There are also utility traits that abstract the asynchronous buffering
+//! necessary to write your own adaptors for encoding and decoding bytes to/from
+//! your structured data, allowing to transform something that implements
+//! [`AsyncRead`]/[`AsyncWrite`] into a [`Stream`]/[`Sink`], see [`Decoder`] and
+//! [`Encoder`] in the [tokio-util::codec] module.
+//!
+//! [tokio-util]: https://docs.rs/tokio-util
+//! [tokio-util::codec]: https://docs.rs/tokio-util/latest/tokio_util/codec/index.html
+//!
+//! # Standard input and output
+//!
+//! Tokio provides asynchronous APIs to standard [input], [output], and [error].
+//! These APIs are very similar to the ones provided by `std`, but they also
+//! implement [`AsyncRead`] and [`AsyncWrite`].
+//!
+//! Note that the standard input / output APIs  **must** be used from the
+//! context of the Tokio runtime, as they require Tokio-specific features to
+//! function. Calling these functions outside of a Tokio runtime will panic.
+//!
+//! [input]: fn@stdin
+//! [output]: fn@stdout
+//! [error]: fn@stderr
+//!
+//! # `std` re-exports
+//!
+//! Additionally, [`Error`], [`ErrorKind`], [`Result`], and [`SeekFrom`] are
+//! re-exported from `std::io` for ease of use.
+//!
+//! [`AsyncRead`]: trait@AsyncRead
+//! [`AsyncWrite`]: trait@AsyncWrite
+//! [`AsyncReadExt`]: trait@AsyncReadExt
+//! [`AsyncWriteExt`]: trait@AsyncWriteExt
+//! ["codec"]: https://docs.rs/tokio-util/latest/tokio_util/codec/index.html
+//! [`Encoder`]: https://docs.rs/tokio-util/latest/tokio_util/codec/trait.Encoder.html
+//! [`Decoder`]: https://docs.rs/tokio-util/latest/tokio_util/codec/trait.Decoder.html
+//! [`ReaderStream`]: https://docs.rs/tokio-util/latest/tokio_util/io/struct.ReaderStream.html
+//! [`StreamReader`]: https://docs.rs/tokio-util/latest/tokio_util/io/struct.StreamReader.html
+//! [`Error`]: struct@Error
+//! [`ErrorKind`]: enum@ErrorKind
+//! [`Result`]: type@Result
+//! [`Read`]: std::io::Read
+//! [`SeekFrom`]: enum@SeekFrom
+//! [`Sink`]: https://docs.rs/futures/0.3/futures/sink/trait.Sink.html
+//! [`Stream`]: https://docs.rs/futures/0.3/futures/stream/trait.Stream.html
+//! [`Write`]: std::io::Write
+
+#![cfg_attr(
+    not(all(feature = "rt", feature = "net")),
+    allow(dead_code, unused_imports)
+)]
+
+cfg_io_blocking! {
+    pub(crate) mod blocking;
+}
+
+mod async_buf_read;
+pub use self::async_buf_read::AsyncBufRead;
+
+mod async_read;
+pub use self::async_read::AsyncRead;
+
+mod async_seek;
+pub use self::async_seek::AsyncSeek;
+
+mod async_write;
+pub use self::async_write::AsyncWrite;
+
+mod read_buf;
+pub use self::read_buf::ReadBuf;
+
+// Re-export some types from `std::io` so that users don't have to deal
+// with conflicts when `use`ing `tokio::io` and `std::io`.
+#[doc(no_inline)]
+pub use std::io::{Error, ErrorKind, Result, SeekFrom};
+
+cfg_io_driver_impl! {
+    pub(crate) mod interest;
+    pub(crate) mod ready;
+
+    cfg_net! {
+        pub use interest::Interest;
+        pub use ready::Ready;
+    }
+
+    #[cfg_attr(target_os = "wasi", allow(unused_imports))]
+    mod poll_evented;
+
+    #[cfg(not(loom))]
+    #[cfg_attr(target_os = "wasi", allow(unused_imports))]
+    pub(crate) use poll_evented::PollEvented;
+}
+
+cfg_aio! {
+    /// BSD-specific I/O types.
+    pub mod bsd {
+        mod poll_aio;
+
+        pub use poll_aio::{Aio, AioEvent, AioSource};
+    }
+}
+
+cfg_net_unix! {
+    mod async_fd;
+
+    pub mod unix {
+        //! Asynchronous IO structures specific to Unix-like operating systems.
+        pub use super::async_fd::{AsyncFd, AsyncFdReadyGuard, AsyncFdReadyMutGuard, TryIoError};
+    }
+}
+
+cfg_io_std! {
+    mod stdio_common;
+
+    mod stderr;
+    pub use stderr::{stderr, Stderr};
+
+    mod stdin;
+    pub use stdin::{stdin, Stdin};
+
+    mod stdout;
+    pub use stdout::{stdout, Stdout};
+}
+
+cfg_io_util! {
+    mod split;
+    pub use split::{split, ReadHalf, WriteHalf};
+    mod join;
+    pub use join::{join, Join};
+
+    pub(crate) mod seek;
+    pub(crate) mod util;
+    pub use util::{
+        copy, copy_bidirectional, copy_buf, duplex, empty, repeat, sink, AsyncBufReadExt, AsyncReadExt, AsyncSeekExt, AsyncWriteExt,
+        BufReader, BufStream, BufWriter, DuplexStream, Empty, Lines, Repeat, Sink, Split, Take,
+    };
+}
+
+cfg_not_io_util! {
+    cfg_process! {
+        pub(crate) mod util;
+    }
+}
+
+cfg_io_blocking! {
+    /// Types in this module can be mocked out in tests.
+    mod sys {
+        // TODO: don't rename
+        pub(crate) use crate::blocking::spawn_blocking as run;
+        pub(crate) use crate::blocking::JoinHandle as Blocking;
+    }
+}

data/ext/cargo-vendor/tokio-1.36.0/src/io/poll_evented.rs

@@ -0,0 +1,277 @@
+use crate::io::interest::Interest;
+use crate::runtime::io::Registration;
+use crate::runtime::scheduler;
+
+use mio::event::Source;
+use std::fmt;
+use std::io;
+use std::ops::Deref;
+use std::panic::{RefUnwindSafe, UnwindSafe};
+
+cfg_io_driver! {
+    /// Associates an I/O resource that implements the [`std::io::Read`] and/or
+    /// [`std::io::Write`] traits with the reactor that drives it.
+    ///
+    /// `PollEvented` uses [`Registration`] internally to take a type that
+    /// implements [`mio::event::Source`] as well as [`std::io::Read`] and/or
+    /// [`std::io::Write`] and associate it with a reactor that will drive it.
+    ///
+    /// Once the [`mio::event::Source`] type is wrapped by `PollEvented`, it can be
+    /// used from within the future's execution model. As such, the
+    /// `PollEvented` type provides [`AsyncRead`] and [`AsyncWrite`]
+    /// implementations using the underlying I/O resource as well as readiness
+    /// events provided by the reactor.
+    ///
+    /// **Note**: While `PollEvented` is `Sync` (if the underlying I/O type is
+    /// `Sync`), the caller must ensure that there are at most two tasks that
+    /// use a `PollEvented` instance concurrently. One for reading and one for
+    /// writing. While violating this requirement is "safe" from a Rust memory
+    /// model point of view, it will result in unexpected behavior in the form
+    /// of lost notifications and tasks hanging.
+    ///
+    /// ## Readiness events
+    ///
+    /// Besides just providing [`AsyncRead`] and [`AsyncWrite`] implementations,
+    /// this type also supports access to the underlying readiness event stream.
+    /// While similar in function to what [`Registration`] provides, the
+    /// semantics are a bit different.
+    ///
+    /// Two functions are provided to access the readiness events:
+    /// [`poll_read_ready`] and [`poll_write_ready`]. These functions return the
+    /// current readiness state of the `PollEvented` instance. If
+    /// [`poll_read_ready`] indicates read readiness, immediately calling
+    /// [`poll_read_ready`] again will also indicate read readiness.
+    ///
+    /// When the operation is attempted and is unable to succeed due to the I/O
+    /// resource not being ready, the caller must call [`clear_readiness`].
+    /// This clears the readiness state until a new readiness event is received.
+    ///
+    /// This allows the caller to implement additional functions. For example,
+    /// [`TcpListener`] implements `poll_accept` by using [`poll_read_ready`] and
+    /// [`clear_readiness`].
+    ///
+    /// ## Platform-specific events
+    ///
+    /// `PollEvented` also allows receiving platform-specific `mio::Ready` events.
+    /// These events are included as part of the read readiness event stream. The
+    /// write readiness event stream is only for `Ready::writable()` events.
+    ///
+    /// [`AsyncRead`]: crate::io::AsyncRead
+    /// [`AsyncWrite`]: crate::io::AsyncWrite
+    /// [`TcpListener`]: crate::net::TcpListener
+    /// [`clear_readiness`]: Registration::clear_readiness
+    /// [`poll_read_ready`]: Registration::poll_read_ready
+    /// [`poll_write_ready`]: Registration::poll_write_ready
+    pub(crate) struct PollEvented<E: Source> {
+        io: Option<E>,
+        registration: Registration,
+    }
+}
+
+// ===== impl PollEvented =====
+
+impl<E: Source> PollEvented<E> {
+    /// Creates a new `PollEvented` associated with the default reactor.
+    ///
+    /// The returned `PollEvented` has readable and writable interests. For more control, use
+    /// [`Self::new_with_interest`].
+    ///
+    /// # Panics
+    ///
+    /// This function panics if thread-local runtime is not set.
+    ///
+    /// The runtime is usually set implicitly when this function is called
+    /// from a future driven by a tokio runtime, otherwise runtime can be set
+    /// explicitly with [`Runtime::enter`](crate::runtime::Runtime::enter) function.
+    #[track_caller]
+    #[cfg_attr(feature = "signal", allow(unused))]
+    pub(crate) fn new(io: E) -> io::Result<Self> {
+        PollEvented::new_with_interest(io, Interest::READABLE | Interest::WRITABLE)
+    }
+
+    /// Creates a new `PollEvented` associated with the default reactor, for
+    /// specific `Interest` state. `new_with_interest` should be used over `new`
+    /// when you need control over the readiness state, such as when a file
+    /// descriptor only allows reads. This does not add `hup` or `error` so if
+    /// you are interested in those states, you will need to add them to the
+    /// readiness state passed to this function.
+    ///
+    /// # Panics
+    ///
+    /// This function panics if thread-local runtime is not set.
+    ///
+    /// The runtime is usually set implicitly when this function is called from
+    /// a future driven by a tokio runtime, otherwise runtime can be set
+    /// explicitly with [`Runtime::enter`](crate::runtime::Runtime::enter)
+    /// function.
+    #[track_caller]
+    #[cfg_attr(feature = "signal", allow(unused))]
+    pub(crate) fn new_with_interest(io: E, interest: Interest) -> io::Result<Self> {
+        Self::new_with_interest_and_handle(io, interest, scheduler::Handle::current())
+    }
+
+    #[track_caller]
+    pub(crate) fn new_with_interest_and_handle(
+        mut io: E,
+        interest: Interest,
+        handle: scheduler::Handle,
+    ) -> io::Result<Self> {
+        let registration = Registration::new_with_interest_and_handle(&mut io, interest, handle)?;
+        Ok(Self {
+            io: Some(io),
+            registration,
+        })
+    }
+
+    /// Returns a reference to the registration.
+    #[cfg(feature = "net")]
+    pub(crate) fn registration(&self) -> &Registration {
+        &self.registration
+    }
+
+    /// Deregisters the inner io from the registration and returns a Result containing the inner io.
+    #[cfg(any(feature = "net", feature = "process"))]
+    pub(crate) fn into_inner(mut self) -> io::Result<E> {
+        let mut inner = self.io.take().unwrap(); // As io shouldn't ever be None, just unwrap here.
+        self.registration.deregister(&mut inner)?;
+        Ok(inner)
+    }
+
+    #[cfg(all(feature = "process", target_os = "linux"))]
+    pub(crate) fn poll_read_ready(&self, cx: &mut Context<'_>) -> Poll<io::Result<()>> {
+        self.registration
+            .poll_read_ready(cx)
+            .map_err(io::Error::from)
+            .map_ok(|_| ())
+    }
+
+    /// Re-register under new runtime with `interest`.
+    #[cfg(all(feature = "process", target_os = "linux"))]
+    pub(crate) fn reregister(&mut self, interest: Interest) -> io::Result<()> {
+        let io = self.io.as_mut().unwrap(); // As io shouldn't ever be None, just unwrap here.
+        let _ = self.registration.deregister(io);
+        self.registration =
+            Registration::new_with_interest_and_handle(io, interest, scheduler::Handle::current())?;
+
+        Ok(())
+    }
+}
+
+feature! {
+    #![any(feature = "net", all(unix, feature = "process"))]
+
+    use crate::io::ReadBuf;
+    use std::task::{Context, Poll};
+
+    impl<E: Source> PollEvented<E> {
+        // Safety: The caller must ensure that `E` can read into uninitialized memory
+        pub(crate) unsafe fn poll_read<'a>(
+            &'a self,
+            cx: &mut Context<'_>,
+            buf: &mut ReadBuf<'_>,
+        ) -> Poll<io::Result<()>>
+        where
+            &'a E: io::Read + 'a,
+        {
+            use std::io::Read;
+
+            loop {
+                let evt = ready!(self.registration.poll_read_ready(cx))?;
+
+                let b = &mut *(buf.unfilled_mut() as *mut [std::mem::MaybeUninit<u8>] as *mut [u8]);
+                let len = b.len();
+
+                match self.io.as_ref().unwrap().read(b) {
+                    Ok(n) => {
+                        // if we read a partially full buffer, this is sufficient on unix to show
+                        // that the socket buffer has been drained.  Unfortunately this assumption
+                        // fails for level-triggered selectors (like on Windows or poll even for
+                        // UNIX): https://github.com/tokio-rs/tokio/issues/5866
+                        if n > 0 && (!cfg!(windows) && !cfg!(mio_unsupported_force_poll_poll) && n < len) {
+                            self.registration.clear_readiness(evt);
+                        }
+
+                        // Safety: We trust `TcpStream::read` to have filled up `n` bytes in the
+                        // buffer.
+                        buf.assume_init(n);
+                        buf.advance(n);
+                        return Poll::Ready(Ok(()));
+                    },
+                    Err(e) if e.kind() == io::ErrorKind::WouldBlock => {
+                        self.registration.clear_readiness(evt);
+                    }
+                    Err(e) => return Poll::Ready(Err(e)),
+                }
+            }
+        }
+
+        pub(crate) fn poll_write<'a>(&'a self, cx: &mut Context<'_>, buf: &[u8]) -> Poll<io::Result<usize>>
+        where
+            &'a E: io::Write + 'a,
+        {
+            use std::io::Write;
+
+            loop {
+                let evt = ready!(self.registration.poll_write_ready(cx))?;
+
+                match self.io.as_ref().unwrap().write(buf) {
+                    Ok(n) => {
+                        // if we write only part of our buffer, this is sufficient on unix to show
+                        // that the socket buffer is full.  Unfortunately this assumption
+                        // fails for level-triggered selectors (like on Windows or poll even for
+                        // UNIX): https://github.com/tokio-rs/tokio/issues/5866
+                        if n > 0 && (!cfg!(windows) && !cfg!(mio_unsupported_force_poll_poll) && n < buf.len()) {
+                            self.registration.clear_readiness(evt);
+                        }
+
+                        return Poll::Ready(Ok(n));
+                    },
+                    Err(e) if e.kind() == io::ErrorKind::WouldBlock => {
+                        self.registration.clear_readiness(evt);
+                    }
+                    Err(e) => return Poll::Ready(Err(e)),
+                }
+            }
+        }
+
+        #[cfg(any(feature = "net", feature = "process"))]
+        pub(crate) fn poll_write_vectored<'a>(
+            &'a self,
+            cx: &mut Context<'_>,
+            bufs: &[io::IoSlice<'_>],
+        ) -> Poll<io::Result<usize>>
+        where
+            &'a E: io::Write + 'a,
+        {
+            use std::io::Write;
+            self.registration.poll_write_io(cx, || self.io.as_ref().unwrap().write_vectored(bufs))
+        }
+    }
+}
+
+impl<E: Source> UnwindSafe for PollEvented<E> {}
+
+impl<E: Source> RefUnwindSafe for PollEvented<E> {}
+
+impl<E: Source> Deref for PollEvented<E> {
+    type Target = E;
+
+    fn deref(&self) -> &E {
+        self.io.as_ref().unwrap()
+    }
+}
+
+impl<E: Source + fmt::Debug> fmt::Debug for PollEvented<E> {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        f.debug_struct("PollEvented").field("io", &self.io).finish()
+    }
+}
+
+impl<E: Source> Drop for PollEvented<E> {
+    fn drop(&mut self) {
+        if let Some(mut io) = self.io.take() {
+            // Ignore errors
+            let _ = self.registration.deregister(&mut io);
+        }
+    }
+}