src/linux/epoll.rs - platform/external/rust/crates/vmm-sys-util - Git at Google

 // Copyright 2020 Amazon.com, Inc. or its affiliates. All Rights Reserved.
 // SPDX-License-Identifier: BSD-3-Clause

 //! Safe wrappers over the
 //! [`epoll`](http://man7.org/linux/man-pages/man7/epoll.7.html) API.

 use std::io;
 use std::ops::{Deref, Drop};
 use std::os::unix::io::{AsRawFd, RawFd};

 #[cfg(any(target_os = "linux", target_os = "android"))]
 use bitflags::bitflags;
 use libc::{
     epoll_create1, epoll_ctl, epoll_event, epoll_wait, EPOLLERR, EPOLLET, EPOLLEXCLUSIVE, EPOLLHUP,
     EPOLLIN, EPOLLONESHOT, EPOLLOUT, EPOLLPRI, EPOLLRDHUP, EPOLLWAKEUP, EPOLL_CLOEXEC,
     EPOLL_CTL_ADD, EPOLL_CTL_DEL, EPOLL_CTL_MOD,
 };

 use crate::syscall::SyscallReturnCode;

 /// Wrapper over `EPOLL_CTL_*` operations that can be performed on a file descriptor.
 #[repr(i32)]
 pub enum ControlOperation {
     /// Add a file descriptor to the interest list.
     Add = EPOLL_CTL_ADD,
     /// Change the settings associated with a file descriptor that is
     /// already in the interest list.
     Modify = EPOLL_CTL_MOD,
     /// Remove a file descriptor from the interest list.
     Delete = EPOLL_CTL_DEL,
 }

 bitflags! {
     /// The type of events we can monitor a file descriptor for.
     pub struct EventSet: u32 {
         /// The associated file descriptor is available for read operations.
         const IN = EPOLLIN as u32;
         /// The associated file descriptor is available for write operations.
         const OUT = EPOLLOUT as u32;
         /// Error condition happened on the associated file descriptor.
         const ERROR = EPOLLERR as u32;
         /// This can be used to detect peer shutdown when using Edge Triggered monitoring.
         const READ_HANG_UP = EPOLLRDHUP as u32;
         /// Sets the Edge Triggered behavior for the associated file descriptor.
         /// The default behavior is Level Triggered.
         const EDGE_TRIGGERED = EPOLLET as u32;
         /// Hang up happened on the associated file descriptor. Note that `epoll_wait`
         /// will always wait for this event and it is not necessary to set it in events.
         const HANG_UP = EPOLLHUP as u32;
         /// There is an exceptional condition on that file descriptor. It is mostly used to
         /// set high priority for some data.
         const PRIORITY = EPOLLPRI as u32;
         /// The event is considered as being "processed" from the time when it is returned
         /// by a call to `epoll_wait` until the next call to `epoll_wait` on the same
         /// epoll file descriptor, the closure of that file descriptor, the removal of the
         /// event file descriptor via EPOLL_CTL_DEL, or the clearing of EPOLLWAKEUP
         /// for the event file descriptor via EPOLL_CTL_MOD.
         const WAKE_UP = EPOLLWAKEUP as u32;
         /// Sets the one-shot behavior for the associated file descriptor.
         const ONE_SHOT = EPOLLONESHOT as u32;
         /// Sets an exclusive wake up mode for the epoll file descriptor that is being
         /// attached to the associated file descriptor.
         /// When a wake up event occurs and multiple epoll file descriptors are attached to
         /// the same target file using this mode, one or more of the epoll file descriptors
         /// will receive an event with `epoll_wait`. The default here is for all those file
         /// descriptors to receive an event.
         const EXCLUSIVE = EPOLLEXCLUSIVE as u32;
     }
 }

 /// Wrapper over
 /// ['libc::epoll_event'](https://doc.rust-lang.org/1.8.0/libc/struct.epoll_event.html).
 // We are using `transparent` here to be super sure that this struct and its fields
 // have the same alignment as those from the `epoll_event` struct from C.
 #[repr(transparent)]
 #[derive(Clone, Copy)]
 pub struct EpollEvent(epoll_event);

 impl std::fmt::Debug for EpollEvent {
     fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
         write!(f, "{{ events: {}, data: {} }}", self.events(), self.data())
     }
 }

 impl Deref for EpollEvent {
     type Target = epoll_event;
     fn deref(&self) -> &Self::Target {
         &self.0
     }
 }

 impl Default for EpollEvent {
     fn default() -> Self {
         EpollEvent(epoll_event {
             events: 0u32,
             u64: 0u64,
         })
     }
 }

 impl EpollEvent {
     /// Create a new epoll_event instance.
     ///
     /// # Arguments
     ///
     /// `events` - contains an event mask.
     /// `data` - a user data variable. `data` field can be a fd on which
     ///          we want to monitor the events specified by `events`.
     ///
     /// # Examples
     ///
     /// ```
     /// extern crate vmm_sys_util;
     /// use vmm_sys_util::epoll::{EpollEvent, EventSet};
     ///
     /// let event = EpollEvent::new(EventSet::IN, 2);
     /// ```
     pub fn new(events: EventSet, data: u64) -> Self {
         EpollEvent(epoll_event {
             events: events.bits(),
             u64: data,
         })
     }

     /// Returns the `events` from
     /// ['libc::epoll_event'](https://doc.rust-lang.org/1.8.0/libc/struct.epoll_event.html).
     ///
     /// # Examples
     ///
     /// ```
     /// extern crate vmm_sys_util;
     /// use vmm_sys_util::epoll::{EpollEvent, EventSet};
     ///
     /// let event = EpollEvent::new(EventSet::IN, 2);
     /// assert_eq!(event.events(), 1);
     /// ```
     pub fn events(&self) -> u32 {
         self.events
     }

     /// Returns the `EventSet` corresponding to `epoll_event.events`.
     ///
     /// # Panics
     ///
     /// Panics if `libc::epoll_event` contains invalid events.
     ///
     ///
     /// # Examples
     ///
     /// ```
     /// extern crate vmm_sys_util;
     /// use vmm_sys_util::epoll::{EpollEvent, EventSet};
     ///
     /// let event = EpollEvent::new(EventSet::IN, 2);
     /// assert_eq!(event.event_set(), EventSet::IN);
     /// ```
     pub fn event_set(&self) -> EventSet {
         // This unwrap is safe because `epoll_events` can only be user created or
         // initialized by the kernel. We trust the kernel to only send us valid
         // events. The user can only initialize `epoll_events` using valid events.
         EventSet::from_bits(self.events()).unwrap()
     }

     /// Returns the `data` from the `libc::epoll_event`.
     ///
     /// # Examples
     ///
     /// ```
     /// extern crate vmm_sys_util;
     /// use vmm_sys_util::epoll::{EpollEvent, EventSet};
     ///
     /// let event = EpollEvent::new(EventSet::IN, 2);
     /// assert_eq!(event.data(), 2);
     /// ```
     pub fn data(&self) -> u64 {
         self.u64
     }

     /// Converts the `libc::epoll_event` data to a RawFd.
     ///
     /// This conversion is lossy when the data does not correspond to a RawFd
     /// (data does not fit in a i32).
     ///
     /// # Examples
     ///
     /// ```
     /// extern crate vmm_sys_util;
     /// use vmm_sys_util::epoll::{EpollEvent, EventSet};
     ///
     /// let event = EpollEvent::new(EventSet::IN, 2);
     /// assert_eq!(event.fd(), 2);
     /// ```
     pub fn fd(&self) -> RawFd {
         self.u64 as i32
     }
 }

 /// Wrapper over epoll functionality.
 #[derive(Debug)]
 pub struct Epoll {
     epoll_fd: RawFd,
 }

 impl Epoll {
     /// Create a new epoll file descriptor.
     pub fn new() -> io::Result<Self> {
         let epoll_fd = SyscallReturnCode(
             // SAFETY: Safe because the return code is transformed by `into_result` in a `Result`.
             unsafe { epoll_create1(EPOLL_CLOEXEC) },
         )
         .into_result()?;
         Ok(Epoll { epoll_fd })
     }

     /// Wrapper for `libc::epoll_ctl`.
     ///
     /// This can be used for adding, modifying or removing a file descriptor in the
     /// interest list of the epoll instance.
     ///
     /// # Arguments
     ///
     /// * `operation` - refers to the action to be performed on the file descriptor.
     /// * `fd` - the file descriptor on which we want to perform `operation`.
     /// * `event` - refers to the `epoll_event` instance that is linked to `fd`.
     ///
     /// # Examples
     ///
     /// ```
     /// extern crate vmm_sys_util;
     ///
     /// use std::os::unix::io::AsRawFd;
     /// use vmm_sys_util::epoll::{ControlOperation, Epoll, EpollEvent, EventSet};
     /// use vmm_sys_util::eventfd::EventFd;
     ///
     /// let epoll = Epoll::new().unwrap();
     /// let event_fd = EventFd::new(libc::EFD_NONBLOCK).unwrap();
     /// epoll
     ///     .ctl(
     ///         ControlOperation::Add,
     ///         event_fd.as_raw_fd() as i32,
     ///         EpollEvent::new(EventSet::OUT, event_fd.as_raw_fd() as u64),
     ///     )
     ///     .unwrap();
     /// epoll
     ///     .ctl(
     ///         ControlOperation::Modify,
     ///         event_fd.as_raw_fd() as i32,
     ///         EpollEvent::new(EventSet::IN, 4),
     ///     )
     ///     .unwrap();
     /// ```
     pub fn ctl(&self, operation: ControlOperation, fd: RawFd, event: EpollEvent) -> io::Result<()> {
         SyscallReturnCode(
             // SAFETY: Safe because we give a valid epoll file descriptor, a valid file descriptor
             // to watch, as well as a valid epoll_event structure. We also check the return value.
             unsafe {
                 epoll_ctl(
                     self.epoll_fd,
                     operation as i32,
                     fd,
                     &event as *const EpollEvent as *mut epoll_event,
                 )
             },
         )
         .into_empty_result()
     }

     /// Wrapper for `libc::epoll_wait`.
     /// Returns the number of file descriptors in the interest list that became ready
     /// for I/O or `errno` if an error occurred.
     ///
     /// # Arguments
     ///
     /// * `timeout` - specifies for how long the `epoll_wait` system call will block
     ///               (measured in milliseconds).
     /// * `events` - points to a memory area that will be used for storing the events
     ///              returned by `epoll_wait()` call.
     ///
     /// # Examples
     ///
     /// ```
     /// extern crate vmm_sys_util;
     ///
     /// use std::os::unix::io::AsRawFd;
     /// use vmm_sys_util::epoll::{ControlOperation, Epoll, EpollEvent, EventSet};
     /// use vmm_sys_util::eventfd::EventFd;
     ///
     /// let epoll = Epoll::new().unwrap();
     /// let event_fd = EventFd::new(libc::EFD_NONBLOCK).unwrap();
     ///
     /// let mut ready_events = vec![EpollEvent::default(); 10];
     /// epoll
     ///     .ctl(
     ///         ControlOperation::Add,
     ///         event_fd.as_raw_fd() as i32,
     ///         EpollEvent::new(EventSet::OUT, 4),
     ///     )
     ///     .unwrap();
     /// let ev_count = epoll.wait(-1, &mut ready_events[..]).unwrap();
     /// assert_eq!(ev_count, 1);
     /// ```
     pub fn wait(&self, timeout: i32, events: &mut [EpollEvent]) -> io::Result<usize> {
         let events_count = SyscallReturnCode(
             // SAFETY: Safe because we give a valid epoll file descriptor and an array of
             // epoll_event structures that will be modified by the kernel to indicate information
             // about the subset of file descriptors in the interest list.
             // We also check the return value.
             unsafe {
                 epoll_wait(
                     self.epoll_fd,
                     events.as_mut_ptr() as *mut epoll_event,
                     events.len() as i32,
                     timeout,
                 )
             },
         )
         .into_result()? as usize;

         Ok(events_count)
     }
 }

 impl AsRawFd for Epoll {
     fn as_raw_fd(&self) -> RawFd {
         self.epoll_fd
     }
 }

 impl Drop for Epoll {
     fn drop(&mut self) {
         // SAFETY: Safe because this fd is opened with `epoll_create` and we trust
         // the kernel to give us a valid fd.
         unsafe {
             libc::close(self.epoll_fd);
         }
     }
 }

 #[cfg(test)]
 mod tests {
     use super::*;

     use crate::eventfd::EventFd;

     #[test]
     fn test_event_ops() {
         let mut event = EpollEvent::default();
         assert_eq!(event.events(), 0);
         assert_eq!(event.data(), 0);

         event = EpollEvent::new(EventSet::IN, 2);
         assert_eq!(event.events(), 1);
         assert_eq!(event.event_set(), EventSet::IN);

         assert_eq!(event.data(), 2);
         assert_eq!(event.fd(), 2);
     }

     #[test]
     fn test_events_debug() {
         let events = EpollEvent::new(EventSet::IN, 42);
         assert_eq!(format!("{:?}", events), "{ events: 1, data: 42 }")
     }

     #[test]
     fn test_epoll() {
         const DEFAULT__TIMEOUT: i32 = 250;
         const EVENT_BUFFER_SIZE: usize = 128;

         let epoll = Epoll::new().unwrap();
         assert_eq!(epoll.epoll_fd, epoll.as_raw_fd());

         // Let's test different scenarios for `epoll_ctl()` and `epoll_wait()` functionality.

         let event_fd_1 = EventFd::new(libc::EFD_NONBLOCK).unwrap();
         // For EPOLLOUT to be available it is enough only to be possible to write a value of
         // at least 1 to the eventfd counter without blocking.
         // If we write a value greater than 0 to this counter, the fd will be available for
         // EPOLLIN events too.
         event_fd_1.write(1).unwrap();

         let mut event_1 =
             EpollEvent::new(EventSet::IN | EventSet::OUT, event_fd_1.as_raw_fd() as u64);

         // For EPOLL_CTL_ADD behavior we will try to add some fds with different event masks into
         // the interest list of epoll instance.
         assert!(epoll
             .ctl(
                 ControlOperation::Add,
                 event_fd_1.as_raw_fd() as i32,
                 event_1
             )
             .is_ok());

         // We can't add twice the same fd to epoll interest list.
         assert!(epoll
             .ctl(
                 ControlOperation::Add,
                 event_fd_1.as_raw_fd() as i32,
                 event_1
             )
             .is_err());

         let event_fd_2 = EventFd::new(libc::EFD_NONBLOCK).unwrap();
         event_fd_2.write(1).unwrap();
         assert!(epoll
             .ctl(
                 ControlOperation::Add,
                 event_fd_2.as_raw_fd() as i32,
                 // For this fd, we want an Event instance that has `data` field set to other
                 // value than the value of the fd and `events` without EPOLLIN type set.
                 EpollEvent::new(EventSet::OUT, 10)
             )
             .is_ok());

         // For the following eventfd we won't write anything to its counter, so we expect EPOLLIN
         // event to not be available for this fd, even if we say that we want to monitor this type
         // of event via EPOLL_CTL_ADD operation.
         let event_fd_3 = EventFd::new(libc::EFD_NONBLOCK).unwrap();
         let event_3 = EpollEvent::new(EventSet::OUT | EventSet::IN, event_fd_3.as_raw_fd() as u64);
         assert!(epoll
             .ctl(
                 ControlOperation::Add,
                 event_fd_3.as_raw_fd() as i32,
                 event_3
             )
             .is_ok());

         // Let's check `epoll_wait()` behavior for our epoll instance.
         let mut ready_events = vec![EpollEvent::default(); EVENT_BUFFER_SIZE];
         let mut ev_count = epoll.wait(DEFAULT__TIMEOUT, &mut ready_events[..]).unwrap();

         // We expect to have 3 fds in the ready list of epoll instance.
         assert_eq!(ev_count, 3);

         // Let's check also the Event values that are now returned in the ready list.
         assert_eq!(ready_events[0].data(), event_fd_1.as_raw_fd() as u64);
         // For this fd, `data` field was populated with random data instead of the
         // corresponding fd value.
         assert_eq!(ready_events[1].data(), 10);
         assert_eq!(ready_events[2].data(), event_fd_3.as_raw_fd() as u64);

         // EPOLLIN and EPOLLOUT should be available for this fd.
         assert_eq!(
             ready_events[0].events(),
             (EventSet::IN | EventSet::OUT).bits()
         );
         // Only EPOLLOUT is expected because we didn't want to monitor EPOLLIN on this fd.
         assert_eq!(ready_events[1].events(), EventSet::OUT.bits());
         // Only EPOLLOUT too because eventfd counter value is 0 (we didn't write a value
         // greater than 0 to it).
         assert_eq!(ready_events[2].events(), EventSet::OUT.bits());

         // Now we're gonna modify the Event instance for a fd to test EPOLL_CTL_MOD
         // behavior.
         // We create here a new Event with some events, other than those previously set,
         // that we want to monitor this time on event_fd_1.
         event_1 = EpollEvent::new(EventSet::OUT, 20);
         assert!(epoll
             .ctl(
                 ControlOperation::Modify,
                 event_fd_1.as_raw_fd() as i32,
                 event_1
             )
             .is_ok());

         let event_fd_4 = EventFd::new(libc::EFD_NONBLOCK).unwrap();
         // Can't modify a fd that wasn't added to epoll interest list.
         assert!(epoll
             .ctl(
                 ControlOperation::Modify,
                 event_fd_4.as_raw_fd() as i32,
                 EpollEvent::default()
             )
             .is_err());

         let _ = epoll.wait(DEFAULT__TIMEOUT, &mut ready_events[..]).unwrap();

         // Let's check that Event fields were indeed changed for the `event_fd_1` fd.
         assert_eq!(ready_events[0].data(), 20);
         // EPOLLOUT is now available for this fd as we've intended with EPOLL_CTL_MOD operation.
         assert_eq!(ready_events[0].events(), EventSet::OUT.bits());

         // Now let's set for a fd to not have any events monitored.
         assert!(epoll
             .ctl(
                 ControlOperation::Modify,
                 event_fd_1.as_raw_fd() as i32,
                 EpollEvent::default()
             )
             .is_ok());

         // In this particular case we expect to remain only with 2 fds in the ready list.
         ev_count = epoll.wait(DEFAULT__TIMEOUT, &mut ready_events[..]).unwrap();
         assert_eq!(ev_count, 2);

         // Let's also delete a fd from the interest list.
         assert!(epoll
             .ctl(
                 ControlOperation::Delete,
                 event_fd_2.as_raw_fd() as i32,
                 EpollEvent::default()
             )
             .is_ok());

         // We expect to have only one fd remained in the ready list (event_fd_3).
         ev_count = epoll.wait(DEFAULT__TIMEOUT, &mut ready_events[..]).unwrap();

         assert_eq!(ev_count, 1);
         assert_eq!(ready_events[0].data(), event_fd_3.as_raw_fd() as u64);
         assert_eq!(ready_events[0].events(), EventSet::OUT.bits());

         // If we try to remove a fd from epoll interest list that wasn't added before it will fail.
         assert!(epoll
             .ctl(
                 ControlOperation::Delete,
                 event_fd_4.as_raw_fd() as i32,
                 EpollEvent::default()
             )
             .is_err());
     }
 }
	// Copyright 2020 Amazon.com, Inc. or its affiliates. All Rights Reserved.
	// SPDX-License-Identifier: BSD-3-Clause

	//! Safe wrappers over the
	//! [`epoll`](http://man7.org/linux/man-pages/man7/epoll.7.html) API.

	use std::io;
	use std::ops::{Deref, Drop};
	use std::os::unix::io::{AsRawFd, RawFd};

	#[cfg(any(target_os = "linux", target_os = "android"))]
	use bitflags::bitflags;
	use libc::{
	epoll_create1, epoll_ctl, epoll_event, epoll_wait, EPOLLERR, EPOLLET, EPOLLEXCLUSIVE, EPOLLHUP,
	EPOLLIN, EPOLLONESHOT, EPOLLOUT, EPOLLPRI, EPOLLRDHUP, EPOLLWAKEUP, EPOLL_CLOEXEC,
	EPOLL_CTL_ADD, EPOLL_CTL_DEL, EPOLL_CTL_MOD,
	};

	use crate::syscall::SyscallReturnCode;

	/// Wrapper over `EPOLL_CTL_*` operations that can be performed on a file descriptor.
	#[repr(i32)]
	pub enum ControlOperation {
	/// Add a file descriptor to the interest list.
	Add = EPOLL_CTL_ADD,
	/// Change the settings associated with a file descriptor that is
	/// already in the interest list.
	Modify = EPOLL_CTL_MOD,
	/// Remove a file descriptor from the interest list.
	Delete = EPOLL_CTL_DEL,
	}

	bitflags! {
	/// The type of events we can monitor a file descriptor for.
	pub struct EventSet: u32 {
	/// The associated file descriptor is available for read operations.
	const IN = EPOLLIN as u32;
	/// The associated file descriptor is available for write operations.
	const OUT = EPOLLOUT as u32;
	/// Error condition happened on the associated file descriptor.
	const ERROR = EPOLLERR as u32;
	/// This can be used to detect peer shutdown when using Edge Triggered monitoring.
	const READ_HANG_UP = EPOLLRDHUP as u32;
	/// Sets the Edge Triggered behavior for the associated file descriptor.
	/// The default behavior is Level Triggered.
	const EDGE_TRIGGERED = EPOLLET as u32;
	/// Hang up happened on the associated file descriptor. Note that `epoll_wait`
	/// will always wait for this event and it is not necessary to set it in events.
	const HANG_UP = EPOLLHUP as u32;
	/// There is an exceptional condition on that file descriptor. It is mostly used to
	/// set high priority for some data.
	const PRIORITY = EPOLLPRI as u32;
	/// The event is considered as being "processed" from the time when it is returned
	/// by a call to `epoll_wait` until the next call to `epoll_wait` on the same
	/// epoll file descriptor, the closure of that file descriptor, the removal of the
	/// event file descriptor via EPOLL_CTL_DEL, or the clearing of EPOLLWAKEUP
	/// for the event file descriptor via EPOLL_CTL_MOD.
	const WAKE_UP = EPOLLWAKEUP as u32;
	/// Sets the one-shot behavior for the associated file descriptor.
	const ONE_SHOT = EPOLLONESHOT as u32;
	/// Sets an exclusive wake up mode for the epoll file descriptor that is being
	/// attached to the associated file descriptor.
	/// When a wake up event occurs and multiple epoll file descriptors are attached to
	/// the same target file using this mode, one or more of the epoll file descriptors
	/// will receive an event with `epoll_wait`. The default here is for all those file
	/// descriptors to receive an event.
	const EXCLUSIVE = EPOLLEXCLUSIVE as u32;
	}
	}

	/// Wrapper over
	/// ['libc::epoll_event'](https://doc.rust-lang.org/1.8.0/libc/struct.epoll_event.html).
	// We are using `transparent` here to be super sure that this struct and its fields
	// have the same alignment as those from the `epoll_event` struct from C.
	#[repr(transparent)]
	#[derive(Clone, Copy)]
	pub struct EpollEvent(epoll_event);

	impl std::fmt::Debug for EpollEvent {
	fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
	write!(f, "{{ events: {}, data: {} }}", self.events(), self.data())
	}
	}

	impl Deref for EpollEvent {
	type Target = epoll_event;
	fn deref(&self) -> &Self::Target {
	&self.0
	}
	}

	impl Default for EpollEvent {
	fn default() -> Self {
	EpollEvent(epoll_event {
	events: 0u32,
	u64: 0u64,
	})
	}
	}

	impl EpollEvent {
	/// Create a new epoll_event instance.
	///
	/// # Arguments
	///
	/// `events` - contains an event mask.
	/// `data` - a user data variable. `data` field can be a fd on which
	/// we want to monitor the events specified by `events`.
	///
	/// # Examples
	///
	/// ```
	/// extern crate vmm_sys_util;
	/// use vmm_sys_util::epoll::{EpollEvent, EventSet};
	///
	/// let event = EpollEvent::new(EventSet::IN, 2);
	/// ```
	pub fn new(events: EventSet, data: u64) -> Self {
	EpollEvent(epoll_event {
	events: events.bits(),
	u64: data,
	})
	}

	/// Returns the `events` from
	/// ['libc::epoll_event'](https://doc.rust-lang.org/1.8.0/libc/struct.epoll_event.html).
	///
	/// # Examples
	///
	/// ```
	/// extern crate vmm_sys_util;
	/// use vmm_sys_util::epoll::{EpollEvent, EventSet};
	///
	/// let event = EpollEvent::new(EventSet::IN, 2);
	/// assert_eq!(event.events(), 1);
	/// ```
	pub fn events(&self) -> u32 {
	self.events
	}

	/// Returns the `EventSet` corresponding to `epoll_event.events`.
	///
	/// # Panics
	///
	/// Panics if `libc::epoll_event` contains invalid events.
	///
	///
	/// # Examples
	///
	/// ```
	/// extern crate vmm_sys_util;
	/// use vmm_sys_util::epoll::{EpollEvent, EventSet};
	///
	/// let event = EpollEvent::new(EventSet::IN, 2);
	/// assert_eq!(event.event_set(), EventSet::IN);
	/// ```
	pub fn event_set(&self) -> EventSet {
	// This unwrap is safe because `epoll_events` can only be user created or
	// initialized by the kernel. We trust the kernel to only send us valid
	// events. The user can only initialize `epoll_events` using valid events.
	EventSet::from_bits(self.events()).unwrap()
	}

	/// Returns the `data` from the `libc::epoll_event`.
	///
	/// # Examples
	///
	/// ```
	/// extern crate vmm_sys_util;
	/// use vmm_sys_util::epoll::{EpollEvent, EventSet};
	///
	/// let event = EpollEvent::new(EventSet::IN, 2);
	/// assert_eq!(event.data(), 2);
	/// ```
	pub fn data(&self) -> u64 {
	self.u64
	}

	/// Converts the `libc::epoll_event` data to a RawFd.
	///
	/// This conversion is lossy when the data does not correspond to a RawFd
	/// (data does not fit in a i32).
	///
	/// # Examples
	///
	/// ```
	/// extern crate vmm_sys_util;
	/// use vmm_sys_util::epoll::{EpollEvent, EventSet};
	///
	/// let event = EpollEvent::new(EventSet::IN, 2);
	/// assert_eq!(event.fd(), 2);
	/// ```
	pub fn fd(&self) -> RawFd {
	self.u64 as i32
	}
	}

	/// Wrapper over epoll functionality.
	#[derive(Debug)]
	pub struct Epoll {
	epoll_fd: RawFd,
	}

	impl Epoll {
	/// Create a new epoll file descriptor.
	pub fn new() -> io::Result<Self> {
	let epoll_fd = SyscallReturnCode(
	// SAFETY: Safe because the return code is transformed by `into_result` in a `Result`.
	unsafe { epoll_create1(EPOLL_CLOEXEC) },
	)
	.into_result()?;
	Ok(Epoll { epoll_fd })
	}

	/// Wrapper for `libc::epoll_ctl`.
	///
	/// This can be used for adding, modifying or removing a file descriptor in the
	/// interest list of the epoll instance.
	///
	/// # Arguments
	///
	/// * `operation` - refers to the action to be performed on the file descriptor.
	/// * `fd` - the file descriptor on which we want to perform `operation`.
	/// * `event` - refers to the `epoll_event` instance that is linked to `fd`.
	///
	/// # Examples
	///
	/// ```
	/// extern crate vmm_sys_util;
	///
	/// use std::os::unix::io::AsRawFd;
	/// use vmm_sys_util::epoll::{ControlOperation, Epoll, EpollEvent, EventSet};
	/// use vmm_sys_util::eventfd::EventFd;
	///
	/// let epoll = Epoll::new().unwrap();
	/// let event_fd = EventFd::new(libc::EFD_NONBLOCK).unwrap();
	/// epoll
	/// .ctl(
	/// ControlOperation::Add,
	/// event_fd.as_raw_fd() as i32,
	/// EpollEvent::new(EventSet::OUT, event_fd.as_raw_fd() as u64),
	/// )
	/// .unwrap();
	/// epoll
	/// .ctl(
	/// ControlOperation::Modify,
	/// event_fd.as_raw_fd() as i32,
	/// EpollEvent::new(EventSet::IN, 4),
	/// )
	/// .unwrap();
	/// ```
	pub fn ctl(&self, operation: ControlOperation, fd: RawFd, event: EpollEvent) -> io::Result<()> {
	SyscallReturnCode(
	// SAFETY: Safe because we give a valid epoll file descriptor, a valid file descriptor
	// to watch, as well as a valid epoll_event structure. We also check the return value.
	unsafe {
	epoll_ctl(
	self.epoll_fd,
	operation as i32,
	fd,
	&event as const EpollEvent as mut epoll_event,
	)
	},
	)
	.into_empty_result()
	}

	/// Wrapper for `libc::epoll_wait`.
	/// Returns the number of file descriptors in the interest list that became ready
	/// for I/O or `errno` if an error occurred.
	///
	/// # Arguments
	///
	/// * `timeout` - specifies for how long the `epoll_wait` system call will block
	/// (measured in milliseconds).
	/// * `events` - points to a memory area that will be used for storing the events
	/// returned by `epoll_wait()` call.
	///
	/// # Examples
	///
	/// ```
	/// extern crate vmm_sys_util;
	///
	/// use std::os::unix::io::AsRawFd;
	/// use vmm_sys_util::epoll::{ControlOperation, Epoll, EpollEvent, EventSet};
	/// use vmm_sys_util::eventfd::EventFd;
	///
	/// let epoll = Epoll::new().unwrap();
	/// let event_fd = EventFd::new(libc::EFD_NONBLOCK).unwrap();
	///
	/// let mut ready_events = vec![EpollEvent::default(); 10];
	/// epoll
	/// .ctl(
	/// ControlOperation::Add,
	/// event_fd.as_raw_fd() as i32,
	/// EpollEvent::new(EventSet::OUT, 4),
	/// )
	/// .unwrap();
	/// let ev_count = epoll.wait(-1, &mut ready_events[..]).unwrap();
	/// assert_eq!(ev_count, 1);
	/// ```
	pub fn wait(&self, timeout: i32, events: &mut [EpollEvent]) -> io::Result<usize> {
	let events_count = SyscallReturnCode(
	// SAFETY: Safe because we give a valid epoll file descriptor and an array of
	// epoll_event structures that will be modified by the kernel to indicate information
	// about the subset of file descriptors in the interest list.
	// We also check the return value.
	unsafe {
	epoll_wait(
	self.epoll_fd,
	events.as_mut_ptr() as *mut epoll_event,
	events.len() as i32,
	timeout,
	)
	},
	)
	.into_result()? as usize;

	Ok(events_count)
	}
	}

	impl AsRawFd for Epoll {
	fn as_raw_fd(&self) -> RawFd {
	self.epoll_fd
	}
	}

	impl Drop for Epoll {
	fn drop(&mut self) {
	// SAFETY: Safe because this fd is opened with `epoll_create` and we trust
	// the kernel to give us a valid fd.
	unsafe {
	libc::close(self.epoll_fd);
	}
	}
	}

	#[cfg(test)]
	mod tests {
	use super::*;

	use crate::eventfd::EventFd;

	#[test]
	fn test_event_ops() {
	let mut event = EpollEvent::default();
	assert_eq!(event.events(), 0);
	assert_eq!(event.data(), 0);

	event = EpollEvent::new(EventSet::IN, 2);
	assert_eq!(event.events(), 1);
	assert_eq!(event.event_set(), EventSet::IN);

	assert_eq!(event.data(), 2);
	assert_eq!(event.fd(), 2);
	}

	#[test]
	fn test_events_debug() {
	let events = EpollEvent::new(EventSet::IN, 42);
	assert_eq!(format!("{:?}", events), "{ events: 1, data: 42 }")
	}

	#[test]
	fn test_epoll() {
	const DEFAULT__TIMEOUT: i32 = 250;
	const EVENT_BUFFER_SIZE: usize = 128;

	let epoll = Epoll::new().unwrap();
	assert_eq!(epoll.epoll_fd, epoll.as_raw_fd());

	// Let's test different scenarios for `epoll_ctl()` and `epoll_wait()` functionality.

	let event_fd_1 = EventFd::new(libc::EFD_NONBLOCK).unwrap();
	// For EPOLLOUT to be available it is enough only to be possible to write a value of
	// at least 1 to the eventfd counter without blocking.
	// If we write a value greater than 0 to this counter, the fd will be available for
	// EPOLLIN events too.
	event_fd_1.write(1).unwrap();

	let mut event_1 =
	EpollEvent::new(EventSet::IN \| EventSet::OUT, event_fd_1.as_raw_fd() as u64);

	// For EPOLL_CTL_ADD behavior we will try to add some fds with different event masks into
	// the interest list of epoll instance.
	assert!(epoll
	.ctl(
	ControlOperation::Add,
	event_fd_1.as_raw_fd() as i32,
	event_1
	)
	.is_ok());

	// We can't add twice the same fd to epoll interest list.
	assert!(epoll
	.ctl(
	ControlOperation::Add,
	event_fd_1.as_raw_fd() as i32,
	event_1
	)
	.is_err());

	let event_fd_2 = EventFd::new(libc::EFD_NONBLOCK).unwrap();
	event_fd_2.write(1).unwrap();
	assert!(epoll
	.ctl(
	ControlOperation::Add,
	event_fd_2.as_raw_fd() as i32,
	// For this fd, we want an Event instance that has `data` field set to other
	// value than the value of the fd and `events` without EPOLLIN type set.
	EpollEvent::new(EventSet::OUT, 10)
	)
	.is_ok());

	// For the following eventfd we won't write anything to its counter, so we expect EPOLLIN
	// event to not be available for this fd, even if we say that we want to monitor this type
	// of event via EPOLL_CTL_ADD operation.
	let event_fd_3 = EventFd::new(libc::EFD_NONBLOCK).unwrap();
	let event_3 = EpollEvent::new(EventSet::OUT \| EventSet::IN, event_fd_3.as_raw_fd() as u64);
	assert!(epoll
	.ctl(
	ControlOperation::Add,
	event_fd_3.as_raw_fd() as i32,
	event_3
	)
	.is_ok());

	// Let's check `epoll_wait()` behavior for our epoll instance.
	let mut ready_events = vec![EpollEvent::default(); EVENT_BUFFER_SIZE];
	let mut ev_count = epoll.wait(DEFAULT__TIMEOUT, &mut ready_events[..]).unwrap();

	// We expect to have 3 fds in the ready list of epoll instance.
	assert_eq!(ev_count, 3);

	// Let's check also the Event values that are now returned in the ready list.
	assert_eq!(ready_events[0].data(), event_fd_1.as_raw_fd() as u64);
	// For this fd, `data` field was populated with random data instead of the
	// corresponding fd value.
	assert_eq!(ready_events[1].data(), 10);
	assert_eq!(ready_events[2].data(), event_fd_3.as_raw_fd() as u64);

	// EPOLLIN and EPOLLOUT should be available for this fd.
	assert_eq!(
	ready_events[0].events(),
	(EventSet::IN \| EventSet::OUT).bits()
	);
	// Only EPOLLOUT is expected because we didn't want to monitor EPOLLIN on this fd.
	assert_eq!(ready_events[1].events(), EventSet::OUT.bits());
	// Only EPOLLOUT too because eventfd counter value is 0 (we didn't write a value
	// greater than 0 to it).
	assert_eq!(ready_events[2].events(), EventSet::OUT.bits());

	// Now we're gonna modify the Event instance for a fd to test EPOLL_CTL_MOD
	// behavior.
	// We create here a new Event with some events, other than those previously set,
	// that we want to monitor this time on event_fd_1.
	event_1 = EpollEvent::new(EventSet::OUT, 20);
	assert!(epoll
	.ctl(
	ControlOperation::Modify,
	event_fd_1.as_raw_fd() as i32,
	event_1
	)
	.is_ok());

	let event_fd_4 = EventFd::new(libc::EFD_NONBLOCK).unwrap();
	// Can't modify a fd that wasn't added to epoll interest list.
	assert!(epoll
	.ctl(
	ControlOperation::Modify,
	event_fd_4.as_raw_fd() as i32,
	EpollEvent::default()
	)
	.is_err());

	let _ = epoll.wait(DEFAULT__TIMEOUT, &mut ready_events[..]).unwrap();

	// Let's check that Event fields were indeed changed for the `event_fd_1` fd.
	assert_eq!(ready_events[0].data(), 20);
	// EPOLLOUT is now available for this fd as we've intended with EPOLL_CTL_MOD operation.
	assert_eq!(ready_events[0].events(), EventSet::OUT.bits());

	// Now let's set for a fd to not have any events monitored.
	assert!(epoll
	.ctl(
	ControlOperation::Modify,
	event_fd_1.as_raw_fd() as i32,
	EpollEvent::default()
	)
	.is_ok());

	// In this particular case we expect to remain only with 2 fds in the ready list.
	ev_count = epoll.wait(DEFAULT__TIMEOUT, &mut ready_events[..]).unwrap();
	assert_eq!(ev_count, 2);

	// Let's also delete a fd from the interest list.
	assert!(epoll
	.ctl(
	ControlOperation::Delete,
	event_fd_2.as_raw_fd() as i32,
	EpollEvent::default()
	)
	.is_ok());

	// We expect to have only one fd remained in the ready list (event_fd_3).
	ev_count = epoll.wait(DEFAULT__TIMEOUT, &mut ready_events[..]).unwrap();

	assert_eq!(ev_count, 1);
	assert_eq!(ready_events[0].data(), event_fd_3.as_raw_fd() as u64);
	assert_eq!(ready_events[0].events(), EventSet::OUT.bits());

	// If we try to remove a fd from epoll interest list that wasn't added before it will fail.
	assert!(epoll
	.ctl(
	ControlOperation::Delete,
	event_fd_4.as_raw_fd() as i32,
	EpollEvent::default()
	)
	.is_err());
	}
	}