io_uring: add some more source code comments/docs
Change-Id: I8ba77a18b51f67a9edbd1fa488b9791f8bf6e40a
diff --git a/src/core/osmo_io.c b/src/core/osmo_io.c
index f23986f..649bf73 100644
--- a/src/core/osmo_io.c
+++ b/src/core/osmo_io.c
@@ -323,6 +323,10 @@
iofd->pending = pending;
}
+/*! completion handler: Called by osmo_io backend after a given I/O operation has completed
+ * \param[in] iofd I/O file-descriptor on which I/O has completed
+ * \param[in] msg message buffer containing data related to completed I/O
+ * \param[in] hdr serialized msghdr containing state of completed I/O */
void iofd_handle_recv(struct osmo_io_fd *iofd, struct msgb *msg, int rc, struct iofd_msghdr *hdr)
{
talloc_steal(iofd->msgb_alloc.ctx, msg);
diff --git a/src/core/osmo_io_internal.h b/src/core/osmo_io_internal.h
index 5b7ab90..73a81e1 100644
--- a/src/core/osmo_io_internal.h
+++ b/src/core/osmo_io_internal.h
@@ -111,16 +111,24 @@
};
-/* serialized version of 'struct msghdr' employed by sendmsg/recvmsg */
+/*! serialized version of 'struct msghdr' employed by sendmsg/recvmsg */
struct iofd_msghdr {
+ /*! entry into osmo_io_fd.tx_queue.msg_queue */
struct llist_head list;
enum iofd_msg_action action;
+ /*! the 'struct msghdr' we are wrapping/ecapsulating here */
struct msghdr hdr;
+ /*! socket address of the remote peer */
struct osmo_sockaddr osa;
+ /*! io-vector we need to pass as argument to sendmsg/recvmsg; is set up
+ * to point into msg below */
struct iovec iov[1];
+ /*! flags we pass as argument to sendmsg / recvmsg */
int flags;
+ /*! message-buffer containing data for this I/O operation */
struct msgb *msg;
+ /*! I/O file descriptor on which we perform this I/O operation */
struct osmo_io_fd *iofd;
};
diff --git a/src/core/osmo_io_uring.c b/src/core/osmo_io_uring.c
index a6395fe..abeea79 100644
--- a/src/core/osmo_io_uring.c
+++ b/src/core/osmo_io_uring.c
@@ -59,6 +59,8 @@
static __thread struct osmo_io_uring g_ring;
static void iofd_uring_cqe(struct io_uring *ring);
+
+/*! read call-back for eventfd notifying us if entries are in the completion queue */
static int iofd_uring_poll_cb(struct osmo_fd *ofd, unsigned int what)
{
struct io_uring *ring = ofd->data;
@@ -157,6 +159,7 @@
iofd->u.uring.read_msghdr = msghdr;
}
+/*! completion call-back for READ/RECVFROM */
static void iofd_uring_handle_recv(struct iofd_msghdr *msghdr, int rc)
{
struct osmo_io_fd *iofd = msghdr->iofd;
@@ -179,6 +182,7 @@
static int iofd_uring_submit_tx(struct osmo_io_fd *iofd);
+/*! completion call-back for WRITE/SENDTO */
static void iofd_uring_handle_tx(struct iofd_msghdr *msghdr, int rc)
{
struct osmo_io_fd *iofd = msghdr->iofd;
@@ -220,10 +224,12 @@
out:
iofd->u.uring.write_msghdr = NULL;
+ /* submit the next to-be-transmitted message for this file descriptor */
if (iofd->u.uring.write_enabled && !IOFD_FLAG_ISSET(iofd, IOFD_FLAG_CLOSED))
iofd_uring_submit_tx(iofd);
}
+/*! handle completion of a single I/O message */
static void iofd_uring_handle_completion(struct iofd_msghdr *msghdr, int res)
{
struct osmo_io_fd *iofd = msghdr->iofd;
@@ -250,6 +256,7 @@
talloc_free(iofd);
}
+/*! process all pending completion queue entries in given io_uring */
static void iofd_uring_cqe(struct io_uring *ring)
{
int rc;
@@ -274,6 +281,7 @@
}
}
+/*! will submit the next to-be-transmitted message for given iofd */
static int iofd_uring_submit_tx(struct osmo_io_fd *iofd)
{
struct io_uring_sqe *sqe;