[PATCH liburing v1 2/3] liburing.h: Explain the history of `io_uring_get_sqe()`

[Ammar Faizi <ammarfaizi2@gnuweeb.org>]

Add a comment for `io_uring_get_sqe()` to provide historical context
and prevent misunderstandings, as seen in Pull Request 1336.

Link: https://github.com/axboe/liburing/pull/1336
Signed-off-by: Ammar Faizi <ammarfaizi2@gnuweeb.org>
---
 src/include/liburing.h | 19 +++++++++++++++++++
 1 file changed, 19 insertions(+)

diff --git a/src/include/liburing.h b/src/include/liburing.h
index b2d76f3224e2..98419e378f72 100644
--- a/src/include/liburing.h
+++ b/src/include/liburing.h
@@ -1622,24 +1622,43 @@ IOURINGINLINE int io_uring_buf_ring_available(struct io_uring *ring,
 					      unsigned short bgid)
 {
 	uint16_t head;
 	int ret;
 
 	ret = io_uring_buf_ring_head(ring, bgid, &head);
 	if (ret)
 		return ret;
 
 	return (uint16_t) (br->tail - head);
 }
 
+/*
+ * As of liburing-2.2, io_uring_get_sqe() has been converted into a
+ * "static inline" function. However, this change breaks seamless
+ * updates of liburing.so, as applications would need to be recompiled.
+ * To ensure backward compatibility, liburing keeps the original
+ * io_uring_get_sqe() symbol available in the shared library.
+ *
+ * To accomplish this, io_uring_get_sqe() is defined as a non-static
+ * inline function when LIBURING_INTERNAL is set, which only applies
+ * during liburing.so builds.
+ *
+ * This strategy ensures new users adopt the "static inline" version
+ * while preserving compatibility for old applications linked against
+ * the shared library.
+ *
+ * Relevant commits:
+ * 8be8af4afcb4 ("queue: provide io_uring_get_sqe() symbol again")
+ * 52dcdbba35c8 ("src/queue: protect io_uring_get_sqe() with LIBURING_INTERNAL")
+ */
 #ifndef LIBURING_INTERNAL
 IOURINGINLINE struct io_uring_sqe *io_uring_get_sqe(struct io_uring *ring)
 {
 	return _io_uring_get_sqe(ring);
 }
 #else
 struct io_uring_sqe *io_uring_get_sqe(struct io_uring *ring);
 #endif
 
 ssize_t io_uring_mlock_size(unsigned entries, unsigned flags);
 ssize_t io_uring_mlock_size_params(unsigned entries, struct io_uring_params *p);
 
-- 
Ammar Faizi