Move SubmissionQueue::msg_listener to msg module

Making it a standalone function.

SubmissionQueue::msg_listener is marked as deprecated, but not removed.

src/lib.rs

@@ -484,9 +484,9 @@ impl SubmissionQueue {
 
     /// Setup a listener for user space messages.
     ///
-    /// The returned [`MsgListener`] iterator will return all messages send
-    /// using [`SubmissionQueue::try_send_msg`] and
-    /// [`SubmissionQueue::send_msg`] using the returned `MsgToken`.
+    /// The returned [`MsgListener`] will return all messages send using
+    /// [`SubmissionQueue::try_send_msg`] and [`SubmissionQueue::send_msg`]
+    /// using the returned `MsgToken`.
     ///
     /// # Notes
     ///
@@ -503,8 +503,11 @@ impl SubmissionQueue {
     /// don't use `MsgToken` after it became invalid. Furthermore to ensure
     /// the creation of it succeeds it should be done early in the lifetime of
     /// `Ring`.
+    ///
+    /// This is deprecated, use [`msg::msg_listener`] instead.
+    #[deprecated(note = "use a10::msg::msg_listener instead")]
     pub fn msg_listener(self) -> io::Result<(MsgListener, MsgToken)> {
-        MsgListener::new(self)
+        msg::msg_listener(self)
     }
 
     /// Try to send a message to iterator listening for message using `MsgToken`.
@@ -517,9 +520,10 @@ impl SubmissionQueue {
     /// [`SubmissionQueue::send_msg`] for a version that tries again when the
     /// submission queue is full.
     ///
-    /// See [`SubmissionQueue::msg_listener`] for examples.
+    /// See [`msg_listener`] for examples.
     ///
     /// [polling]: Ring::poll
+    /// [`msg_listener`]: msg::msg_listener
     pub fn try_send_msg(&self, token: MsgToken, data: u32) -> io::Result<()> {
         self.add_no_result(|submission| unsafe {
             submission.msg(self.shared.ring_fd.as_raw_fd(), (token.0).0 as u64, data, 0);

src/msg.rs

@@ -1,7 +1,7 @@
 //! User space messages.
 //!
-//! To setup a [`MsgListener`] use [`SubmissionQueue::msg_listener`]. It returns
-//! the listener as well as a [`MsgToken`], which can be used in
+//! To setup a [`MsgListener`] use [`msg_listener`]. It returns the listener as
+//! well as a [`MsgToken`], which can be used in
 //! [`SubmissionQueue::try_send_msg`] and [`SubmissionQueue::send_msg`] to send
 //! a message to the created `MsgListener`.
 
@@ -19,6 +19,35 @@ use crate::{OpIndex, SubmissionQueue};
 #[allow(clippy::module_name_repetitions)]
 pub struct MsgToken(pub(crate) OpIndex);
 
+/// Setup a listener for user space messages.
+///
+/// The returned [`MsgListener`] will return all messages send using
+/// [`SubmissionQueue::try_send_msg`] and [`SubmissionQueue::send_msg`] using
+/// the returned `MsgToken`.
+///
+/// # Notes
+///
+/// This will return an error if too many operations are already queued,
+/// this is usually resolved by calling [`Ring::poll`].
+///
+/// The returned `MsgToken` has an implicitly lifetime linked to
+/// `MsgListener`. If `MsgListener` is dropped the `MsgToken` will
+/// become invalid.
+///
+/// Due to the limitations mentioned above it's advised to consider the
+/// usefulness of the type severly limited. The returned `MsgListener`
+/// iterator should live for the entire lifetime of the `Ring`, to ensure we
+/// don't use `MsgToken` after it became invalid. Furthermore to ensure
+/// the creation of it succeeds it should be done early in the lifetime of
+/// `Ring`.
+///
+/// [`Ring::poll`]: crate::Ring::poll
+#[allow(clippy::module_name_repetitions)]
+pub fn msg_listener(sq: SubmissionQueue) -> io::Result<(MsgListener, MsgToken)> {
+    let op_index = sq.queue_multishot()?;
+    Ok((MsgListener { sq, op_index }, MsgToken(op_index)))
+}
+
 /// [`AsyncIterator`] behind [`SubmissionQueue::msg_listener`].
 ///
 /// [`AsyncIterator`]: std::async_iter::AsyncIterator
@@ -31,12 +60,6 @@ pub struct MsgListener {
 }
 
 impl MsgListener {
-    /// Create a new `MsgListener`.
-    pub(crate) fn new(sq: SubmissionQueue) -> io::Result<(MsgListener, MsgToken)> {
-        let op_index = sq.queue_multishot()?;
-        Ok((MsgListener { sq, op_index }, MsgToken(op_index)))
-    }
-
     /// This is the same as the `AsyncIterator::poll_next` function, but then
     /// available on stable Rust.
     pub fn poll_next(self: Pin<&mut Self>, ctx: &mut task::Context<'_>) -> Poll<Option<u32>> {

tests/ring.rs

@@ -18,7 +18,7 @@ use std::time::{Duration, Instant};
 use a10::cancel::Cancel;
 use a10::fs::OpenOptions;
 use a10::io::ReadBufPool;
-use a10::msg::{MsgListener, MsgToken, SendMsg};
+use a10::msg::{msg_listener, MsgListener, MsgToken, SendMsg};
 use a10::poll::{multishot_poll, oneshot_poll, MultishotPoll, OneshotPoll};
 use a10::{mem, process, AsyncFd, Config, Ring, SubmissionQueue};
 
@@ -279,7 +279,7 @@ fn message_sending() {
     is_send::<MsgToken>();
     is_sync::<MsgToken>();
 
-    let (msg_listener, msg_token) = sq.clone().msg_listener().unwrap();
+    let (msg_listener, msg_token) = msg_listener(sq.clone()).unwrap();
     let mut msg_listener = pin!(msg_listener);
     start_mulitshot_op(msg_listener.as_mut());