pub struct Registration { /* private fields */ }Expand description
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 register.
Once the association is established, it remains established until the
registration instance is dropped. Subsequent calls to register are
no-ops.
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§
Source§impl Registration
impl Registration
Sourcepub fn new() -> Registration
pub fn new() -> Registration
Create a new Registration.
This registration is not associated with a Reactor instance. Call
register to establish the association.
Sourcepub fn register<T>(&self, io: &T) -> Result<bool>where
T: Evented,
pub fn register<T>(&self, io: &T) -> Result<bool>where
T: Evented,
Register the I/O resource with the default reactor.
This function is safe to call concurrently and repeatedly. However, only the first call will establish the registration. Subsequent calls will be no-ops.
§Return
If the registration happened successfully, Ok(true) is returned.
If an I/O resource has previously been successfully registered,
Ok(false) is returned.
If an error is encountered during registration, Err is returned.
Sourcepub fn deregister<T>(&mut self, io: &T) -> Result<()>where
T: Evented,
pub fn deregister<T>(&mut self, io: &T) -> Result<()>where
T: Evented,
Deregister 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.
Sourcepub fn register_with<T>(&self, io: &T, handle: &Handle) -> Result<bool>where
T: Evented,
pub fn register_with<T>(&self, io: &T, handle: &Handle) -> Result<bool>where
T: Evented,
Register the I/O resource with the specified reactor.
This function is safe to call concurrently and repeatedly. However, only the first call will establish the registration. Subsequent calls will be no-ops.
If the registration happened successfully, Ok(true) is returned.
If an I/O resource has previously been successfully registered,
Ok(false) is returned.
If an error is encountered during registration, Err is returned.
Sourcepub fn poll_read_ready(&self) -> Poll<Ready, Error>
pub fn poll_read_ready(&self) -> Poll<Ready, Error>
Poll 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.
Ensure that register has been called first.
§Return value
There are several possible return values:
-
Ok(Async::Ready(readiness))means that the I/O resource has received a new readiness event. The readiness value is included. -
Ok(NotReady)means that no new readiness events have been received since the last call topoll_read_ready. -
Err(err)means that the registration has encountered an error. This error either represents a permanent internal error or the fact thatregisterwas not called first.
§Panics
This function will panic if called from outside of a task context.
Sourcepub fn take_read_ready(&self) -> Result<Option<Ready>>
pub fn take_read_ready(&self) -> Result<Option<Ready>>
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.
Sourcepub fn poll_write_ready(&self) -> Poll<Ready, Error>
pub fn poll_write_ready(&self) -> Poll<Ready, Error>
Poll 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.
Ensure that register has been called first.
§Return value
There are several possible return values:
-
Ok(Async::Ready(readiness))means that the I/O resource has received a new readiness event. The readiness value is included. -
Ok(NotReady)means that no new readiness events have been received since the last call topoll_write_ready. -
Err(err)means that the registration has encountered an error. This error either represents a permanent internal error or the fact thatregisterwas not called first.
§Panics
This function will panic if called from outside of a task context.
Sourcepub fn take_write_ready(&self) -> Result<Option<Ready>>
pub fn take_write_ready(&self) -> Result<Option<Ready>>
Consume 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.