1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235
// hinix/src/eventfd.rs
//
// This is part of the Rust 'hinix' crate
//
// Copyright (c) 2018-2020, Frank Pagliughi
//
// Licensed under the MIT license:
// <LICENSE or http://opensource.org/licenses/MIT>
// This file may not be copied, modified, or distributed except according
// to those terms.
//
//! Module to manage Linux event objects.
//!
//! See:
//! <https://man7.org/linux/man-pages/man2/eventfd.2.html>
//!
use crate::{Error, Result};
use nix::{self, sys::eventfd, unistd};
use std::{
mem,
os::{
raw::c_uint,
unix::io::{AsFd, AsRawFd, BorrowedFd, FromRawFd, OwnedFd, RawFd},
},
slice,
};
/// The size, in bytes, of the value held by an eventfd.
/// This is the required size of a buffer that is used for reads and writes,
/// as the value is a u64.
const EFD_VAL_SIZE: usize = mem::size_of::<u64>();
/// The flags used to create an EventFd
pub type EfdFlags = eventfd::EfdFlags;
/// An event object that can be used as a wait/notify mechanism between
/// user-space applications, threads in an app, or between the kernel and
/// user-space.
///
/// This is a simpler, more efficient signaling mechanism than a pipe, if
/// event notification is all that is required by the application.
///
/// The event is seen as a normal file handle, and thus can be used in
/// combination with other handles such as from sockets, pipes, etc,
/// in a poll/epoll/select call to provide additional signaling
/// capabilities.
#[derive(Debug)]
pub struct EventFd(OwnedFd);
impl EventFd {
/// Create a new event object.
///
/// This is the default configuration of the event object with no flags.
/// When read, the value is returned and the count is reset to zero.
///
/// # Parameters
///
/// `initval` The initial value held by the object
pub fn new(initval: u64) -> Result<EventFd> {
Self::with_flags(initval, EfdFlags::empty())
}
/// Create a new event object with the semaphore option.
///
/// This is applies the EDF_SEMAPHORE flag. When read, the value
/// returned is 1, and the value is decremented by 1.
///
/// # Parameters
///
/// `initval` The initial value held by the object
pub fn new_semaphore(initval: u64) -> Result<EventFd> {
Self::with_flags(initval, EfdFlags::EFD_SEMAPHORE)
}
/// Create a new event object with the specified flags.
///
/// # Parameters
/// `initval` The initial value held by the object
/// `flags` The flags used to create the object
///
/// <http://man7.org/linux/man-pages/man2/eventfd.2.html>
pub fn with_flags(initval: u64, flags: EfdFlags) -> Result<EventFd> {
let fd = eventfd::eventfd(initval as c_uint, flags)?;
let fd = unsafe { OwnedFd::from_raw_fd(fd) };
Ok(EventFd(fd))
}
/// Try to clone the event object by making a dup() of the OS file handle.
pub fn try_clone(&self) -> Result<Self> {
let fd = self
.0
.try_clone()
.map_err(|e| Error::try_from(e).unwrap_or_else(|_| Error::from_i32(0)))?;
Ok(EventFd(fd))
}
/// Reads the value of the event object.
pub fn read(&self) -> Result<u64> {
let mut buf: [u8; 8] = [0; EFD_VAL_SIZE];
if unistd::read(self.0.as_raw_fd(), &mut buf)? != EFD_VAL_SIZE {
return Err(Error::EIO);
}
let val: u64 = unsafe { *(&buf as *const u8 as *const u64) };
Ok(val)
}
/// Writes a value to the event object.
///
/// # Parameters
/// `val` The value to _add_ to the one held by the object.
pub fn write(&self, val: u64) -> Result<()> {
let buf = unsafe { slice::from_raw_parts(&val as *const u64 as *const u8, EFD_VAL_SIZE) };
if unistd::write(self.0.as_raw_fd(), buf)? != EFD_VAL_SIZE {
return Err(Error::EIO);
}
Ok(())
}
}
impl AsFd for EventFd {
/// Gets the raw file handle for the event object.
fn as_fd(&self) -> BorrowedFd<'_> {
self.0.as_fd()
}
}
impl AsRawFd for EventFd {
/// Gets the raw file handle for the event object.
fn as_raw_fd(&self) -> RawFd {
self.0.as_raw_fd()
}
}
/////////////////////////////////////////////////////////////////////////////
// Unit Tests
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn test_normal() {
let evtfd = EventFd::new(0).unwrap();
assert!(evtfd.as_raw_fd() >= 0);
// Writing a value should get us the same back on a read.
evtfd.write(1).unwrap();
let n = evtfd.read().unwrap();
assert_eq!(1, n);
// Try another value that's not '1'
evtfd.write(42).unwrap();
let n = evtfd.read().unwrap();
assert_eq!(42, n);
// Multiple writes should sunm the value
evtfd.write(5).unwrap();
evtfd.write(6).unwrap();
let n = evtfd.read().unwrap();
assert_eq!(11, n);
}
#[test]
fn test_non_blocking() {
let evtfd = EventFd::with_flags(0, EfdFlags::EFD_NONBLOCK).unwrap();
assert!(evtfd.as_raw_fd() >= 0);
// No value in object should get us an EAGAIN error.
match evtfd.read() {
Ok(_) => assert!(false),
Err(err) => assert_eq!(Error::EAGAIN, err),
}
// Writing a value should get us the same back on a read.
evtfd.write(6).unwrap();
let n = evtfd.read().unwrap();
assert_eq!(6, n);
// The read should have cleared the value, so another is an error.
match evtfd.read() {
Ok(_) => assert!(false),
Err(err) => assert_eq!(Error::EAGAIN, err),
}
// Try another value that's not '1'
evtfd.write(42).unwrap();
let n = evtfd.read().unwrap();
assert_eq!(42, n);
}
#[test]
fn test_semaphore() {
let evtfd = EventFd::new_semaphore(0).unwrap();
assert!(evtfd.as_raw_fd() >= 0);
// Signal then read back should get us a 1.
evtfd.write(1).unwrap();
let n = evtfd.read().unwrap();
assert_eq!(1, n);
// Try another value that's not 1.
evtfd.write(2).unwrap();
// Each read should return 1.
let n = evtfd.read().unwrap();
assert_eq!(1, n);
let n = evtfd.read().unwrap();
assert_eq!(1, n);
}
#[test]
fn test_semaphore_non_blocking() {
let evtfd =
EventFd::with_flags(0, EfdFlags::EFD_SEMAPHORE | EfdFlags::EFD_NONBLOCK).unwrap();
assert!(evtfd.as_raw_fd() >= 0);
// Try another value that's not '1'
evtfd.write(2).unwrap();
let n = evtfd.read().unwrap();
assert_eq!(1, n);
let n = evtfd.read().unwrap();
assert_eq!(1, n);
// The read should have cleared the value, so another is an error.
match evtfd.read() {
Ok(_) => assert!(false),
Err(err) => assert_eq!(Error::EAGAIN, err),
}
}
}