Struct tokio_core::reactor::PollEvented
[−]
[src]
pub struct PollEvented<E> { /* fields omitted */ }
A concrete implementation of a stream of readiness notifications for I/O objects that originates from an event loop.
Created by the PollEvented::new
method, each PollEvented
is
associated with a specific event loop and source of events that will be
registered with an event loop.
An instance of PollEvented
is essentially the bridge between the mio
world and the tokio-core
world, providing abstractions to receive
notifications about changes to an object's mio::Ready
state.
Each readiness stream has a number of methods to test whether the underlying
object is readable or writable. Once the methods return that an object is
readable/writable, then it will continue to do so until the need_read
or
need_write
methods are called.
That is, this object is typically wrapped in another form of I/O object. It's the responsibility of the wrapper to inform the readiness stream when a "would block" I/O event is seen. The readiness stream will then take care of any scheduling necessary to get notified when the event is ready again.
You can find more information about creating a custom I/O object online.
Readiness to read/write
A PollEvented
allows listening and waiting for an arbitrary mio::Ready
instance, including the platform-specific contents of mio::Ready
. At most
two future tasks, however, can be waiting on a PollEvented
. The
need_read
and need_write
methods can block two separate tasks, one on
reading and one on writing. Not all I/O events correspond to read/write,
however!
To account for this a PollEvented
gets a little interesting when working
with an arbitrary instance of mio::Ready
that may not map precisely to
"write" and "read" tasks. Currently it is defined that instances of
mio::Ready
that do not return true from is_writable
are all notified
through need_read
, or the read task.
In other words, poll_ready
with the mio::UnixReady::hup
event will block
the read task of this PollEvented
if the hup
event isn't available.
Essentially a good rule of thumb is that if you're using the poll_ready
method you want to also use need_read
to signal blocking and you should
otherwise probably avoid using two tasks on the same PollEvented
.
Methods
impl<E: Evented> PollEvented<E>
[src]
pub fn new(io: E, handle: &Handle) -> Result<PollEvented<E>>
[src]
Creates a new readiness stream associated with the provided
loop_handle
and for the given source
.
This method returns a future which will resolve to the readiness stream when it's ready.
pub fn deregister(self, handle: &Handle) -> Result<()>
[src]
Deregisters this source of events from the reactor core specified.
This method can optionally be called to unregister the underlying I/O
object with the event loop that the handle
provided points to.
Typically this method is not required as this automatically happens when
E
is dropped, but for some use cases the E
object doesn't represent
an owned reference, so dropping it won't automatically unregister with
the event loop.
This consumes self
as it will no longer provide events after the
method is called, and will likely return an error if this PollEvented
was created on a separate event loop from the handle
specified.
impl<E> PollEvented<E>
[src]
pub fn poll_read(&self) -> Async<()>
[src]
Tests to see if this source is ready to be read from or not.
If this stream is not ready for a read then NotReady
will be returned
and the current task will be scheduled to receive a notification when
the stream is readable again. In other words, this method is only safe
to call from within the context of a future's task, typically done in a
Future::poll
method.
This is mostly equivalent to self.poll_ready(Ready::readable())
.
Panics
This function will panic if called outside the context of a future's task.
pub fn poll_write(&self) -> Async<()>
[src]
Tests to see if this source is ready to be written to or not.
If this stream is not ready for a write then NotReady
will be returned
and the current task will be scheduled to receive a notification when
the stream is writable again. In other words, this method is only safe
to call from within the context of a future's task, typically done in a
Future::poll
method.
This is mostly equivalent to self.poll_ready(Ready::writable())
.
Panics
This function will panic if called outside the context of a future's task.
pub fn poll_ready(&self, mask: Ready) -> Async<Ready>
[src]
Test to see whether this source fulfills any condition listed in mask
provided.
The mask
given here is a mio Ready
set of possible events. This can
contain any events like read/write but also platform-specific events
such as hup and error. The mask
indicates events that are interested
in being ready.
If any event in mask
is ready then it is returned through
Async::Ready
. The Ready
set returned is guaranteed to not be empty
and contains all events that are currently ready in the mask
provided.
If no events are ready in the mask
provided then the current task is
scheduled to receive a notification when any of them become ready. If
the writable
event is contained within mask
then this
PollEvented
's write
task will be blocked and otherwise the read
task will be blocked. This is generally only relevant if you're working
with this PollEvented
object on multiple tasks.
Panics
This function will panic if called outside the context of a future's task.
pub fn need_read(&self)
[src]
Indicates to this source of events that the corresponding I/O object is no longer readable, but it needs to be.
This function, like poll_read
, is only safe to call from the context
of a future's task (typically in a Future::poll
implementation). It
informs this readiness stream that the underlying object is no longer
readable, typically because a "would block" error was seen.
All readiness bits associated with this stream except the writable bit will be reset when this method is called. The current task is then scheduled to receive a notification whenever anything changes other than the writable bit. Note that this typically just means the readable bit is used here, but if you're using a custom I/O object for events like hup/error this may also be relevant.
Note that it is also only valid to call this method if poll_read
previously indicated that the object is readable. That is, this function
must always be paired with calls to poll_read
previously.
Panics
This function will panic if called outside the context of a future's task.
pub fn need_write(&self)
[src]
Indicates to this source of events that the corresponding I/O object is no longer writable, but it needs to be.
This function, like poll_write
, is only safe to call from the context
of a future's task (typically in a Future::poll
implementation). It
informs this readiness stream that the underlying object is no longer
writable, typically because a "would block" error was seen.
The flag indicating that this stream is writable is unset and the current task is scheduled to receive a notification when the stream is then again writable.
Note that it is also only valid to call this method if poll_write
previously indicated that the object is writable. That is, this function
must always be paired with calls to poll_write
previously.
Panics
This function will panic if called outside the context of a future's task.
pub fn remote(&self) -> &Remote
[src]
Returns a reference to the event loop handle that this readiness stream is associated with.
ⓘImportant traits for &'a mut Rpub fn get_ref(&self) -> &E
[src]
Returns a shared reference to the underlying I/O object this readiness stream is wrapping.
ⓘImportant traits for &'a mut Rpub fn get_mut(&mut self) -> &mut E
[src]
Returns a mutable reference to the underlying I/O object this readiness stream is wrapping.
Trait Implementations
impl<E: Evented + Debug> Debug for PollEvented<E>
[src]
fn fmt(&self, f: &mut Formatter) -> Result
[src]
Formats the value using the given formatter. Read more
impl<E: Read> Read for PollEvented<E>
[src]
fn read(&mut self, buf: &mut [u8]) -> Result<usize>
[src]
Pull some bytes from this source into the specified buffer, returning how many bytes were read. Read more
unsafe fn initializer(&self) -> Initializer
[src]
read_initializer
)Determines if this Read
er can work with buffers of uninitialized memory. Read more
fn read_to_end(&mut self, buf: &mut Vec<u8>) -> Result<usize, Error>
1.0.0[src]
Read all bytes until EOF in this source, placing them into buf
. Read more
fn read_to_string(&mut self, buf: &mut String) -> Result<usize, Error>
1.0.0[src]
Read all bytes until EOF in this source, appending them to buf
. Read more
fn read_exact(&mut self, buf: &mut [u8]) -> Result<(), Error>
1.6.0[src]
Read the exact number of bytes required to fill buf
. Read more
ⓘImportant traits for &'a mut Rfn by_ref(&mut self) -> &mut Self
1.0.0[src]
Creates a "by reference" adaptor for this instance of Read
. Read more
ⓘImportant traits for Bytes<R>fn bytes(self) -> Bytes<Self>
1.0.0[src]
Transforms this Read
instance to an [Iterator
] over its bytes. Read more
ⓘImportant traits for Chars<R>fn chars(self) -> Chars<Self>
[src]
🔬 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. Read more
ⓘImportant traits for Chain<T, U>fn chain<R>(self, next: R) -> Chain<Self, R> where
R: Read,
1.0.0[src]
R: Read,
Creates an adaptor which will chain this stream with another. Read more
ⓘImportant traits for Take<T>fn take(self, limit: u64) -> Take<Self>
1.0.0[src]
Creates an adaptor which will read at most limit
bytes from it. Read more
impl<E: Write> Write for PollEvented<E>
[src]
fn write(&mut self, buf: &[u8]) -> Result<usize>
[src]
Write a buffer into this object, returning how many bytes were written. Read more
fn flush(&mut self) -> Result<()>
[src]
Flush this output stream, ensuring that all intermediately buffered contents reach their destination. Read more
fn write_all(&mut self, buf: &[u8]) -> Result<(), Error>
1.0.0[src]
Attempts to write an entire buffer into this write. Read more
fn write_fmt(&mut self, fmt: Arguments) -> Result<(), Error>
1.0.0[src]
Writes a formatted string into this writer, returning any error encountered. Read more
ⓘImportant traits for &'a mut Rfn by_ref(&mut self) -> &mut Self
1.0.0[src]
Creates a "by reference" adaptor for this instance of Write
. Read more
impl<E: Read> AsyncRead for PollEvented<E>
[src]
unsafe fn prepare_uninitialized_buffer(&self, buf: &mut [u8]) -> bool
[src]
Prepares an uninitialized buffer to be safe to pass to read
. Returns true
if the supplied buffer was zeroed out. Read more
fn read_buf<B>(&mut self, buf: &mut B) -> Result<Async<usize>, Error> where
B: BufMut,
[src]
B: BufMut,
Pull some bytes from this source into the specified Buf
, returning how many bytes were read. Read more
fn framed<T>(self, codec: T) -> Framed<Self, T> where
Self: AsyncWrite,
T: Decoder + Encoder,
[src]
Self: AsyncWrite,
T: Decoder + Encoder,
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. Read more
fn split(self) -> (ReadHalf<Self>, WriteHalf<Self>) where
Self: AsyncWrite,
[src]
Self: AsyncWrite,
Helper method for splitting this read/write object into two halves. Read more
impl<E: Write> AsyncWrite for PollEvented<E>
[src]
fn shutdown(&mut self) -> Poll<(), Error>
[src]
Initiates or attempts to shut down this writer, returning success when the I/O connection has completely shut down. Read more
fn write_buf<B>(&mut self, buf: &mut B) -> Result<Async<usize>, Error> where
B: Buf,
[src]
B: Buf,
Write a Buf
into this value, returning how many bytes were written. Read more
impl<'a, E> Read for &'a PollEvented<E> where
&'a E: Read,
[src]
&'a E: Read,
fn read(&mut self, buf: &mut [u8]) -> Result<usize>
[src]
Pull some bytes from this source into the specified buffer, returning how many bytes were read. Read more
unsafe fn initializer(&self) -> Initializer
[src]
read_initializer
)Determines if this Read
er can work with buffers of uninitialized memory. Read more
fn read_to_end(&mut self, buf: &mut Vec<u8>) -> Result<usize, Error>
1.0.0[src]
Read all bytes until EOF in this source, placing them into buf
. Read more
fn read_to_string(&mut self, buf: &mut String) -> Result<usize, Error>
1.0.0[src]
Read all bytes until EOF in this source, appending them to buf
. Read more
fn read_exact(&mut self, buf: &mut [u8]) -> Result<(), Error>
1.6.0[src]
Read the exact number of bytes required to fill buf
. Read more
ⓘImportant traits for &'a mut Rfn by_ref(&mut self) -> &mut Self
1.0.0[src]
Creates a "by reference" adaptor for this instance of Read
. Read more
ⓘImportant traits for Bytes<R>fn bytes(self) -> Bytes<Self>
1.0.0[src]
Transforms this Read
instance to an [Iterator
] over its bytes. Read more
ⓘImportant traits for Chars<R>fn chars(self) -> Chars<Self>
[src]
🔬 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. Read more
ⓘImportant traits for Chain<T, U>fn chain<R>(self, next: R) -> Chain<Self, R> where
R: Read,
1.0.0[src]
R: Read,
Creates an adaptor which will chain this stream with another. Read more
ⓘImportant traits for Take<T>fn take(self, limit: u64) -> Take<Self>
1.0.0[src]
Creates an adaptor which will read at most limit
bytes from it. Read more
impl<'a, E> Write for &'a PollEvented<E> where
&'a E: Write,
[src]
&'a E: Write,
fn write(&mut self, buf: &[u8]) -> Result<usize>
[src]
Write a buffer into this object, returning how many bytes were written. Read more
fn flush(&mut self) -> Result<()>
[src]
Flush this output stream, ensuring that all intermediately buffered contents reach their destination. Read more
fn write_all(&mut self, buf: &[u8]) -> Result<(), Error>
1.0.0[src]
Attempts to write an entire buffer into this write. Read more
fn write_fmt(&mut self, fmt: Arguments) -> Result<(), Error>
1.0.0[src]
Writes a formatted string into this writer, returning any error encountered. Read more
ⓘImportant traits for &'a mut Rfn by_ref(&mut self) -> &mut Self
1.0.0[src]
Creates a "by reference" adaptor for this instance of Write
. Read more
impl<'a, E> AsyncRead for &'a PollEvented<E> where
&'a E: Read,
[src]
&'a E: Read,
unsafe fn prepare_uninitialized_buffer(&self, buf: &mut [u8]) -> bool
[src]
Prepares an uninitialized buffer to be safe to pass to read
. Returns true
if the supplied buffer was zeroed out. Read more
fn read_buf<B>(&mut self, buf: &mut B) -> Result<Async<usize>, Error> where
B: BufMut,
[src]
B: BufMut,
Pull some bytes from this source into the specified Buf
, returning how many bytes were read. Read more
fn framed<T>(self, codec: T) -> Framed<Self, T> where
Self: AsyncWrite,
T: Decoder + Encoder,
[src]
Self: AsyncWrite,
T: Decoder + Encoder,
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. Read more
fn split(self) -> (ReadHalf<Self>, WriteHalf<Self>) where
Self: AsyncWrite,
[src]
Self: AsyncWrite,
Helper method for splitting this read/write object into two halves. Read more
impl<'a, E> AsyncWrite for &'a PollEvented<E> where
&'a E: Write,
[src]
&'a E: Write,
fn shutdown(&mut self) -> Poll<(), Error>
[src]
Initiates or attempts to shut down this writer, returning success when the I/O connection has completely shut down. Read more
fn write_buf<B>(&mut self, buf: &mut B) -> Result<Async<usize>, Error> where
B: Buf,
[src]
B: Buf,
Write a Buf
into this value, returning how many bytes were written. Read more