Struct userfaultfd::Uffd

pub struct Uffd { /* fields omitted */ }

The userfaultfd object.

The userspace representation of the object is a file descriptor, so this type implements AsRawFd, FromRawFd, and IntoRawFd. These methods should be used with caution, but can be essential for using functions like poll on a worker thread.

Implementations

impl Uffd

pub fn register(&self, start: *mut c_void, len: usize) -> Result<IoctlFlags>

Register a memory address range with the userfaultfd object, and returns the IoctlFlags that are available for the selected range.

While the underlying ioctl call accepts mode flags, only one mode (UFFDIO_REGISTER_MODE_MISSING) is currently supported.

pub fn unregister(&self, start: *mut c_void, len: usize) -> Result<()>

Unregister a memory address range from the userfaultfd object.

pub unsafe fn copy(
    &self,
    src: *const c_void,
    dst: *mut c_void,
    len: usize,
    wake: bool
) -> Result<usize>

Atomically copy a continuous memory chunk into the userfaultfd-registed range, and return the number of bytes that were successfully copied.

If wake is true, wake up the thread waiting for pagefault resolution on the memory range.

pub unsafe fn zeropage(
    &self,
    start: *mut c_void,
    len: usize,
    wake: bool
) -> Result<usize>

Zero out a memory address range registered with userfaultfd, and return the number of bytes that were successfully zeroed.

If wake is true, wake up the thread waiting for pagefault resolution on the memory address range.

pub fn wake(&self, start: *mut c_void, len: usize) -> Result<()>

Wake up the thread waiting for pagefault resolution on the specified memory address range.

pub fn read_event(&self) -> Result<Option<Event>>

Read an Event from the userfaultfd object.

If the Uffd object was created with non_blocking set to false, this will block until an event is successfully read (returning Some(event), or an error is returned.

If non_blocking was true, this will immediately return None if no event is ready to read.

Note that while this method doesn’t require a mutable reference to the Uffd object, it does consume bytes (thread-safely) from the underlying file descriptor.

Examples

fn read_event(uffd: &Uffd) -> Result<()> {
    // Read a single event
    match uffd.read_event()? {
        Some(e) => {
            // Do something with the event
        },
        None => {
            // This was a non-blocking read and the descriptor was not ready for read
        },
    }
    Ok(())
}

pub fn read_events<'a>(
    &self,
    buf: &'a mut EventBuffer
) -> Result<impl Iterator<Item = Result<Event>> + 'a>

Read multiple events from the userfaultfd object using the given event buffer.

If the Uffd object was created with non_blocking set to false, this will block until an event is successfully read or an error is returned.

If non_blocking was true, this will immediately return an empty iterator if the file descriptor is not ready for reading.

Examples

fn read_events(uffd: &Uffd) -> userfaultfd::Result<()> {
    // Read up to 100 events at a time
    let mut buf = EventBuffer::new(100);
    for event in uffd.read_events(&mut buf)? {
        let event = event?;
        // Do something with the event...
    }
    Ok(())
}

Trait Implementations

impl AsRawFd for Uffd

fn as_raw_fd(&self) -> RawFd

Extracts the raw file descriptor.

impl Debug for Uffd

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

Formats the value using the given formatter.

impl Drop for Uffd

fn drop(&mut self)

Executes the destructor for this type.

impl FromRawFd for Uffd

unsafe fn from_raw_fd(fd: RawFd) -> Self

Constructs a new instance of Self from the given raw file descriptor.

impl IntoRawFd for Uffd

fn into_raw_fd(self) -> RawFd

Consumes this object, returning the raw underlying file descriptor.