Started `UnmanagedFD`.

Added README.md, prepared for uploading to crates.io.

Fortune for mapped-file's current commit: Small blessing − 小吉

Cargo.toml

@@ -2,11 +2,17 @@
 name = "mapped-file"
 description = "Construct a memory mapping over any file object"
 keywords = ["unix", "mmap", "generic", "file", "fd"]
-version = "0.1.0"
+version = "0.0.1"
 edition = "2021"
+license="MIT"
 
 # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
 
+[features]
+# Add support for file-descriptor operations other than simply mapping
+# TODO: XXX: Incomplete, will be enabled by default when complete
+file=[]
+
 [dependencies]
 lazy_static = "1.4.0"
 libc = "0.2.132"

README.md

@@ -0,0 +1,42 @@
+# `MemoryFile<T>`: Map over any file object
+
+A safe and ergonomic `mmap()` wrapper for arbitrary file-descriptor handles.
+
+__NOTE__: Working release, but still in development.
+
+## Usage
+
+`MemoryFile<T>` can be used to consume any type `T` that implements `AsRawFd`, form a mapping over that file-descriptor, and then unmap the memory before the `T` itself is dropped (which can be a reference or value.)
+The `MemoryFile<T>` can also be consumed back into the `T`, unmapping (and optionally syncing) the memory in the process.
+
+### Examples
+
+A function mapping file memory working on arbitrary file-descriptor holding objects.
+
+```rust
+pub fn files_equal<T: ?Sized, U: ?Sized>(file1: &T, file2: &U, size: usize) -> io::Result<bool>
+	where T: AsRawFd,
+		  U: AsRawFd
+{
+	let file1 = MappedFile::try_new(file1, size, Perm::Readonly, Flags::Private)?.with_advice(Advice::Sequential)?;
+	let file2 = MappedFile::try_new(file2, size, Perm::Readonly, Flags::Private)?.with_advice(Advice::Sequential)?;
+	Ok(&file1[..] == &file2[..])
+}
+```
+
+Although, it is probably a better pattern to allow the caller to handle the mapping, and the callee to take any kind of mapping like so:
+
+``` rust
+pub fn files_equal<T: ?Sized, U: ?Sized>(file1: &MappedFile<T>, file2: &MappedFile<U>) -> bool
+	where T: AsRawFd,
+		  U: AsRawFd
+{
+	&file1[..] == &file2[..]
+}
+
+```
+
+However, `MappedFile<T>` also implements `Borrow<[u8]>`, so any `&MappedFile<T>` can be passed to any function as `AsRef<[u8]>` too.
+
+# License
+MIT

src/file/unmanaged.rs

@@ -6,4 +6,38 @@ use super::*;
 #[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
 pub struct UnmanagedFD(RawFd);
 
+impl UnmanagedFD {
+    #[inline] 
+    pub fn new(alias: &(impl AsRawFd + ?Sized)) -> Self
+    {
+	Self(alias.as_raw_fd())
+    }
+}
+
+impl From<RawFd> for UnmanagedFD
+{
+    #[inline] 
+    fn from(from: RawFd) -> Self
+    {
+	debug_assert!(from >= 0, "Invalid file descriptor");
+	Self(from)
+    }
+}
+
+impl FromRawFd for UnmanagedFD
+{
+    unsafe fn from_raw_fd(fd: RawFd) -> Self {
+	Self(fd)
+    }
+}
+
+
+impl AsRawFd for UnmanagedFD
+{
+    #[inline(always)] 
+    fn as_raw_fd(&self) -> RawFd {
+	self.0
+    }
+}
+
 //TODO: implement a full version of the temporary struct `UnmanagedFD` from `utf8encode`

src/lib.rs

@@ -26,6 +26,7 @@ mod ffi;
 use ffi::c_try;
 
 pub mod hugetlb;
+#[cfg(feature="file")]
 pub mod file;
 
 use hugetlb::{