Struct tokio_reactor::PollEvented

pub struct PollEvented<E: Evented> { /* fields omitted */ }

Associates an I/O resource that implements the std::Read and / or std::Write traits with the reactor that drives it.

PollEvented uses Registration internally to take a type that implements mio::Evented as well as std::Read and or std::Write and associate it with a reactor that will drive it.

Once the mio::Evented 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_read_ready or clear_write_ready. 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_write_ready.

pub fn poll_accept(&mut self) -> Poll<(net::TcpStream, SocketAddr), io::Error> {
    let ready = Ready::readable();

    try_ready!(self.poll_evented.poll_read_ready(ready));

    match self.poll_evented.get_ref().accept_std() {
        Ok(pair) => Ok(Async::Ready(pair)),
        Err(ref e) if e.kind() == io::ErrorKind::WouldBlock => {
            self.poll_evented.clear_read_ready(ready);
            Ok(Async::NotReady)
        }
        Err(e) => Err(e),
    }
}

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.

Methods

impl<E> PollEvented<E> where     E: Evented,

Important traits for PollEvented<E>

impl<E> Read for PollEvented<E> where
    E: Evented + Read, impl<E> Write for PollEvented<E> where
    E: Evented + Write, impl<'a, E> Read for &'a PollEvented<E> where
    E: Evented,
    &'a E: Read, impl<'a, E> Write for &'a PollEvented<E> where
    E: Evented,
    &'a E: Write, 

pub fn new(io: E) -> PollEvented<E>

Creates a new PollEvented associated with the default reactor.

pub fn new_with_handle(io: E, handle: &Handle) -> Result<Self>

Creates a new PollEvented associated with the specified reactor.

pub fn get_ref(&self) -> &E

Returns a shared reference to the underlying I/O object this readiness stream is wrapping.

pub fn get_mut(&mut self) -> &mut E

Returns a mutable reference to the underlying I/O object this readiness stream is wrapping.

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

Consumes self, returning the inner I/O object

This function will deregister the I/O resource from the reactor before returning. If the deregistration operation fails, an error is returned.

Note that deregistering does not guarantee that the I/O resource can be registered with a different reactor. Some I/O resource types can only be associated with a single reactor instance for their lifetime.

pub fn poll_read_ready(&self, mask: Ready) -> Poll<Ready, Error>

Check the I/O resource's read readiness state.

The mask argument allows specifying what readiness to notify on. This can be any value, including platform specific readiness, except writable. HUP is always implicitly included on platforms that support it.

If the resource is not ready for a read then Async::NotReady is returned and the current task is notified once a new event is received.

The I/O resource will remain in a read-ready state until readiness is cleared by calling clear_read_ready.

Panics

This function panics if:

• ready includes writable.
• called from outside of a task context.

pub fn clear_read_ready(&self, ready: Ready) -> Result<()>

Clears the I/O resource's read readiness state and registers the current task to be notified once a read readiness event is received.

After calling this function, poll_read_ready will return NotReady until a new read readiness event has been received.

The mask argument specifies the readiness bits to clear. This may not include writable or hup.

Panics

This function panics if:

• ready includes writable or HUP
• called from outside of a task context.

pub fn poll_write_ready(&self) -> Poll<Ready, Error>

Check the I/O resource's write readiness state.

This always checks for writable readiness and also checks for HUP readiness on platforms that support it.

If the resource is not ready for a write then Async::NotReady is returned and the current task is notified once a new event is received.

The I/O resource will remain in a write-ready state until readiness is cleared by calling clear_write_ready.

Panics

This function panics if:

• ready contains bits besides writable and hup.
• called from outside of a task context.

pub fn clear_write_ready(&self) -> Result<()>

Resets the I/O resource's write readiness state and registers the current task to be notified once a write readiness event is received.

This only clears writable readiness. HUP (on platforms that support HUP) cannot be cleared as it is a final state.

After calling this function, poll_write_ready(Ready::writable()) will return NotReady until a new read readiness event has been received.

Panics

This function will panic if called from outside of a task context.

Trait Implementations

impl<E> Read for PollEvented<E> where     E: Evented + Read,

fn read(&mut self, buf: &mut [u8]) -> Result<usize>

