Struct polling::Poller

source ·
pub struct Poller { /* private fields */ }
Expand description

Waits for I/O events.

Implementations§

source§

impl Poller

source

pub fn new() -> Result<Poller>

Creates a new poller.

§Examples
use polling::Poller;

let poller = Poller::new()?;
source

pub fn supports_level(&self) -> bool

Tell whether or not this Poller supports level-triggered polling.

source

pub fn supports_edge(&self) -> bool

Tell whether or not this Poller supports edge-triggered polling.

source

pub unsafe fn add( &self, source: impl AsRawSource, interest: Event, ) -> Result<()>

Adds a file descriptor or socket to the poller.

A file descriptor or socket is considered readable or writable when a read or write operation on it would not block. This doesn’t mean the read or write operation will succeed, it only means the operation will return immediately.

If interest is set in both readability and writability, the two kinds of events might be delivered either separately or together.

For example, interest in Event { key: 7, readable: true, writable: true } might result in a single Event of the same form, or in two separate Events:

  • Event { key: 7, readable: true, writable: false }
  • Event { key: 7, readable: false, writable: true }

Note that interest in I/O events needs to be re-enabled using modify() again after an event is delivered if we’re interested in the next event of the same kind.

It is possible to register interest in the same file descriptor or socket using multiple separate Poller instances. When the event is delivered, one or more Pollers are notified with that event. The exact number of Pollers notified depends on the underlying platform. When registering multiple sources into one event, the user should be careful to accommodate for events lost to other pollers.

One may also register one source into other, non-polling event loops, like GLib’s context. While the plumbing will vary from platform to platform, in general the Poller will act as if the source was registered with another Poller, with the same caveats as above.

§Safety

The source must be delete()d from this Poller before it is dropped.

§Errors

This method returns an error in the following situations:

  • If key equals usize::MAX because that key is reserved for internal use.
  • If an error is returned by the syscall.
§Examples

Set interest in all events:

use polling::{Event, Poller};

let source = std::net::TcpListener::bind("127.0.0.1:0")?;
source.set_nonblocking(true)?;
let key = 7;

let poller = Poller::new()?;
unsafe {
    poller.add(&source, Event::all(key))?;
}
poller.delete(&source)?;
source

pub unsafe fn add_with_mode( &self, source: impl AsRawSource, interest: Event, mode: PollMode, ) -> Result<()>

Adds a file descriptor or socket to the poller in the specified mode.

This is identical to the add() function, but allows specifying the polling mode to use for this socket.

§Safety

The source must be delete()d from this Poller before it is dropped.

§Errors

If the operating system does not support the specified mode, this function will return an error.

source

pub fn modify(&self, source: impl AsSource, interest: Event) -> Result<()>

Modifies the interest in a file descriptor or socket.

This method has the same behavior as add() except it modifies the interest of a previously added file descriptor or socket.

To use this method with a file descriptor or socket, you must first add it using add().

Note that interest in I/O events needs to be re-enabled using modify() again after an event is delivered if we’re interested in the next event of the same kind.

§Errors

This method returns an error in the following situations:

  • If key equals usize::MAX because that key is reserved for internal use.
  • If an error is returned by the syscall.
§Examples

To enable interest in all events:

poller.modify(&source, Event::all(key))?;

To enable interest in readable events and disable interest in writable events:

poller.modify(&source, Event::readable(key))?;

To disable interest in readable events and enable interest in writable events:

poller.modify(&source, Event::writable(key))?;

To disable interest in all events:

poller.modify(&source, Event::none(key))?;
source

pub fn modify_with_mode( &self, source: impl AsSource, interest: Event, mode: PollMode, ) -> Result<()>

Modifies interest in a file descriptor or socket to the poller, but with the specified mode.

This is identical to the modify() function, but allows specifying the polling mode to use for this socket.

§Performance Notes

This function can be used to change a source from one polling mode to another. However, on some platforms, this switch can cause delays in the delivery of events.

§Errors

If the operating system does not support the specified mode, this function will return an error.

source

pub fn delete(&self, source: impl AsSource) -> Result<()>

Removes a file descriptor or socket from the poller.

Unlike add(), this method only removes the file descriptor or socket from the poller without putting it back into blocking mode.

§Examples
use polling::{Event, Poller};
use std::net::TcpListener;

let socket = TcpListener::bind("127.0.0.1:0")?;
socket.set_nonblocking(true)?;
let key = 7;

let poller = Poller::new()?;
unsafe { poller.add(&socket, Event::all(key))?; }
poller.delete(&socket)?;
source

pub fn wait( &self, events: &mut Events, timeout: Option<Duration>, ) -> Result<usize>

Waits for at least one I/O event and returns the number of new events.

New events will be appended to events. If necessary, make sure to clear the Events before calling wait()!

This method will return with no new events if a notification is delivered by the notify() method, or the timeout is reached. Sometimes it may even return with no events spuriously.

Only one thread can wait on I/O. If another thread is already in wait(), concurrent calls to this method will return immediately with no new events.

If the operating system is ready to deliver a large number of events at once, this method may decide to deliver them in smaller batches.

§Examples
use polling::{Event, Events, Poller};
use std::net::TcpListener;
use std::time::Duration;

let socket = TcpListener::bind("127.0.0.1:0")?;
socket.set_nonblocking(true)?;
let key = 7;

let poller = Poller::new()?;
unsafe {
    poller.add(&socket, Event::all(key))?;
}

let mut events = Events::new();
let n = poller.wait(&mut events, Some(Duration::from_secs(1)))?;
poller.delete(&socket)?;
source

pub fn notify(&self) -> Result<()>

Wakes up the current or the following invocation of wait().

If no thread is calling wait() right now, this method will cause the following call to wake up immediately.

§Examples
use polling::{Events, Poller};

let poller = Poller::new()?;

// Notify the poller.
poller.notify()?;

let mut events = Events::new();
poller.wait(&mut events, None)?; // wakes up immediately
assert!(events.is_empty());

Trait Implementations§

source§

impl AsFd for Poller

source§

fn as_fd(&self) -> BorrowedFd<'_>

Borrows the file descriptor. Read more
source§

impl AsRawFd for Poller

source§

fn as_raw_fd(&self) -> RawFd

Extracts the raw file descriptor. Read more
source§

impl Debug for Poller

source§

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more

Auto Trait Implementations§

§

impl !Freeze for Poller

§

impl RefUnwindSafe for Poller

§

impl Send for Poller

§

impl Sync for Poller

§

impl Unpin for Poller

§

impl UnwindSafe for Poller

Blanket Implementations§

source§

impl<T> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> AsSource for T
where T: AsFd,

source§

fn source(&self) -> BorrowedFd<'_>

Returns the borrowed file descriptor.
source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T> Instrument for T

source§

fn instrument(self, span: Span) -> Instrumented<Self>

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more
source§

fn in_current_span(self) -> Instrumented<Self>

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
source§

impl<T, U> Into<U> for T
where U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
source§

impl<T> WithSubscriber for T

source§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self>
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more
source§

fn with_current_subscriber(self) -> WithDispatch<Self>

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more