Struct EpollContext

pub struct EpollContext<T> { /* private fields */ }

A wrapper of linux epoll.

It provides similar interface to PollContext. It is thread safe while PollContext is not. It requires user to pass in a reference of EpollEvents while PollContext does not. Always use PollContext if you don’t need to access the same epoll from different threads.

Examples

extern crate vmm_sys_util;
use vmm_sys_util::eventfd::EventFd;
use vmm_sys_util::poll::{EpollContext, EpollEvents};

let evt = EventFd::new(0).unwrap();
let ctx: EpollContext<u32> = EpollContext::new().unwrap();
let events = EpollEvents::new();

evt.write(1).unwrap();
ctx.add(&evt, 1).unwrap();

for event in ctx.wait(&events).unwrap().iter_readable() {
    assert_eq!(event.token(), 1);
}

Implementations

impl<T: PollToken> EpollContext<T>

pub fn new() -> Result<EpollContext<T>>

Creates a new EpollContext.

Uses epoll_create1 to create a new epoll fd.

Examples

extern crate vmm_sys_util;
use vmm_sys_util::poll::EpollContext;

let ctx: EpollContext<usize> = EpollContext::new().unwrap();

pub fn add(&self, fd: &dyn AsRawFd, token: T) -> Result<()>

Adds the given fd to this context and associates the given token with the fd’s readable events.

A fd can only be added once and does not need to be kept open. If the fd is dropped and there were no duplicated file descriptors (i.e. adding the same descriptor with a different FD number) added to this context, events will not be reported by wait anymore.

Arguments

• fd: the target file descriptor to be added.
• token: a PollToken implementation, used to be as u64 of libc::epoll_event structure.

Examples

extern crate vmm_sys_util;
use vmm_sys_util::eventfd::EventFd;
use vmm_sys_util::poll::EpollContext;

let evt = EventFd::new(0).unwrap();
let ctx: EpollContext<u32> = EpollContext::new().unwrap();
ctx.add(&evt, 1).unwrap();

pub fn add_fd_with_events( &self, fd: &dyn AsRawFd, events: WatchingEvents, token: T, ) -> Result<()>

Adds the given fd to this context, watching for the specified events and associates the given ‘token’ with those events.

A fd can only be added once and does not need to be kept open. If the fd is dropped and there were no duplicated file descriptors (i.e. adding the same descriptor with a different FD number) added to this context, events will not be reported by wait anymore.

Arguments

• fd: the target file descriptor to be added.
• events: specifies the events to be watched.
• token: a PollToken implementation, used to be as u64 of libc::epoll_event structure.

Examples

extern crate vmm_sys_util;
use vmm_sys_util::eventfd::EventFd;
use vmm_sys_util::poll::{EpollContext, WatchingEvents};

let evt = EventFd::new(0).unwrap();
let ctx: EpollContext<u32> = EpollContext::new().unwrap();
ctx.add_fd_with_events(&evt, WatchingEvents::empty().set_read(), 1)
    .unwrap();

pub fn modify( &self, fd: &dyn AsRawFd, events: WatchingEvents, token: T, ) -> Result<()>

Changes the setting associated with the given fd in this context.

If fd was previously added to this context, the watched events will be replaced with events and the token associated with it will be replaced with the given token.

Arguments

• fd: the target file descriptor to be performed.
• events: specifies the events to be watched.
• token: a PollToken implementation, used to be as u64 of libc::epoll_event structure.

Examples

extern crate vmm_sys_util;
use vmm_sys_util::eventfd::EventFd;
use vmm_sys_util::poll::{EpollContext, WatchingEvents};

let evt = EventFd::new(0).unwrap();
let ctx: EpollContext<u32> = EpollContext::new().unwrap();
ctx.add_fd_with_events(&evt, WatchingEvents::empty().set_read(), 1)
    .unwrap();
ctx.modify(&evt, WatchingEvents::empty().set_write(), 2)
    .unwrap();

pub fn delete(&self, fd: &dyn AsRawFd) -> Result<()>

Deletes the given fd from this context.

If an fd’s token shows up in the list of hangup events, it should be removed using this method or by closing/dropping (if and only if the fd was never dup()’d/fork()’d) the fd. Failure to do so will cause the wait method to always return immediately, causing ~100% CPU load.

Arguments

• fd: the target file descriptor to be removed.

Examples

extern crate vmm_sys_util;
use vmm_sys_util::eventfd::EventFd;
use vmm_sys_util::poll::EpollContext;

let evt = EventFd::new(0).unwrap();
let ctx: EpollContext<u32> = EpollContext::new().unwrap();
ctx.add(&evt, 1).unwrap();
ctx.delete(&evt).unwrap();

pub fn wait<'a>(&self, events: &'a EpollEvents) -> Result<PollEvents<'a, T>>

Waits for any events to occur in FDs that were previously added to this context.

The events are level-triggered, meaning that if any events are unhandled (i.e. not reading for readable events and not closing for hungup events), subsequent calls to wait will return immediately. The consequence of not handling an event perpetually while calling wait is that the callers loop will degenerated to busy loop polling, pinning a CPU to ~100% usage.

Arguments

• events: the events to wait for.

Examples

extern crate vmm_sys_util;
use vmm_sys_util::eventfd::EventFd;
use vmm_sys_util::poll::{EpollContext, EpollEvents};

let evt = EventFd::new(0).unwrap();
let ctx: EpollContext<u32> = EpollContext::new().unwrap();
let events = EpollEvents::new();

evt.write(1).unwrap();
ctx.add(&evt, 1).unwrap();

for event in ctx.wait(&events).unwrap().iter_readable() {
    assert_eq!(event.token(), 1);
}

pub fn wait_timeout<'a>( &self, events: &'a EpollEvents, timeout: Duration, ) -> Result<PollEvents<'a, T>>

Like wait except will only block for a maximum of the given timeout.

This may return earlier than timeout with zero events if the duration indicated exceeds system limits.

Arguments

• events: the events to wait for.
• timeout: specifies the timeout that will block.

Examples

extern crate vmm_sys_util;
use vmm_sys_util::eventfd::EventFd;
use vmm_sys_util::poll::{EpollContext, EpollEvents};

let evt = EventFd::new(0).unwrap();
let ctx: EpollContext<u32> = EpollContext::new().unwrap();
let events = EpollEvents::new();

evt.write(1).unwrap();
ctx.add(&evt, 1).unwrap();
for event in ctx
    .wait_timeout(&events, Duration::new(100, 0))
    .unwrap()
    .iter_readable()
{
    assert_eq!(event.token(), 1);
}

Trait Implementations

impl<T: PollToken> AsRawFd for EpollContext<T>

fn as_raw_fd(&self) -> RawFd

Extracts the raw file descriptor.

impl<T: Debug> Debug for EpollContext<T>

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

Formats the value using the given formatter.

impl<T: PollToken> IntoRawFd for EpollContext<T>

fn into_raw_fd(self) -> RawFd

Consumes this object, returning the raw underlying file descriptor.