Pull some bytes from this source into the specified buffer, returning how many bytes were read.

unsafe fn initializer(&self) -> Initializer

🔬 This is a nightly-only experimental API. (read_initializer)

Determines if this Reader can work with buffers of uninitialized memory.

fn read_to_end(&mut self, buf: &mut Vec<u8>) -> Result<usize, Error>

Read all bytes until EOF in this source, placing them into buf.

fn read_to_string(&mut self, buf: &mut String) -> Result<usize, Error>

Read all bytes until EOF in this source, appending them to buf.

fn read_exact(&mut self, buf: &mut [u8]) -> Result<(), Error>

Read the exact number of bytes required to fill buf.

fn by_ref(&mut self) -> &mut Self

Creates a "by reference" adaptor for this instance of Read.

fn bytes(self) -> Bytes<Self>

Transforms this Read instance to an [Iterator] over its bytes.

fn chars(self) -> Chars<Self>

Deprecated since 1.27.0

: Use str::from_utf8 instead: https://doc.rust-lang.org/nightly/std/str/struct.Utf8Error.html#examples

🔬 This is a nightly-only experimental API. (io)

the semantics of a partial read/write of where errors happen is currently unclear and may change

Transforms this Read instance to an [Iterator] over [char]s.

fn chain<R>(self, next: R) -> Chain<Self, R> where     R: Read,

Creates an adaptor which will chain this stream with another.

fn take(self, limit: u64) -> Take<Self>

Creates an adaptor which will read at most limit bytes from it.

impl<E> Write for PollEvented<E> where     E: Evented + Write,

fn write(&mut self, buf: &[u8]) -> Result<usize>

Write a buffer into this object, returning how many bytes were written.

fn flush(&mut self) -> Result<()>

Flush this output stream, ensuring that all intermediately buffered contents reach their destination.

fn write_all(&mut self, buf: &[u8]) -> Result<(), Error>

Attempts to write an entire buffer into this write.

fn write_fmt(&mut self, fmt: Arguments) -> Result<(), Error>

Writes a formatted string into this writer, returning any error encountered.

fn by_ref(&mut self) -> &mut Self

Creates a "by reference" adaptor for this instance of Write.

impl<E> AsyncRead for PollEvented<E> where     E: Evented + Read,

unsafe fn prepare_uninitialized_buffer(&self, buf: &mut [u8]) -> bool

Prepares an uninitialized buffer to be safe to pass to read. Returns true if the supplied buffer was zeroed out.

fn poll_read(&mut self, buf: &mut [u8]) -> Result<Async<usize>, Error>

Attempt to read from the AsyncRead into buf.

fn read_buf<B>(&mut self, buf: &mut B) -> Result<Async<usize>, Error> where     B: BufMut,

Pull some bytes from this source into the specified Buf, returning how many bytes were read.

fn framed<T>(self, codec: T) -> Framed<Self, T> where     Self: AsyncWrite,     T: Decoder + Encoder,

Deprecated since 0.1.7

: Use tokio_codec::Decoder::framed instead

Provides a Stream and Sink interface for reading and writing to this Io object, using Decode and Encode to read and write the raw data.

fn split(self) -> (ReadHalf<Self>, WriteHalf<Self>) where     Self: AsyncWrite,

Helper method for splitting this read/write object into two halves.

impl<E> AsyncWrite for PollEvented<E> where     E: Evented + Write,

fn shutdown(&mut self) -> Poll<(), Error>

Initiates or attempts to shut down this writer, returning success when the I/O connection has completely shut down.

fn poll_write(&mut self, buf: &[u8]) -> Result<Async<usize>, Error>

Attempt to write bytes from buf into the object.

fn poll_flush(&mut self) -> Result<Async<()>, Error>

Attempt to flush the object, ensuring that any buffered data reach their destination.

fn write_buf<B>(&mut self, buf: &mut B) -> Result<Async<usize>, Error> where     B: Buf,

Write a Buf into this value, returning how many bytes were written.

impl<'a, E> Read for &'a PollEvented<E> where     E: Evented,     &'a E: Read,

fn read(&mut self, buf: &mut [u8]) -> Result<usize>

