# Module rustix::io::epoll

source · [−]
Expand description

epoll support.

This is an experiment, and it isn’t yet clear whether epoll is the right level of abstraction at which to introduce safety. But it works fairly well in simple examples 🙂.

## Examples

    use io_lifetimes::AsFd;
    use rustix::io::epoll::{self, Epoll};
    use rustix::io::{ioctl_fionbio, read, write};
    use rustix::net::{
        accept, bind_v4, listen, socket, AddressFamily, Ipv4Addr, Protocol, SocketAddrV4,
        SocketType,
    };
    use std::os::unix::io::AsRawFd;

    // Create a socket and listen on it.
    let listen_sock = socket(AddressFamily::INET, SocketType::STREAM, Protocol::default())?;
    bind_v4(&listen_sock, &SocketAddrV4::new(Ipv4Addr::LOCALHOST, 0))?;
    listen(&listen_sock, 1)?;

    // Create an epoll object. Using `Owning` here means the epoll object will
    // take ownership of the file descriptors registered with it.
    let epoll = Epoll::new(epoll::CreateFlags::CLOEXEC, epoll::Owning::new())?;

    // Remember the socket raw fd, which we use for comparisons only.
    let raw_listen_sock = listen_sock.as_fd().as_raw_fd();

    // Register the socket with the epoll object.
    epoll.add(listen_sock, epoll::EventFlags::IN)?;

    // Process events.
    let mut event_list = epoll::EventVec::with_capacity(4);
    loop {
        epoll.wait(&mut event_list, -1)?;
        for (_event_flags, target) in &event_list {
            if target.as_raw_fd() == raw_listen_sock {
                // Accept a new connection, set it to non-blocking, and
                // register to be notified when it's ready to write to.
                let conn_sock = accept(&*target)?;
                ioctl_fionbio(&conn_sock, true)?;
                epoll.add(conn_sock, epoll::EventFlags::OUT | epoll::EventFlags::ET)?;
            } else {
                // Write a message to the stream and then unregister it.
                write(&*target, b"hello\n")?;
                let _ = epoll.del(target)?;
            }
        }
    }

## Structs

Borrowing

A type implementing `Context` where the `Data` type is `BorrowedFd<'a>`.

CreateFlags

`EPOLL_*` for use with `Epoll::new`.

Epoll

An “epoll”, an interface to an OS object allowing one to repeatedly wait for events from a set of file descriptors efficiently.

EventFlags

`EPOLL*` for use with `Epoll::add`.

EventVec

A vector of `Event`s, plus context for interpreting them.

Iter

An iterator over the `Event`s in an `EventVec`.

Owning

A type implementing `Context` where the `Data` type is `T`, a type implementing `From<OwnedFd>` and `From<T> for OwnedFd`.

Ref

A reference to a `T`.

## Traits

Context

A trait for data stored within an `Epoll` instance.