pub struct PollEvented<E: Evented> { /* private fields */ }
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::Evented
as well as std::io::Read
and or
std::io::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_read_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.
Implementations§
Source§impl<E> PollEvented<E>where
E: Evented,
impl<E> PollEvented<E>where
E: Evented,
Sourcepub fn new(io: E) -> PollEvented<E> ⓘ
pub fn new(io: E) -> PollEvented<E> ⓘ
Creates a new PollEvented
associated with the default reactor.
Sourcepub fn new_with_handle(io: E, handle: &Handle) -> Result<Self>
pub fn new_with_handle(io: E, handle: &Handle) -> Result<Self>
Creates a new PollEvented
associated with the specified reactor.
Sourcepub fn get_ref(&self) -> &E
pub fn get_ref(&self) -> &E
Returns a shared reference to the underlying I/O object this readiness stream is wrapping.
Sourcepub fn get_mut(&mut self) -> &mut E
pub fn get_mut(&mut self) -> &mut E
Returns a mutable reference to the underlying I/O object this readiness stream is wrapping.
Sourcepub fn into_inner(self) -> Result<E>
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.
Sourcepub fn poll_read_ready(&self, mask: Ready) -> Poll<Ready, Error>
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.
Sourcepub fn clear_read_ready(&self, ready: Ready) -> Result<()>
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.
Sourcepub fn poll_write_ready(&self) -> Poll<Ready, Error>
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 besideswritable
andhup
.- called from outside of a task context.
Sourcepub fn clear_write_ready(&self) -> Result<()>
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 write readiness event has been received.
§Panics
This function will panic if called from outside of a task context.
Trait Implementations§
Source§impl<'a, E> AsyncRead for &'a PollEvented<E>
impl<'a, E> AsyncRead for &'a PollEvented<E>
Source§unsafe fn prepare_uninitialized_buffer(&self, buf: &mut [u8]) -> bool
unsafe fn prepare_uninitialized_buffer(&self, buf: &mut [u8]) -> bool
read
. Returns
true
if the supplied buffer was zeroed out. Read moreSource§fn read_buf<B>(&mut self, buf: &mut B) -> Result<Async<usize>, Error>
fn read_buf<B>(&mut self, buf: &mut B) -> Result<Async<usize>, Error>
BufMut
, returning
how many bytes were read. Read moreSource§fn framed<T>(self, codec: T) -> Framed<Self, T>where
T: Encoder + Decoder,
Self: Sized + AsyncWrite,
fn framed<T>(self, codec: T) -> Framed<Self, T>where
T: Encoder + Decoder,
Self: Sized + AsyncWrite,
Stream
and Sink
interface for reading and writing to this
I/O object, using Decode
and Encode
to read and write the raw data. Read moreSource§impl<E> AsyncRead for PollEvented<E>
impl<E> AsyncRead for PollEvented<E>
Source§unsafe fn prepare_uninitialized_buffer(&self, buf: &mut [u8]) -> bool
unsafe fn prepare_uninitialized_buffer(&self, buf: &mut [u8]) -> bool
read
. Returns
true
if the supplied buffer was zeroed out. Read moreSource§fn read_buf<B>(&mut self, buf: &mut B) -> Result<Async<usize>, Error>
fn read_buf<B>(&mut self, buf: &mut B) -> Result<Async<usize>, Error>
BufMut
, returning
how many bytes were read. Read moreSource§fn framed<T>(self, codec: T) -> Framed<Self, T>where
T: Encoder + Decoder,
Self: Sized + AsyncWrite,
fn framed<T>(self, codec: T) -> Framed<Self, T>where
T: Encoder + Decoder,
Self: Sized + AsyncWrite,
Stream
and Sink
interface for reading and writing to this
I/O object, using Decode
and Encode
to read and write the raw data. Read moreSource§impl<'a, E> AsyncWrite for &'a PollEvented<E>
impl<'a, E> AsyncWrite for &'a PollEvented<E>
Source§fn shutdown(&mut self) -> Poll<(), Error>
fn shutdown(&mut self) -> Poll<(), Error>
Source§fn poll_write(&mut self, buf: &[u8]) -> Result<Async<usize>, Error>
fn poll_write(&mut self, buf: &[u8]) -> Result<Async<usize>, Error>
buf
into the object. Read moreSource§impl<E> AsyncWrite for PollEvented<E>
impl<E> AsyncWrite for PollEvented<E>
Source§fn shutdown(&mut self) -> Poll<(), Error>
fn shutdown(&mut self) -> Poll<(), Error>
Source§fn poll_write(&mut self, buf: &[u8]) -> Result<Async<usize>, Error>
fn poll_write(&mut self, buf: &[u8]) -> Result<Async<usize>, Error>
buf
into the object. Read moreSource§impl<E: Evented> Drop for PollEvented<E>
impl<E: Evented> Drop for PollEvented<E>
Source§impl<'a, E> Read for &'a PollEvented<E>
impl<'a, E> Read for &'a PollEvented<E>
Source§fn read(&mut self, buf: &mut [u8]) -> Result<usize>
fn read(&mut self, buf: &mut [u8]) -> Result<usize>
1.36.0 · Source§fn read_vectored(&mut self, bufs: &mut [IoSliceMut<'_>]) -> Result<usize, Error>
fn read_vectored(&mut self, bufs: &mut [IoSliceMut<'_>]) -> Result<usize, Error>
read
, except that it reads into a slice of buffers. Read moreSource§fn is_read_vectored(&self) -> bool
fn is_read_vectored(&self) -> bool
can_vector
)1.0.0 · Source§fn read_to_end(&mut self, buf: &mut Vec<u8>) -> Result<usize, Error>
fn read_to_end(&mut self, buf: &mut Vec<u8>) -> Result<usize, Error>
buf
. Read more1.0.0 · Source§fn read_to_string(&mut self, buf: &mut String) -> Result<usize, Error>
fn read_to_string(&mut self, buf: &mut String) -> Result<usize, Error>
buf
. Read more1.6.0 · Source§fn read_exact(&mut self, buf: &mut [u8]) -> Result<(), Error>
fn read_exact(&mut self, buf: &mut [u8]) -> Result<(), Error>
buf
. Read moreSource§fn read_buf(&mut self, buf: BorrowedCursor<'_>) -> Result<(), Error>
fn read_buf(&mut self, buf: BorrowedCursor<'_>) -> Result<(), Error>
read_buf
)Source§fn read_buf_exact(&mut self, cursor: BorrowedCursor<'_>) -> Result<(), Error>
fn read_buf_exact(&mut self, cursor: BorrowedCursor<'_>) -> Result<(), Error>
read_buf
)cursor
. Read more1.0.0 · Source§fn by_ref(&mut self) -> &mut Selfwhere
Self: Sized,
fn by_ref(&mut self) -> &mut Selfwhere
Self: Sized,
Read
. Read moreSource§impl<E> Read for PollEvented<E>
impl<E> Read for PollEvented<E>
Source§fn read(&mut self, buf: &mut [u8]) -> Result<usize>
fn read(&mut self, buf: &mut [u8]) -> Result<usize>
1.36.0 · Source§fn read_vectored(&mut self, bufs: &mut [IoSliceMut<'_>]) -> Result<usize, Error>
fn read_vectored(&mut self, bufs: &mut [IoSliceMut<'_>]) -> Result<usize, Error>
read
, except that it reads into a slice of buffers. Read moreSource§fn is_read_vectored(&self) -> bool
fn is_read_vectored(&self) -> bool
can_vector
)1.0.0 · Source§fn read_to_end(&mut self, buf: &mut Vec<u8>) -> Result<usize, Error>
fn read_to_end(&mut self, buf: &mut Vec<u8>) -> Result<usize, Error>
buf
. Read more1.0.0 · Source§fn read_to_string(&mut self, buf: &mut String) -> Result<usize, Error>
fn read_to_string(&mut self, buf: &mut String) -> Result<usize, Error>
buf
. Read more1.6.0 · Source§fn read_exact(&mut self, buf: &mut [u8]) -> Result<(), Error>
fn read_exact(&mut self, buf: &mut [u8]) -> Result<(), Error>
buf
. Read moreSource§fn read_buf(&mut self, buf: BorrowedCursor<'_>) -> Result<(), Error>
fn read_buf(&mut self, buf: BorrowedCursor<'_>) -> Result<(), Error>
read_buf
)Source§fn read_buf_exact(&mut self, cursor: BorrowedCursor<'_>) -> Result<(), Error>
fn read_buf_exact(&mut self, cursor: BorrowedCursor<'_>) -> Result<(), Error>
read_buf
)cursor
. Read more1.0.0 · Source§fn by_ref(&mut self) -> &mut Selfwhere
Self: Sized,
fn by_ref(&mut self) -> &mut Selfwhere
Self: Sized,
Read
. Read moreSource§impl<'a, E> Write for &'a PollEvented<E>
impl<'a, E> Write for &'a PollEvented<E>
Source§fn write(&mut self, buf: &[u8]) -> Result<usize>
fn write(&mut self, buf: &[u8]) -> Result<usize>
Source§fn flush(&mut self) -> Result<()>
fn flush(&mut self) -> Result<()>
Source§fn is_write_vectored(&self) -> bool
fn is_write_vectored(&self) -> bool
can_vector
)1.0.0 · Source§fn write_all(&mut self, buf: &[u8]) -> Result<(), Error>
fn write_all(&mut self, buf: &[u8]) -> Result<(), Error>
Source§fn write_all_vectored(&mut self, bufs: &mut [IoSlice<'_>]) -> Result<(), Error>
fn write_all_vectored(&mut self, bufs: &mut [IoSlice<'_>]) -> Result<(), Error>
write_all_vectored
)Source§impl<E> Write for PollEvented<E>
impl<E> Write for PollEvented<E>
Source§fn write(&mut self, buf: &[u8]) -> Result<usize>
fn write(&mut self, buf: &[u8]) -> Result<usize>
Source§fn flush(&mut self) -> Result<()>
fn flush(&mut self) -> Result<()>
Source§fn is_write_vectored(&self) -> bool
fn is_write_vectored(&self) -> bool
can_vector
)1.0.0 · Source§fn write_all(&mut self, buf: &[u8]) -> Result<(), Error>
fn write_all(&mut self, buf: &[u8]) -> Result<(), Error>
Source§fn write_all_vectored(&mut self, bufs: &mut [IoSlice<'_>]) -> Result<(), Error>
fn write_all_vectored(&mut self, bufs: &mut [IoSlice<'_>]) -> Result<(), Error>
write_all_vectored
)Auto Trait Implementations§
impl<E> !Freeze for PollEvented<E>
impl<E> !RefUnwindSafe for PollEvented<E>
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,
impl<E> !UnwindSafe for PollEvented<E>
Blanket Implementations§
Source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
Source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Source§impl<R> ReadBytesExt for R
impl<R> ReadBytesExt for R
Source§fn read_u8(&mut self) -> Result<u8, Error>
fn read_u8(&mut self) -> Result<u8, Error>
Source§fn read_i8(&mut self) -> Result<i8, Error>
fn read_i8(&mut self) -> Result<i8, Error>
Source§fn read_u16<T>(&mut self) -> Result<u16, Error>where
T: ByteOrder,
fn read_u16<T>(&mut self) -> Result<u16, Error>where
T: ByteOrder,
Source§fn read_i16<T>(&mut self) -> Result<i16, Error>where
T: ByteOrder,
fn read_i16<T>(&mut self) -> Result<i16, Error>where
T: ByteOrder,
Source§fn read_u24<T>(&mut self) -> Result<u32, Error>where
T: ByteOrder,
fn read_u24<T>(&mut self) -> Result<u32, Error>where
T: ByteOrder,
Source§fn read_i24<T>(&mut self) -> Result<i32, Error>where
T: ByteOrder,
fn read_i24<T>(&mut self) -> Result<i32, Error>where
T: ByteOrder,
Source§fn read_u32<T>(&mut self) -> Result<u32, Error>where
T: ByteOrder,
fn read_u32<T>(&mut self) -> Result<u32, Error>where
T: ByteOrder,
Source§fn read_i32<T>(&mut self) -> Result<i32, Error>where
T: ByteOrder,
fn read_i32<T>(&mut self) -> Result<i32, Error>where
T: ByteOrder,
Source§fn read_u48<T>(&mut self) -> Result<u64, Error>where
T: ByteOrder,
fn read_u48<T>(&mut self) -> Result<u64, Error>where
T: ByteOrder,
Source§fn read_i48<T>(&mut self) -> Result<i64, Error>where
T: ByteOrder,
fn read_i48<T>(&mut self) -> Result<i64, Error>where
T: ByteOrder,
Source§fn read_u64<T>(&mut self) -> Result<u64, Error>where
T: ByteOrder,
fn read_u64<T>(&mut self) -> Result<u64, Error>where
T: ByteOrder,
Source§fn read_i64<T>(&mut self) -> Result<i64, Error>where
T: ByteOrder,
fn read_i64<T>(&mut self) -> Result<i64, Error>where
T: ByteOrder,
Source§fn read_u128<T>(&mut self) -> Result<u128, Error>where
T: ByteOrder,
fn read_u128<T>(&mut self) -> Result<u128, Error>where
T: ByteOrder,
Source§fn read_i128<T>(&mut self) -> Result<i128, Error>where
T: ByteOrder,
fn read_i128<T>(&mut self) -> Result<i128, Error>where
T: ByteOrder,
Source§fn read_uint<T>(&mut self, nbytes: usize) -> Result<u64, Error>where
T: ByteOrder,
fn read_uint<T>(&mut self, nbytes: usize) -> Result<u64, Error>where
T: ByteOrder,
Source§fn read_int<T>(&mut self, nbytes: usize) -> Result<i64, Error>where
T: ByteOrder,
fn read_int<T>(&mut self, nbytes: usize) -> Result<i64, Error>where
T: ByteOrder,
Source§fn read_uint128<T>(&mut self, nbytes: usize) -> Result<u128, Error>where
T: ByteOrder,
fn read_uint128<T>(&mut self, nbytes: usize) -> Result<u128, Error>where
T: ByteOrder,
Source§fn read_int128<T>(&mut self, nbytes: usize) -> Result<i128, Error>where
T: ByteOrder,
fn read_int128<T>(&mut self, nbytes: usize) -> Result<i128, Error>where
T: ByteOrder,
Source§fn read_f32<T>(&mut self) -> Result<f32, Error>where
T: ByteOrder,
fn read_f32<T>(&mut self) -> Result<f32, Error>where
T: ByteOrder,
Source§fn read_f64<T>(&mut self) -> Result<f64, Error>where
T: ByteOrder,
fn read_f64<T>(&mut self) -> Result<f64, Error>where
T: ByteOrder,
Source§fn read_u16_into<T>(&mut self, dst: &mut [u16]) -> Result<(), Error>where
T: ByteOrder,
fn read_u16_into<T>(&mut self, dst: &mut [u16]) -> Result<(), Error>where
T: ByteOrder,
Source§fn read_u32_into<T>(&mut self, dst: &mut [u32]) -> Result<(), Error>where
T: ByteOrder,
fn read_u32_into<T>(&mut self, dst: &mut [u32]) -> Result<(), Error>where
T: ByteOrder,
Source§fn read_u64_into<T>(&mut self, dst: &mut [u64]) -> Result<(), Error>where
T: ByteOrder,
fn read_u64_into<T>(&mut self, dst: &mut [u64]) -> Result<(), Error>where
T: ByteOrder,
Source§fn read_u128_into<T>(&mut self, dst: &mut [u128]) -> Result<(), Error>where
T: ByteOrder,
fn read_u128_into<T>(&mut self, dst: &mut [u128]) -> Result<(), Error>where
T: ByteOrder,
Source§fn read_i8_into(&mut self, dst: &mut [i8]) -> Result<(), Error>
fn read_i8_into(&mut self, dst: &mut [i8]) -> Result<(), Error>
Source§fn read_i16_into<T>(&mut self, dst: &mut [i16]) -> Result<(), Error>where
T: ByteOrder,
fn read_i16_into<T>(&mut self, dst: &mut [i16]) -> Result<(), Error>where
T: ByteOrder,
Source§fn read_i32_into<T>(&mut self, dst: &mut [i32]) -> Result<(), Error>where
T: ByteOrder,
fn read_i32_into<T>(&mut self, dst: &mut [i32]) -> Result<(), Error>where
T: ByteOrder,
Source§fn read_i64_into<T>(&mut self, dst: &mut [i64]) -> Result<(), Error>where
T: ByteOrder,
fn read_i64_into<T>(&mut self, dst: &mut [i64]) -> Result<(), Error>where
T: ByteOrder,
Source§fn read_i128_into<T>(&mut self, dst: &mut [i128]) -> Result<(), Error>where
T: ByteOrder,
fn read_i128_into<T>(&mut self, dst: &mut [i128]) -> Result<(), Error>where
T: ByteOrder,
Source§fn read_f32_into<T>(&mut self, dst: &mut [f32]) -> Result<(), Error>where
T: ByteOrder,
fn read_f32_into<T>(&mut self, dst: &mut [f32]) -> Result<(), Error>where
T: ByteOrder,
Source§fn read_f32_into_unchecked<T>(&mut self, dst: &mut [f32]) -> Result<(), Error>where
T: ByteOrder,
fn read_f32_into_unchecked<T>(&mut self, dst: &mut [f32]) -> Result<(), Error>where
T: ByteOrder,
read_f32_into
instead