On Aug 12, 2024, at 8:38 PM, Pavel Begunkov <asml.silence@xxxxxxxxx> wrote: > > On 8/13/24 03:09, Jens Axboe wrote: >>> On 8/12/24 7:32 PM, Pavel Begunkov wrote: >>> On 8/13/24 01:59, Jens Axboe wrote: >>>> On 8/12/24 6:50 PM, Pavel Begunkov wrote: >>>>> On 8/12/24 19:30, Jens Axboe wrote: >>>>>> On 8/12/24 12:13 PM, Jens Axboe wrote: >>>>>>> On 8/7/24 8:18 AM, Pavel Begunkov wrote: >>>>>>>> Patch 3 allows the user to pass IORING_ENTER_ABS_TIMER while waiting >>>>>>>> for completions, which makes the kernel to interpret the passed timespec >>>>>>>> not as a relative time to wait but rather an absolute timeout. >>>>>>>> >>>>>>>> Patch 4 adds a way to set a clock id to use for CQ waiting. >>>>>>>> >>>>>>>> Tests: https://github.com/isilence/liburing.git abs-timeout >>>>>>> >>>>>>> Looks good to me - was going to ask about tests, but I see you have those >>>>>>> already! Thanks. >>>>>> >>>>>> Took a look at the test, also looks good to me. But we need the man >>>>>> pages updated, or nobody will ever know this thing exists. >>>>> >>>>> If we go into that topic, people not so often read manuals >>>>> to learn new features, a semi formal tutorial would be much >>>>> more useful, I believe. >>>>> >>>>> Regardless, I can update mans before sending the tests, I was >>>>> waiting if anyone have feedback / opinions on the api. >>>> >>>> I regularly get people sending corrections or questions after having >>>> read man pages, so I'd have to disagree. In any case, if there's one >>> >>> That doesn't necessarily mean they've learned about the feature from >>> the man page. In my experience, people google a problem, find some >>> clue like a name of the feature they need and then go to a manual >>> (or other source) to learn more. >>> >>> Which is why I'm not saying that man pages don't have a purpose, on >>> the contrary, but there are often more convenient ways of discovering >>> in the long run. >> In my experience, you google if you have very little clue what you're >> doing, to hopefully learn. And you use a man page, if whatever API you're >> using has good man pages, if you're just curius about a specific >> function. There's definitely a place for both. >> None of that changes the fact that the liburing man pages should >> _always_ document all of the API. > > Nobody said the opposite, but I don't buy that man pages or lack > of thereof somehow mean "nobody will ever know this thing exists". I don’t know why we’re still arguing about this, when the point is that any addition to liburing should come with a man page update. That part isn’t up for debate, and honestly the only thing that matters here. Would be it great to have additional documentation like a tutorial? Certainly. But for a flag that adds absolute timing for waiting rather than relative, just documenting is probably all that’s needed. It’s not like it needs a ton of how to or documentation. If it only exists in a header somewhere, it’s. It going to be easy to discover. — Jens Axboe
