Struct tokio::io::Registration [−][src]
Associates an I/O resource with the reactor instance that drives it.
A registration represents an I/O resource registered with a Reactor such that it will receive task notifications on readiness. This is the lowest level API for integrating with a reactor.
The association between an I/O resource is made by calling new
. Once
the association is established, it remains established until the
registration instance is dropped.
A registration instance represents two separate readiness streams. One for the read readiness and one for write readiness. These streams are independent and can be consumed from separate tasks.
Note: while Registration
is Sync
, the caller must ensure that
there are at most two tasks that use a registration instance
concurrently. One task for poll_read_ready
and one task for
poll_write_ready
. While violating this requirement is “safe” from a
Rust memory safety point of view, it will result in unexpected behavior
in the form of lost notifications and tasks hanging.
Platform-specific events
Registration
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
impl Registration
[src]
pub fn new<T>(io: &T) -> Result<Registration> where
T: Evented,
[src]
T: Evented,
Registers the I/O resource with the default reactor.
Return
Ok
if the registration happened successfullyErr
if an error was encountered during registration
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 Handle::enter
function.
pub fn new_with_ready<T>(io: &T, ready: Ready) -> Result<Registration> where
T: Evented,
[src]
T: Evented,
Registers the I/O resource with the default reactor, for a specific mio::Ready
state.
new_with_ready
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.
An example to listen to read only
#[cfg(unix)] mio::Ready::from_usize( mio::Ready::readable().as_usize() | mio::unix::UnixReady::error().as_usize() | mio::unix::UnixReady::hup().as_usize() );
Return
Ok
if the registration happened successfullyErr
if an error was encountered during registration
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 Handle::enter
function.
pub fn deregister<T>(&mut self, io: &T) -> Result<()> where
T: Evented,
[src]
T: Evented,
Deregisters the I/O resource from the reactor it is associated with.
This function must be called before the I/O resource associated with the registration is dropped.
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.
Return
If the deregistration was successful, Ok
is returned. Any calls to
Reactor::turn
that happen after a successful call to deregister
will
no longer result in notifications getting sent for this registration.
Err
is returned if an error is encountered.
pub fn poll_read_ready(&self, cx: &mut Context<'_>) -> Poll<Result<Ready>>
[src]
Polls for events on the I/O resource’s read readiness stream.
If the I/O resource receives a new read readiness event since the last
call to poll_read_ready
, it is returned. If it has not, the current
task is notified once a new event is received.
All events except HUP
are edge-triggered. Once HUP
is returned,
the function will always return Ready(HUP)
. This should be treated as
the end of the readiness stream.
Return value
There are several possible return values:
-
Poll::Ready(Ok(readiness))
means that the I/O resource has received a new readiness event. The readiness value is included. -
Poll::Pending
means that no new readiness events have been received since the last call topoll_read_ready
. -
Poll::Ready(Err(err))
means that the registration has encountered an error. This could represent a permanent internal error for example.
Panics
This function will panic if called from outside of a task context.
pub fn take_read_ready(&self) -> Result<Option<Ready>>
[src]
Consume any pending read readiness event.
This function is identical to poll_read_ready
except that it
will not notify the current task when a new event is received. As such,
it is safe to call this function from outside of a task context.
pub fn poll_write_ready(&self, cx: &mut Context<'_>) -> Poll<Result<Ready>>
[src]
Polls for events on the I/O resource’s write readiness stream.
If the I/O resource receives a new write readiness event since the last
call to poll_write_ready
, it is returned. If it has not, the current
task is notified once a new event is received.
All events except HUP
are edge-triggered. Once HUP
is returned,
the function will always return Ready(HUP)
. This should be treated as
the end of the readiness stream.
Return value
There are several possible return values:
-
Poll::Ready(Ok(readiness))
means that the I/O resource has received a new readiness event. The readiness value is included. -
Poll::Pending
means that no new readiness events have been received since the last call topoll_write_ready
. -
Poll::Ready(Err(err))
means that the registration has encountered an error. This could represent a permanent internal error for example.
Panics
This function will panic if called from outside of a task context.
pub fn take_write_ready(&self) -> Result<Option<Ready>>
[src]
Consumes any pending write readiness event.
This function is identical to poll_write_ready
except that it
will not notify the current task when a new event is received. As such,
it is safe to call this function from outside of a task context.
Trait Implementations
impl Debug for Registration
[src]
impl Drop for Registration
[src]
impl Send for Registration
[src]
impl Sync for Registration
[src]
Auto Trait Implementations
Blanket Implementations
impl<T> Any for T where
T: 'static + ?Sized,
[src]
T: 'static + ?Sized,
impl<T> Borrow<T> for T where
T: ?Sized,
[src]
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
[src]
T: ?Sized,
pub fn borrow_mut(&mut self) -> &mut Tⓘ
[src]
impl<T> From<T> for T
[src]
impl<T, U> Into<U> for T where
U: From<T>,
[src]
U: From<T>,
impl<T, U> TryFrom<U> for T where
U: Into<T>,
[src]
U: Into<T>,
type Error = Infallible
The type returned in the event of a conversion error.
pub fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>
[src]
impl<T, U> TryInto<U> for T where
U: TryFrom<T>,
[src]
U: TryFrom<T>,