Re: [PATCH v2 0/4] clodkid and abs mode CQ wait timeouts

[Jens Axboe <axboe@kernel.dk>]

On Aug 12, 2024, at 8:38 PM, Pavel Begunkov <asml.silence@gmail.com> 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