Struct Epoll 

pub struct Epoll { /* private fields */ }

Rust abstraction atop linux’s epoll interface. Wrapper type around an epoll file descriptor. Performs proper cleanup on drop.

use std::{time::Duration, fs::File};
use std::os::unix::io::AsRawFd;
use epoll_rs::{Epoll, Opts, EpollEvent};

let mut epoll = Epoll::new()?;
let file = File::open("/")?;
let token = epoll.add(file, Opts::IN)?;
// add other files...
let mut buf = [EpollEvent::zeroed(); 10];
let events = epoll.wait_timeout(&mut buf, Duration::from_millis(50))?;
for event in events {
    if token.fd() == event.fd() {
        println!("File ready for reading");
    } else {
        println!("File not ready for reading");
    }
}
epoll.remove(token); // this cleanup is performed when epoll goes out of scope

Implementations

impl Epoll

pub fn new() -> Result<Self>

pub fn add<'a, 'b: 'a, F: OwnedRawFd>( &'b self, file: F, opts: Opts, ) -> Result<Token<'a, F>>

Add a file-like struct to the epoll instance

The returned token can be ignored if you don’t need to distinguish which file is ready, but dropping the token closes the added file

pub fn remove<'a, 'b: 'a, F: OwnedRawFd>( &'b self, token: Token<'a, F>, ) -> Result<F>

Remove a previously added file-like struct from this epoll instance

No new events will be deilvered referring to this token even if the event occurs before removal. Consumes the token, returning the contained file, since the file it is associated with is no longer in this epoll instance

pub fn modify<'a, 'b: 'a, F: OwnedRawFd>( &'b self, token: &'a Token<'a, F>, opts: Opts, ) -> Result<()>

Change the Opts of a previously added file-like struct

pub fn wait<'a, 'b>( &'a self, buf: &'b mut [EpollEvent], ) -> Result<&'b mut [EpollEvent]>

Wait indefinetly until at least one event and at most buf.len() events occur.

If passed a zero length buf, this function will return Err

pub fn wait_timeout<'a, 'b>( &'a self, buf: &'b mut [EpollEvent], timeout: Duration, ) -> Result<&'b mut [EpollEvent]>

Wait until at least one event and at most buf.len() events occur or timeout expires.

If passed a zero length buf, this function will return Err

pub fn wait_one(&self) -> Result<EpollEvent>

Wait indefinetly for one event.

pub fn wait_one_timeout(&self, timeout: Duration) -> Result<Option<EpollEvent>>

Wait for one event or until timeout expires.

Return value of Ok(None) indicates timeout expired

pub fn close(&mut self) -> Result<()>

Manually close this epoll instance, handling any potential errors

Same as drop, only this lets the user deal with errors in closing. The invariants of this library should mean that close never fails, but those invariants can be broken with unsafe code.

pub unsafe fn add_raw_fd<'a, 'b: 'a, F: OwnedRawFd>( &'b self, fd: RawFd, opts: Opts, ) -> Result<Token<'a, F>>

Adds a RawFd to an epoll instance directly

This is pretty unsafe, prefer add

Safety

fd must refer to a currently open, unowned, file descriptor of type F. If fd refers to a file that is dropped or the fd is closed before this Epoll instance is, later use of the returned Token may modify a different file, since file descriptors (RawFds) are reused. The following is notably io unsound

use epoll_rs::{Epoll, Opts, Token};
use std::{fs::File, io, os::unix::io::{FromRawFd, AsRawFd}};
let mut epoll = Epoll::new()?;
{
    let stdin = unsafe{File::from_raw_fd(1)};
    let token: Token<File> = unsafe {
        epoll.add_raw_fd(stdin.as_raw_fd(), Opts::IN)?
    };
} // stdin dropped here, fd 1 `libc::close`d, invariants violated

instead use into_raw_fd to get an unowned RawFd

use epoll_rs::{Epoll, Opts, Token};
use std::{fs::File, io, os::unix::io::{FromRawFd, AsRawFd, IntoRawFd}};
let mut epoll = Epoll::new()?;
{
    let stdin = unsafe{File::from_raw_fd(1)};
    let token: Token<File> = unsafe {
        epoll.add_raw_fd(stdin.into_raw_fd(), Opts::IN)?
    };
} // stdin was consumed by into_raw_fd(), so it's drop code won't be run

Trait Implementations

impl AsRawFd for Epoll

fn as_raw_fd(&self) -> RawFd

Extracts the raw file descriptor.

impl Debug for Epoll

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

Formats the value using the given formatter.

impl Drop for Epoll

fn drop(&mut self)

Executes the destructor for this type.

impl FromRawFd for Epoll

unsafe fn from_raw_fd(fd: RawFd) -> Self

Safety: super unsafe. Use only if fd came from this library. Otherwise, you need to make sure all fds added to this epoll have epoll_data that contains their own fd, that all added fds are open and that fd is open and refers to an epoll file description.

impl IntoRawFd for Epoll

fn into_raw_fd(self) -> RawFd

Consumes this object, returning the raw underlying file descriptor.

impl OwnedRawFd for Epoll