Add constructor of IoUring from raw FD (#288)

* Add constructor of IoUring from raw FD

The user must communicate the parameters utilized with its construction
out-of-band but can otherwise use an existing file descriptor. The
library will then map the existing ring's queues. This permits using a
pre-opened file descriptor such as one shared by a parent process, or
one stashed away to be kept open in systemd's file descriptor store.

Keeping a ring open can allow its operations to complete despite the
writer's process dying unexpectedly. Additionally, another process might
register a personality (IORING_REGISTER_PERSONALITY) to be used as means
of effective access controls for operations that must avoid confused
deputy scenarios. A ring opened by a parent might also have pre-existing
trusted restrictions (IORING_REGISTER_RESTRICTIONS) applied to it.

Note that this is _not_ an implementation of `IORING_SETUP_ATTACH_WQ` or
of a multi-issuer submission queue.

* Make parameters repr-transparent, add safety note

Author: Andreas Molzer

src/lib.rs

@@ -66,7 +66,11 @@ where
 }
 
 /// The parameters that were used to construct an [`IoUring`].
+///
+/// This type is a transparent wrapper over the system structure `io_uring_params`. A value can be
+/// (unsafely) created from any properly laid-out and initialized memory representation.
 #[derive(Clone)]
+#[repr(transparent)]
 pub struct Parameters(sys::io_uring_params);
 
 unsafe impl<S: squeue::EntryMarker, C: cqueue::EntryMarker> Send for IoUring<S, C> {}
@@ -81,6 +85,17 @@ impl IoUring<squeue::Entry, cqueue::Entry> {
     pub fn new(entries: u32) -> io::Result<Self> {
         Self::builder().build(entries)
     }
+
+    /// Create an `IoUring` instance from a pre-opened file descriptor.
+    ///
+    /// # Safety
+    ///
+    /// The caller must uphold that the file descriptor is owned and refers to a uring. The
+    /// `params` argument must be equivalent to the those previously filled in by the kernel when
+    /// the provided ring was created.
+    pub unsafe fn from_fd(fd: RawFd, params: Parameters) -> io::Result<Self> {
+        Self::with_fd_and_params(OwnedFd::from_raw_fd(fd), params.0)
+    }
 }
 
 impl<S: squeue::EntryMarker, C: cqueue::EntryMarker> IoUring<S, C> {
@@ -103,6 +118,11 @@ impl<S: squeue::EntryMarker, C: cqueue::EntryMarker> IoUring<S, C> {
     }
 
     fn with_params(entries: u32, mut p: sys::io_uring_params) -> io::Result<Self> {
+        let fd: OwnedFd = unsafe { OwnedFd::from_raw_fd(sys::io_uring_setup(entries, &mut p)?) };
+        unsafe { Self::with_fd_and_params(fd, p) }
+    }
+
+    unsafe fn with_fd_and_params(fd: OwnedFd, p: sys::io_uring_params) -> io::Result<Self> {
         // NOTE: The `SubmissionQueue` and `CompletionQueue` are references,
         // and their lifetime can never exceed `MemoryMap`.
         //
@@ -149,8 +169,6 @@ impl<S: squeue::EntryMarker, C: cqueue::EntryMarker> IoUring<S, C> {
             }
         }
 
-        let fd: OwnedFd = unsafe { OwnedFd::from_raw_fd(sys::io_uring_setup(entries, &mut p)?) };
-
         let (mm, sq, cq) = unsafe { setup_queue(&fd, &p)? };
 
         Ok(IoUring {