Skip to content

mctp: Adjust doc comments #18

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
mkj merged 1 commit into from
Jul 30, 2025
Merged

mctp: Adjust doc comments #18

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
64 changes: 20 additions & 44 deletions mctp/src/lib.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -259,8 +259,9 @@ pub trait ReqChannel {

/// Blocking receive
///
/// Returns a filled slice of `buf`, MCTP message type, and IC bit.
/// Will fail if used without a prior call to `send` or `send_vectored`.
/// Returns the MCTP message type, the IC bit, and the filled subslice of
/// `buf`. Will fail if used without a prior call to `send` or
/// `send_vectored`.
fn recv<'f>(
&mut self,
buf: &'f mut [u8],
Expand All @@ -270,16 +271,17 @@ pub trait ReqChannel {
fn remote_eid(&self) -> Eid;
}

#[allow(missing_docs)]
/// Async equivalent of [`ReqChannel`]
/// Async equivalent of [`ReqChannel`].
pub trait AsyncReqChannel {
/// Async equivalent of [`ReqChannel::send_vectored`].
fn send_vectored(
&mut self,
typ: MsgType,
integrity_check: MsgIC,
bufs: &[&[u8]],
) -> impl Future<Output = Result<()>>;

/// Async equivalent of [`ReqChannel::send`].
fn send(
&mut self,
typ: MsgType,
Expand All @@ -288,12 +290,13 @@ pub trait AsyncReqChannel {
async move { self.send_vectored(typ, MsgIC(false), &[buf]).await }
}

/// Async equivalent of [`ReqChannel::recv`].
fn recv<'f>(
&mut self,
buf: &'f mut [u8],
) -> impl Future<Output = Result<(MsgType, MsgIC, &'f mut [u8])>>;

/// Return the remote Endpoint ID
/// Async equivalent of [`ReqChannel::remote_eid`].
fn remote_eid(&self) -> Eid;
}

Expand Down Expand Up @@ -342,49 +345,29 @@ pub trait RespChannel {
fn req_channel(&self) -> Result<Self::ReqChannel>;
}

#[allow(missing_docs)]
/// Async equivalent of [`RespChannel`]
pub trait AsyncRespChannel {
/// `ReqChannel` type returned by [`req_channel`](Self::req_channel)
/// Async equivalent of [`RespChannel::ReqChannel`].
type ReqChannel<'a>: AsyncReqChannel
where
Self: 'a;

/// Send a slice of buffers to this endpoint, blocking.
///
/// The slice of buffers will be sent as a single message
/// (as if concatenated). Accepting multiple buffers allows
/// higher level protocols to more easily append their own
/// protocol headers to a payload without needing extra
/// buffer allocations.
///
/// The sent message type will match that received by the
/// corresponding `AsyncListener`.
///
/// The `integrity_check` argument is the MCTP header IC bit.
Copy link
Member

@mkj mkj Jul 30, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we still might want something like

/// Equivalent of [`ReqChannel::send_vectored`]

Otherwise docs for traits that implement it won't have any link to ReqChannel, for example RouterAsyncReqChannel.

/// Async equivalent of [`RespChannel::send_vectored`].
fn send_vectored(
&mut self,
integrity_check: MsgIC,
bufs: &[&[u8]],
) -> impl Future<Output = Result<()>>;

/// Send a message to this endpoint, blocking.
///
/// Transport implementations will typically use the trait provided method
/// that calls [`send_vectored`](Self::send_vectored).
///
/// The sent message type will match that received by the
/// corresponding `AsyncListener`.
///
/// IC bit is unset.
/// Async equivalent of [`RespChannel::send`].
fn send(&mut self, buf: &[u8]) -> impl Future<Output = Result<()>> {
async move { self.send_vectored(MsgIC(false), &[buf]).await }
}

/// Return the remote Endpoint ID
/// Async equivalent of [`RespChannel::remote_eid`].
fn remote_eid(&self) -> Eid;

/// Constructs a new ReqChannel to the same MCTP endpoint as this RespChannel.
/// Async equivalent of [`RespChannel::req_channel`].
// TODO: should this be async?
fn req_channel(&self) -> Result<Self::ReqChannel<'_>>;
}
Expand All @@ -394,38 +377,31 @@ pub trait AsyncRespChannel {
/// This will receive messages with TO=1. Platform-specific constructors
/// will specify the MCTP message parameters (eg, message type) to listen for.
pub trait Listener {
/// `RespChannel` type returned by this `Listener`
/// `RespChannel` type returned by this `Listener`.
type RespChannel<'a>: RespChannel
where
Self: 'a;

/// Blocking receive
///
/// This receives a single MCTP message matched by the `Listener`.
/// Returns a filled slice of `buf`, `RespChannel`, and IC bit `MsgIC`.
///
/// The returned `RespChannel` should be used to send responses to the
/// This receives a single MCTP message matched by the `Listener`. Returns
/// the MCTP message type, the IC bit, the filled subslice of `buf`, and
/// the response channel that should be used to send responses to the
/// request.
fn recv<'f>(
&mut self,
buf: &'f mut [u8],
) -> Result<(MsgType, MsgIC, &'f mut [u8], Self::RespChannel<'_>)>;
}

#[allow(missing_docs)]
/// Async equivalent of [`Listener`]
/// Async equivalent of [`Listener`].
pub trait AsyncListener {
/// `RespChannel` type returned by this `Listener`
/// Async equivalent of [`Listener::RespChannel`].
type RespChannel<'a>: AsyncRespChannel
where
Self: 'a;

/// Blocking receive
///
/// This receives a single MCTP message matched by the `Listener`.
/// Returns a filled slice of `buf`, `RespChannel`, and IC bit `MsgIC`.
///
/// The returned `RespChannel` should be used to send responses.
/// Async equivalent of [`Listener::recv`].
fn recv<'f>(
&mut self,
buf: &'f mut [u8],
Expand Down