The last part of the code in this file is the Event struct:
ch04/a-epoll/src/ffi.rs
#[derive(Debug)]
#[repr(C, packed)]
pub struct Event {
pub(crate) events: u32,
// Token to identify event
pub(crate) epoll_data: usize,
}
impl Event {
pub fn token(&self) -> usize {
self.epoll_data
}
}
This structure is used to communicate to the operating system in epoll_ctl, and the operating system uses the same structure to communicate with us in epoll_wait.
Events are defined as a u32, but it’s more than just a number. This field is what we call a bitmask. I’ll take the time to explain bitmasks in a later section since it’s common in most syscalls and not something everyone has encountered before. In simple terms, it’s a way to use the bit representation as a set of yes/no flags to indicate whether an option has been chosen or not.
The different options are described in the link I provided for the epoll_ctl syscall. I won’t explain all of them in detail here, but just cover the ones we’ll use:
- EPOLLIN represents a bitflag indicating we’re interested in read operations on the file handle
- EPOLLET represents a bitflag indicating that we’re interested in getting events notified with epoll set to an edge-triggered mode
We’ll get back to explaining bitflags, bitmasks, and what edge-triggered mode really means in a moment, but let’s just finish with the code first.
The last field on the Event struct is epoll_data. This field is defined as a union in the documentation. A union is much like an enum, but in contrast to Rust’s enums, it doesn’t carry any information on what type it is, so it’s up to us to make sure we know what type of data it holds.
We use this field to simply hold a usize so we can pass in an integer identifying each event when we register interest using epoll_ctl. It would be perfectly fine to pass in a pointer instead – just as long as we make sure that the pointer is still valid when it’s returned to us in epoll_wait.
We can think of this field as a token, which is exactly what mio does, and to keep the API as similar as possible, we copy mio and provide a token method on the struct to get this value.
Leave a Reply