Struct tokio::io::poll_evented::PollEvented

source ·
pub(crate) struct PollEvented<E: Source> {
    io: Option<E>,
    registration: Registration,
}
Expand description

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.

Fields§

§io: Option<E>§registration: Registration

Implementations§

source§

impl<E: Source> PollEvented<E>

source

pub(crate) fn new(io: E) -> Result<Self>

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 function.

source

pub(crate) fn new_with_interest(io: E, interest: Interest) -> Result<Self>

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 function.

source

pub(crate) fn new_with_interest_and_handle( io: E, interest: Interest, handle: Handle, ) -> Result<Self>

source

pub(crate) fn registration(&self) -> &Registration

Returns a reference to the registration.

source

pub(crate) fn into_inner(self) -> Result<E>

Deregisters the inner io from the registration and returns a Result containing the inner io.

source§

impl<E: Source> PollEvented<E>

source

pub(crate) unsafe fn poll_read<'a>( &'a self, cx: &mut Context<'_>, buf: &mut ReadBuf<'_>, ) -> Poll<Result<()>>
where &'a E: Read + 'a,

source

pub(crate) fn poll_write<'a>( &'a self, cx: &mut Context<'_>, buf: &[u8], ) -> Poll<Result<usize>>
where &'a E: Write + 'a,

source

pub(crate) fn poll_write_vectored<'a>( &'a self, cx: &mut Context<'_>, bufs: &[IoSlice<'_>], ) -> Poll<Result<usize>>
where &'a E: Write + 'a,

Trait Implementations§

source§

impl<E: Source + Debug> Debug for PollEvented<E>

source§

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more
source§

impl<E: Source> Deref for PollEvented<E>

§

type Target = E

The resulting type after dereferencing.
source§

fn deref(&self) -> &E

Dereferences the value.
source§

impl<E: Source> Drop for PollEvented<E>

source§

fn drop(&mut self)

Executes the destructor for this type. Read more
source§

impl<E: Source> RefUnwindSafe for PollEvented<E>

source§

impl<E: Source> UnwindSafe for PollEvented<E>

Auto Trait Implementations§

§

impl<E> Freeze for PollEvented<E>
where E: Freeze,

§

impl<E> Send for PollEvented<E>
where E: Send,

§

impl<E> Sync for PollEvented<E>
where E: Sync,

§

impl<E> Unpin for PollEvented<E>
where E: Unpin,

Blanket Implementations§

source§

impl<T> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T, U> Into<U> for T
where U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.