refactor(io,net): move cmsg to io ancillary (#730)

* refactor(io,net): move cmsg to io ancillary

* fix(net): use package version

Author: fantix

compio-io/Cargo.toml

@@ -14,11 +14,22 @@ compio-buf = { workspace = true, features = ["arrayvec", "bytes"] }
 futures-util = { workspace = true, features = ["sink"] }
 paste = { workspace = true }
 synchrony = { workspace = true, features = ["bilock"] }
+
+cfg-if = { workspace = true, optional = true }
 thiserror = { workspace = true, optional = true }
 serde = { version = "1.0.219", optional = true }
 serde_json = { version = "1.0.140", optional = true }
 
+[target.'cfg(unix)'.dependencies]
+libc = { workspace = true, optional = true }
+
+[target.'cfg(windows)'.dependencies]
+windows-sys = { workspace = true, optional = true, features = [
+    "Win32_Networking_WinSock",
+] }
+
 [dev-dependencies]
+aligned-array = "1.0.1"
 tokio = { workspace = true, features = ["macros", "rt"] }
 serde = { version = "1.0.219", features = ["derive"] }
 futures-executor = "0.3.30"
@@ -27,6 +38,7 @@ futures-executor = "0.3.30"
 default = []
 compat = ["futures-util/io"]
 sync = []
+ancillary = ["dep:cfg-if", "dep:libc", "dep:windows-sys"]
 
 # Codecs
 # Serde json codec

compio-net/src/cmsg/mod.rs compio-io/src/ancillary/mod.rscompio-net/src/cmsg/mod.rs renamed to compio-io/src/ancillary/mod.rs

@@ -1,3 +1,15 @@
+//! Ancillary data (control message) support for connected streams.
+//!
+//! Ancillary messages are used to pass out-of-band information such as file
+//! descriptors (Unix domain sockets), credentials, or kTLS record types.
+//!
+//! # Types
+//!
+//! - [`AncillaryRef`]: A reference to a single ancillary data entry.
+//! - [`AncillaryIter`]: An iterator over a buffer of ancillary messages.
+//! - [`AncillaryBuilder`]: A builder for constructing ancillary messages into a
+//!   caller-supplied send buffer.
+
 use std::{marker::PhantomData, mem::MaybeUninit};
 
 cfg_if::cfg_if! {
@@ -10,10 +22,10 @@ cfg_if::cfg_if! {
     }
 }
 
-/// Reference to a control message.
-pub struct CMsgRef<'a>(sys::CMsgRef<'a>);
+/// Reference to an ancillary (control) message.
+pub struct AncillaryRef<'a>(sys::CMsgRef<'a>);
 
-impl CMsgRef<'_> {
+impl AncillaryRef<'_> {
     /// Returns the level of the control message.
     pub fn level(&self) -> i32 {
         self.0.level()
@@ -41,14 +53,14 @@ impl CMsgRef<'_> {
     }
 }
 
-/// An iterator for control messages.
-pub struct CMsgIter<'a> {
+/// An iterator for ancillary (control) messages.
+pub struct AncillaryIter<'a> {
     inner: sys::CMsgIter,
     _p: PhantomData<&'a ()>,
 }
 
