Hi Scott, in the NAME section, please put timeout_add_nsec after timeout_add_usec to agree with the order in the SYNOPSIS.
In any case, please go ahead. It appears jmc@ is developing a sore elbow from more than a year of medicine ball ping pong. ;-) The following are merely suggestions / observations / questions, not conditions. Scott Cheloha wrote on Sat, Dec 31, 2022 at 11:22:22AM -0500: > mvs@ is nudging me to realign the timeout.9 page with the state of the > kernel. > > Here is my rewrite (again). > > There are some bits that I want to rework. The opening paragraph is > especially clickety-clackety. The opening paragraph seems fine to me. The second paragraph might be considered a bit awkward. If you rename the struct timeout argument from *to to *timeout in all prototypes in the SYNOPSIS and everywhere in the text, you might be able to join the second and third paragraphs, for example as follows: All state is encapsulated in a .Vt struct timeout allocated by the caller. The .Fn timeout_set function initializes the .Fa timeout before it can be passed to any of the other functions. When the timeout ... That way, you get rid of the word "caller-allocated" and the parenthetic remark, and some of the later text may also simplify all by itself in a natural way. > Still, I think this is an improvement over what's in-tree. And the > technical content should be complete and accurate, which is the most > important thing. > > ok? > > Index: timeout.9 > =================================================================== > RCS file: /cvs/src/share/man/man9/timeout.9,v > retrieving revision 1.55 > diff -u -p -r1.55 timeout.9 > --- timeout.9 22 Jun 2022 14:10:49 -0000 1.55 > +++ timeout.9 31 Dec 2022 16:19:27 -0000 [...] > @@ -44,281 +46,370 @@ [...] > -Once initialized, the > -.Fa to > -structure can be used repeatedly in > -.Fn timeout_add > -and > -.Fn timeout_del > -and does not need to be reinitialized unless > -the function called and/or its argument must change. Are you deleting this information on purpose? [...] > -timeout in at least Are you deleting the words "at least" on purpose, or should they be reinserted into this sentence: KCLOCK_NONE timeouts may be scheduled with the function timeout_add(), which schedules the given timeout to execute after nticks hardclock(9) ticks have elapsed. [...] > +The > .Fn timeout_del_barrier > -is like > -.Fn timeout_del > -but it will wait until any current execution of the timeout has completed. > +function is similar to > +.Fn timeout_del , > +except that it may block until any current execution of the given timeout > +has completed. This appears to change the meaning. The old text provides a guarantee that timeout_del_barrier(9) does not return before the timeout completes, if it is currently running. The new wording no longer provides that guarantee. It that intentional? Otherwise, s/may block/blocks/ ? Or, if you think it should be more explicit, maybe something like: except that, if the timeout is currently executing, .Fn timeout_del blocks until execution of the timeout has completed. [...] > -Otherwise, the system will deadlock. > +Otherwise, > +the system will deadlock. No need to change that. The rule "break the line after a comma" is specific to the Linux man pages project, and i consider it excessive. We only follow "new sentence, new line". Yours, Ingo
