Re: ualarm.3: cleanup, rewrites
On Sun, 30 Jul 2023 20:20:31 -0500, Scott Cheloha wrote: > This patch drags ualarm.3 over to where alarm.3 is. I think it reads > better and the wording is truer to what the function actually does. > In particular, ualarm(3) does not block or "wait": the alarm is > scheduled for asynchronous delivery by the operating system. > > I think I may have tried to clean this up two years ago. I don't > remember where that got sidetracked, but fwiw this was written from > scratch using alarm.3 as a guide. > > Two things I'm iffy on: > > - "high resolution" or "high-resolution"? nanosleep(2) uses "high resolution" so I think we should be consistent with that. > - The current manual mentions an upper bound (2147483647). I'm not > sure when, if ever, this was the real: useconds_t is unsigned, so an > upper bound of INT32_MAX seems off. This may have been copy pasta from alarm.3 which used to document the same limit (which was actually incorrect at the time due to itimerfix). > I am leaning toward just leaving the patch as-is instead of trying > to guide the end-user through the minefield of matching bespoke > "_t" types to real types and limits. > > Tweaks? ok? OK millert@ - todd
Re: ualarm.3: cleanup, rewrites
On Sun, Jul 30, 2023 at 08:20:31PM -0500, Scott Cheloha wrote: > This patch drags ualarm.3 over to where alarm.3 is. I think it reads > better and the wording is truer to what the function actually does. > In particular, ualarm(3) does not block or "wait": the alarm is > scheduled for asynchronous delivery by the operating system. > > I think I may have tried to clean this up two years ago. I don't > remember where that got sidetracked, but fwiw this was written from > scratch using alarm.3 as a guide. > > Two things I'm iffy on: > > - "high resolution" or "high-resolution"? > > - The current manual mentions an upper bound (2147483647). I'm not > sure when, if ever, this was the real: useconds_t is unsigned, so an > upper bound of INT32_MAX seems off. > > I am leaning toward just leaving the patch as-is instead of trying > to guide the end-user through the minefield of matching bespoke > "_t" types to real types and limits. > > Tweaks? ok? > hi. fine by me. i would stick with "high resolution", purely because we seem to have no other instances of "high-resolution". jmc > Index: ualarm.3 > === > RCS file: /cvs/src/lib/libc/gen/ualarm.3,v > retrieving revision 1.17 > diff -u -p -r1.17 ualarm.3 > --- ualarm.3 26 Jul 2019 12:08:18 - 1.17 > +++ ualarm.3 31 Jul 2023 01:05:23 - > @@ -32,7 +32,7 @@ > .Os > .Sh NAME > .Nm ualarm > -.Nd schedule signal after specified time > +.Nd schedule high resolution SIGALRM delivery > .Sh SYNOPSIS > .In unistd.h > .Ft useconds_t > @@ -45,31 +45,37 @@ This is a simplified interface to > .Pp > The > .Fn ualarm > -function waits a count of > +function schedules the > +.Dv SIGALRM > +signal for delivery to the calling process after at least the given number of > .Fa microseconds > -before asserting the terminating signal > -.Dv SIGALRM . > -System activity or time used in processing the call may cause a slight > -delay. > -.Pp > -If the > +have elapsed. > +If > .Fa interval > -argument is non-zero, the > +is non-zero, > +the > .Dv SIGALRM > -signal will be sent > -to the process every > +signal is scheduled for redelivery to the calling process every > .Fa interval > -microseconds after the timer expires (e.g., after > +microseconds thereafter. > +.Pp > +If an alarm is already pending, > +an additional call to > +.Fn ualarm > +supersedes the prior call. > +.Pp > +If > .Fa microseconds > -number of microseconds have passed). > +is zero, > +any pending alarm is cancelled and the value of > +.Fa interval > +is ignored. > .Sh RETURN VALUES > -When the signal has successfully been caught, > +The > .Fn ualarm > -returns the amount of time left on the clock. > -The maximum value for > -.Fa microseconds > -allowed > -is 2147483647. > +function returns the number of microseconds remaining until the next > +alarm is scheduled for delivery, > +or zero if no alarm is pending. > .Sh SEE ALSO > .Xr setitimer 2 , > .Xr sigaction 2 , > @@ -86,5 +92,17 @@ function conforms to > .Sh HISTORY > The > .Fn ualarm > -function appeared in > +function first appeared in > .Bx 4.3 . > +.Sh CAVEATS > +The > +.Fn ualarm > +function is implemented with the per-process > +.Dv ITIMER_REAL > +timer described in > +.Xr setitimer 2 . > +Use of both > +.Fn ualarm > +and > +.Xr setitimer 2 > +in the same program may yield confusing behavior.
ualarm.3: cleanup, rewrites
This patch drags ualarm.3 over to where alarm.3 is. I think it reads better and the wording is truer to what the function actually does. In particular, ualarm(3) does not block or "wait": the alarm is scheduled for asynchronous delivery by the operating system. I think I may have tried to clean this up two years ago. I don't remember where that got sidetracked, but fwiw this was written from scratch using alarm.3 as a guide. Two things I'm iffy on: - "high resolution" or "high-resolution"? - The current manual mentions an upper bound (2147483647). I'm not sure when, if ever, this was the real: useconds_t is unsigned, so an upper bound of INT32_MAX seems off. I am leaning toward just leaving the patch as-is instead of trying to guide the end-user through the minefield of matching bespoke "_t" types to real types and limits. Tweaks? ok? Index: ualarm.3 === RCS file: /cvs/src/lib/libc/gen/ualarm.3,v retrieving revision 1.17 diff -u -p -r1.17 ualarm.3 --- ualarm.326 Jul 2019 12:08:18 - 1.17 +++ ualarm.331 Jul 2023 01:05:23 - @@ -32,7 +32,7 @@ .Os .Sh NAME .Nm ualarm -.Nd schedule signal after specified time +.Nd schedule high resolution SIGALRM delivery .Sh SYNOPSIS .In unistd.h .Ft useconds_t @@ -45,31 +45,37 @@ This is a simplified interface to .Pp The .Fn ualarm -function waits a count of +function schedules the +.Dv SIGALRM +signal for delivery to the calling process after at least the given number of .Fa microseconds -before asserting the terminating signal -.Dv SIGALRM . -System activity or time used in processing the call may cause a slight -delay. -.Pp -If the +have elapsed. +If .Fa interval -argument is non-zero, the +is non-zero, +the .Dv SIGALRM -signal will be sent -to the process every +signal is scheduled for redelivery to the calling process every .Fa interval -microseconds after the timer expires (e.g., after +microseconds thereafter. +.Pp +If an alarm is already pending, +an additional call to +.Fn ualarm +supersedes the prior call. +.Pp +If .Fa microseconds -number of microseconds have passed). +is zero, +any pending alarm is cancelled and the value of +.Fa interval +is ignored. .Sh RETURN VALUES -When the signal has successfully been caught, +The .Fn ualarm -returns the amount of time left on the clock. -The maximum value for -.Fa microseconds -allowed -is 2147483647. +function returns the number of microseconds remaining until the next +alarm is scheduled for delivery, +or zero if no alarm is pending. .Sh SEE ALSO .Xr setitimer 2 , .Xr sigaction 2 , @@ -86,5 +92,17 @@ function conforms to .Sh HISTORY The .Fn ualarm -function appeared in +function first appeared in .Bx 4.3 . +.Sh CAVEATS +The +.Fn ualarm +function is implemented with the per-process +.Dv ITIMER_REAL +timer described in +.Xr setitimer 2 . +Use of both +.Fn ualarm +and +.Xr setitimer 2 +in the same program may yield confusing behavior.
