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>
impl<E: Source> PollEvented<E>
sourcepub(crate) fn new(io: E) -> Result<Self>
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.
sourcepub(crate) fn new_with_interest(io: E, interest: Interest) -> Result<Self>
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.
pub(crate) fn new_with_interest_and_handle( io: E, interest: Interest, handle: Handle, ) -> Result<Self>
sourcepub(crate) fn registration(&self) -> &Registration
pub(crate) fn registration(&self) -> &Registration
Returns a reference to the registration.
sourcepub(crate) fn into_inner(self) -> Result<E>
pub(crate) fn into_inner(self) -> Result<E>
Deregisters the inner io from the registration and returns a Result containing the inner io.