Pull some bytes from this source into the specified buffer, returning how many bytes were read.

unsafe fn initializer(&self) -> Initializer

🔬 This is a nightly-only experimental API. (read_initializer)

Determines if this Reader can work with buffers of uninitialized memory.

fn read_to_end(&mut self, buf: &mut Vec<u8>) -> Result<usize, Error>

Read all bytes until EOF in this source, placing them into buf.

fn read_to_string(&mut self, buf: &mut String) -> Result<usize, Error>

Read all bytes until EOF in this source, appending them to buf.

fn read_exact(&mut self, buf: &mut [u8]) -> Result<(), Error>

Read the exact number of bytes required to fill buf.

fn by_ref(&mut self) -> &mut Self

Creates a "by reference" adaptor for this instance of Read.

fn bytes(self) -> Bytes<Self>

Transforms this Read instance to an [Iterator] over its bytes.

fn chars(self) -> Chars<Self>

Deprecated since 1.27.0

: Use str::from_utf8 instead: https://doc.rust-lang.org/nightly/std/str/struct.Utf8Error.html#examples

🔬 This is a nightly-only experimental API. (io)

the semantics of a partial read/write of where errors happen is currently unclear and may change

Transforms this Read instance to an [Iterator] over [char]s.

fn chain<R>(self, next: R) -> Chain<Self, R> where     R: Read,

Creates an adaptor which will chain this stream with another.

fn take(self, limit: u64) -> Take<Self>

Creates an adaptor which will read at most limit bytes from it.

impl<'a, E> Write for &'a PollEvented<E> where     E: Evented,     &'a E: Write,

fn write(&mut self, buf: &[u8]) -> Result<usize>

Write a buffer into this object, returning how many bytes were written.

fn flush(&mut self) -> Result<()>

Flush this output stream, ensuring that all intermediately buffered contents reach their destination.

fn write_all(&mut self, buf: &[u8]) -> Result<(), Error>

Attempts to write an entire buffer into this write.

fn write_fmt(&mut self, fmt: Arguments) -> Result<(), Error>

Writes a formatted string into this writer, returning any error encountered.

fn by_ref(&mut self) -> &mut Self

Creates a "by reference" adaptor for this instance of Write.

impl<'a, E> AsyncRead for &'a PollEvented<E> where     E: Evented,     &'a E: Read,

unsafe fn prepare_uninitialized_buffer(&self, buf: &mut [u8]) -> bool

Prepares an uninitialized buffer to be safe to pass to read. Returns true if the supplied buffer was zeroed out.

fn poll_read(&mut self, buf: &mut [u8]) -> Result<Async<usize>, Error>

Attempt to read from the AsyncRead into buf.

fn read_buf<B>(&mut self, buf: &mut B) -> Result<Async<usize>, Error> where     B: BufMut,

Pull some bytes from this source into the specified Buf, returning how many bytes were read.

fn framed<T>(self, codec: T) -> Framed<Self, T> where     Self: AsyncWrite,     T: Decoder + Encoder,

Deprecated since 0.1.7

: Use tokio_codec::Decoder::framed instead

Provides a Stream and Sink interface for reading and writing to this Io object, using Decode and Encode to read and write the raw data.

fn split(self) -> (ReadHalf<Self>, WriteHalf<Self>) where     Self: AsyncWrite,

Helper method for splitting this read/write object into two halves.

impl<'a, E> AsyncWrite for &'a PollEvented<E> where     E: Evented,     &'a E: Write,

fn shutdown(&mut self) -> Poll<(), Error>

Initiates or attempts to shut down this writer, returning success when the I/O connection has completely shut down.

fn poll_write(&mut self, buf: &[u8]) -> Result<Async<usize>, Error>

Attempt to write bytes from buf into the object.

fn poll_flush(&mut self) -> Result<Async<()>, Error>

Attempt to flush the object, ensuring that any buffered data reach their destination.

fn write_buf<B>(&mut self, buf: &mut B) -> Result<Async<usize>, Error> where     B: Buf,

Write a Buf into this value, returning how many bytes were written.

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

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

Formats the value using the given formatter.

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

fn drop(&mut self)

Executes the destructor for this type.