Enum mio_st::poll::PollOption
source · pub enum PollOption {
Edge,
Level,
Oneshot,
}
Expand description
Option supplied when registering an Evented
handle with Poller
.
PollOption
values can be combined together using the various bitwise
operators.
For high level documentation on polling see Poller
.
Difference
An Evented
registration may request edge-triggered or
level-triggered or oneshot events. Evented
handle registered with
oneshot polling option will only receive a single event and then have to
reregister too receive more events.
The difference between the edge-triggered and level-trigger can be described as follows. Supposed that this scenario happens:
- A
TcpStream
is registered withPoller
. - The socket receives 2kb of data.
- A call to
Poller.poll
returns the id associated with the socket indicating readable readiness. - 1kb is read from the socket.
- Another call to
Poller.poll
is made.
If when the socket was registered with Poller
, and edge-triggered events
were requested, then the call to Poller.poll
done in step 5 will
(probably) block despite there being another 1kb still present in the socket
read buffer. The reason for this is that edge-triggered mode delivers events
only when changes occur on the monitored Evented
. So, in step 5 the
caller might end up waiting for some data that is already present inside the
socket buffer.
With edge-triggered events, operations must be performed on the
Evented
type until WouldBlock
is returned. In other words, after
receiving an event indicating readiness for a certain operation, one should
assume that Poller.poll
may never return another event for the same id
and readiness until the operation returns WouldBlock
.
By contrast, when level-triggered notifications was requested, each call
to Poller.poll
will return an event for the socket as long as data
remains in the socket buffer. Though generally, level-triggered events
should be avoided if high performance is a concern.
Since even with edge-triggered events, multiple events can be generated upon
receipt of multiple chunks of data, the caller has the option to set the
oneshot flag. This tells Poller
to disable the associated Evented
after the event is returned from Poller.poll
, note that disabled and
deregistered are not the same thing. Subsequent calls to Poller.poll
will no longer include events for Evented
handles that are disabled even
if the readiness state changes. The handle can be re-enabled by calling
reregister
. When handles are disabled, internal resources used to
monitor the handle are maintained until the handle is deregistered. This
makes re-registering the handle a fast operation.
For example, in the following scenario:
- A
TcpStream
is registered withPoller
. - The socket receives 2kb of data.
- A call to
Poller.poll
returns the id associated with the socket indicating readable readiness. - 2kb is read from the socket.
- Another call to read is issued and
WouldBlock
is returned - The socket receives another 2kb of data.
- Another call to
Poller.poll
is made.
Assuming the socket was registered with Poller
with the oneshot option,
then the call to Poller.poll
in step 7 would block. This is because,
oneshot tells Poller
to disable events for the socket after returning an
event.
In order to receive the event for the data received in step 6, the socket
would need to be reregistered using reregister
.
Variants§
Edge
Edge-triggered notifications.
Level
Level-triggered notifications.
Oneshot
Oneshot notifications.
Trait Implementations§
source§impl Clone for PollOption
impl Clone for PollOption
source§fn clone(&self) -> PollOption
fn clone(&self) -> PollOption
1.0.0 · source§fn clone_from(&mut self, source: &Self)
fn clone_from(&mut self, source: &Self)
source
. Read moresource§impl Debug for PollOption
impl Debug for PollOption
source§impl Ord for PollOption
impl Ord for PollOption
source§fn cmp(&self, other: &PollOption) -> Ordering
fn cmp(&self, other: &PollOption) -> Ordering
1.21.0 · source§fn max(self, other: Self) -> Selfwhere
Self: Sized,
fn max(self, other: Self) -> Selfwhere
Self: Sized,
source§impl PartialEq<PollOption> for PollOption
impl PartialEq<PollOption> for PollOption
source§fn eq(&self, other: &PollOption) -> bool
fn eq(&self, other: &PollOption) -> bool
source§impl PartialOrd<PollOption> for PollOption
impl PartialOrd<PollOption> for PollOption
source§fn partial_cmp(&self, other: &PollOption) -> Option<Ordering>
fn partial_cmp(&self, other: &PollOption) -> Option<Ordering>
1.0.0 · source§fn le(&self, other: &Rhs) -> bool
fn le(&self, other: &Rhs) -> bool
self
and other
) and is used by the <=
operator. Read more