-impl<'a> CMsgIter<'a> {
-    /// Create [`CMsgIter`] with the given buffer.
+impl<'a> AncillaryIter<'a> {
+    /// Create [`AncillaryIter`] with the given buffer.
     ///
     /// # Panics
     ///
@@ -66,28 +78,28 @@ impl<'a> CMsgIter<'a> {
     }
 }
 
-impl<'a> Iterator for CMsgIter<'a> {
-    type Item = CMsgRef<'a>;
+impl<'a> Iterator for AncillaryIter<'a> {
+    type Item = AncillaryRef<'a>;
 
     fn next(&mut self) -> Option<Self::Item> {
         unsafe {
             let cmsg = self.inner.current();
             self.inner.next();
-            cmsg.map(CMsgRef)
+            cmsg.map(AncillaryRef)
         }
     }
 }
 
-/// Helper to construct control message.
-pub struct CMsgBuilder<'a> {
+/// Helper to construct ancillary (control) messages.
+pub struct AncillaryBuilder<'a> {
     inner: sys::CMsgIter,
     len: usize,
     _p: PhantomData<&'a mut ()>,
 }
 
-impl<'a> CMsgBuilder<'a> {
-    /// Create [`CMsgBuilder`] with the given buffer. The buffer will be zeroed
-    /// on creation.
+impl<'a> AncillaryBuilder<'a> {
+    /// Create [`AncillaryBuilder`] with the given buffer. The buffer will be
+    /// zeroed on creation.
     ///
     /// # Panics
     ///

compio-net/src/cmsg/unix.rs compio-io/src/ancillary/unix.rscompio-net/src/cmsg/unix.rs renamed to compio-io/src/ancillary/unix.rs

@@ -128,6 +128,8 @@ use synchrony::unsync as sync;
 
 type PinBoxFuture<T> = Pin<Box<dyn Future<Output = T>>>;
 
+#[cfg(feature = "ancillary")]
+pub mod ancillary;
 mod buffer;
 pub mod framed;
 

compio-net/src/cmsg/windows.rs compio-io/src/ancillary/windows.rscompio-net/src/cmsg/windows.rs renamed to compio-io/src/ancillary/windows.rs

@@ -2,12 +2,12 @@ use std::mem::MaybeUninit;
 
 use aligned_array::{A8, Aligned};
 use compio_buf::{IoBuf, IoBufMut};
-use compio_net::{CMsgBuilder, CMsgIter};
+use compio_io::ancillary::{AncillaryBuilder, AncillaryIter};
 
 #[test]
 fn test_cmsg() {
     let mut buf: Aligned<A8, [u8; 64]> = Aligned([0u8; 64]);
-    let mut builder = CMsgBuilder::new(buf.as_uninit());
+    let mut builder = AncillaryBuilder::new(buf.as_uninit());
 
     builder.try_push(0, 0, ()).unwrap(); // 16 / 12
     builder.try_push(1, 1, u32::MAX).unwrap(); // 16 + 4 + 4 / 12 + 4
@@ -17,7 +17,7 @@ fn test_cmsg() {
 
     unsafe {
         let buf = buf.slice(..len);
-        let mut iter = CMsgIter::new(&buf);
+        let mut iter = AncillaryIter::new(&buf);
 
         let cmsg = iter.next().unwrap();
         assert_eq!((cmsg.level(), cmsg.ty(), cmsg.data::<()>()), (0, 0, &()));
@@ -39,12 +39,12 @@ fn test_cmsg() {
 #[should_panic]
 fn invalid_buffer_length() {
     let mut buf = [MaybeUninit::new(0u8); 1];
-    CMsgBuilder::new(&mut buf);
+    AncillaryBuilder::new(&mut buf);
 }
 
 #[test]
 #[should_panic]
 fn invalid_buffer_alignment() {
     let mut buf = [MaybeUninit::new(0u8); 64];
-    CMsgBuilder::new(&mut buf[1..]);
+    AncillaryBuilder::new(&mut buf[1..]);
 }

compio-io/src/lib.rs

@@ -17,7 +17,7 @@ rustdoc-args = ["--cfg", "docsrs"]
 # Workspace dependencies
 compio-buf = { workspace = true }
 compio-driver = { workspace = true }
-compio-io = { workspace = true }
+compio-io = { workspace = true, features = ["ancillary"] }
 compio-runtime = { workspace = true }
 
 cfg-if = { workspace = true }
@@ -40,7 +40,6 @@ libc = { workspace = true }
 # Shared dev dependencies for all platforms
 [dev-dependencies]
 compio-macros = { workspace = true }
-aligned-array = "1.0.1"
 futures-util = { workspace = true }
 tempfile = { workspace = true }
 

compio-net/tests/cmsg.rs compio-io/tests/ancillary.rscompio-net/tests/cmsg.rs renamed to compio-io/tests/ancillary.rs

@@ -13,7 +13,6 @@
     html_favicon_url = "https://github.com/compio-rs/compio-logo/raw/refs/heads/master/generated/colored-bold.svg"
 )]
 
-mod cmsg;
 mod opts;
 mod resolve;
 mod socket;
@@ -22,7 +21,27 @@ mod tcp;
 mod udp;
 mod unix;
 
-pub use cmsg::*;
+/// Reference to a control message.
+#[deprecated(
+    since = "0.12.0",
+    note = "use `compio_io::ancillary::AncillaryRef` instead"
+)]
+pub type CMsgRef<'a> = compio_io::ancillary::AncillaryRef<'a>;
+
+/// An iterator for control messages.
+#[deprecated(
+    since = "0.12.0",
+    note = "use `compio_io::ancillary::AncillaryIter` instead"
+)]
+pub type CMsgIter<'a> = compio_io::ancillary::AncillaryIter<'a>;
+
+/// Helper to construct control message.
+#[deprecated(
+    since = "0.12.0",
+    note = "use `compio_io::ancillary::AncillaryBuilder` instead"
+)]
+pub type CMsgBuilder<'a> = compio_io::ancillary::AncillaryBuilder<'a>;
+
 /// Providing functionalities to wait for readiness.
 #[deprecated(since = "0.12.0", note = "Use `compio::runtime::fd::PollFd` instead")]
 pub type PollFd<T> = compio_runtime::fd::PollFd<T>;

compio-net/Cargo.toml

@@ -15,7 +15,7 @@ rustdoc-args = ["--cfg", "docsrs"]
 
 [dependencies]
 # Workspace dependencies
-compio-io = { workspace = true }
+compio-io = { workspace = true, features = ["ancillary"] }
 compio-buf = { workspace = true, features = ["bytes"] }
 compio-log = { workspace = true }
 compio-net = { workspace = true }

compio-net/src/lib.rs

@@ -17,7 +17,8 @@ use std::{
 };
 
 use compio_buf::{BufResult, IntoInner, IoBuf, IoBufMut, SetLen, buf_try};
-use compio_net::{CMsgBuilder, CMsgIter, UdpSocket};
+use compio_io::ancillary::{AncillaryBuilder, AncillaryIter};
+use compio_net::UdpSocket;
 use quinn_proto::{EcnCodepoint, Transmit};
 #[cfg(windows)]
 use windows_sys::Win32::Networking::WinSock;
@@ -344,7 +345,7 @@ impl Socket {
 
         // SAFETY: `control` contains valid data
         unsafe {
-            for cmsg in CMsgIter::new(&control) {
+            for cmsg in AncillaryIter::new(&control) {
                 #[cfg(windows)]
                 const UDP_COALESCED_INFO: i32 = WinSock::UDP_COALESCED_INFO as i32;
 
@@ -420,7 +421,7 @@ impl Socket {
         let ecn = transmit.ecn.map_or(0, |x| x as u8);
 
         let mut control = Ancillary::<CMSG_LEN>::new();
-        let mut builder = CMsgBuilder::new(control.as_uninit());
+        let mut builder = AncillaryBuilder::new(control.as_uninit());
 
         // ECN
         if is_ipv4 {