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

[Jens Axboe <axboe@kernel.dk>]

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.

>> spot that SHOULD have the documentation, it's the man pages. Definitely
>> any addition should be added there too.
>>
>> I'd love for the man pages to have more section 7 additions, like one on
>> fixed buffers and things like that, so that it would be THE spot to get
>> to know about these features. Tutorials always useful (even if they tend
>> often age poorly), but that should be an addition to the man pages, not
> 
> "tutorials" could be different, they can be kept in the repo and
> up to date. bpftrace manual IMHO is a good example, it's more
> 'leisurely' readable, whereas manual pages need to be descriptive
> and hence verbose to cover all edge cases and conditions.
> 
> https://github.com/bpftrace/bpftrace/blob/master/man/adoc/bpftrace.adoc

Yeah that'd be fine too, the closer to the repo, the better. And maybe
that can replace section 7 man pages, we are sorely missing some
descriptions of idiomatic usage of various features. That kind of thing
is hard to learn in a man page.

-- 
Jens Axboe