From: Ingo Schwarze Subject: Re: pthread man.3 inode conservation To: Ted Unangst Cc: tech@openbsd.org Date: Thu, 3 Jul 2025 00:08:05 +0200 Hello Ted, Ted Unangst wrote on Wed, Jul 02, 2025 at 03:07:36PM -0400: > On 2025-06-21, Ingo Schwarze wrote: >> Ted Unangst proposed some teduing: >>> This diff more or less mechanically combines the pages. I think a >>> bit more narrative structure can be added, but at least you can get >>> some idea of what these functions are for and how they work together >>> in a single page now. >> My in-line remarks are suggestions, not conditions for going ahead. > Mostly incorporated. Thanks. > I changed a few words here and there for clarity and brevity. Very good, OK schwarze@ if you fix the three typos noted inline below. Thanks for doing this! :-) Ingo > Index: Makefile.inc > =================================================================== > RCS file: /home/cvs/src/lib/libpthread/man/Makefile.inc,v > diff -u -p -r1.37 Makefile.inc > --- Makefile.inc 12 Jan 2019 00:16:03 -0000 1.37 > +++ Makefile.inc 2 Jul 2025 18:30:21 -0000 > @@ -20,12 +20,7 @@ MAN+= \ > pthread_cleanup_pop.3 \ > pthread_cleanup_push.3 \ > pthread_condattr_init.3 \ > - pthread_cond_broadcast.3 \ > - pthread_cond_destroy.3 \ > pthread_cond_init.3 \ > - pthread_cond_signal.3 \ > - pthread_cond_timedwait.3 \ > - pthread_cond_wait.3 \ > pthread_cancel.3 \ > pthread_create.3 \ > pthread_detach.3 \ > Index: pthread_cond_init.3 > =================================================================== > RCS file: /home/cvs/src/lib/libpthread/man/pthread_cond_init.3,v > diff -u -p -r1.13 pthread_cond_init.3 > --- pthread_cond_init.3 7 Jun 2025 00:16:52 -0000 1.13 > +++ pthread_cond_init.3 2 Jul 2025 19:02:40 -0000 > @@ -28,37 +28,104 @@ > .\" SUCH DAMAGE. > .\" > .\" $FreeBSD: pthread_cond_init.3,v 1.6 1999/08/28 00:03:03 peter Exp $ > +.\" $FreeBSD: pthread_cond_destroy.3,v 1.5 1999/08/28 00:03:03 peter Exp $ > +.\" $FreeBSD: pthread_cond_wait.3,v 1.6 1999/08/28 00:03:04 peter Exp $ > +.\" $FreeBSD: pthread_cond_timedwait.3,v 1.6 1999/08/28 00:03:04 peter Exp $ > +.\" $FreeBSD: pthread_cond_broadcast.3,v 1.5 1999/08/28 00:03:03 peter Exp $ > +.\" $FreeBSD: pthread_cond_signal.3,v 1.5 1999/08/28 00:03:04 peter Exp $ > .\" > .Dd $Mdocdate: June 7 2025 $ > .Dt PTHREAD_COND_INIT 3 > .Os > .Sh NAME > -.Nm pthread_cond_init > -.Nd create a condition variable > +.Nm pthread_cond_init , > +.Nm pthread_cond_destroy , > +.Nm pthread_cond_wait , > +.Nm pthread_cond_timedwait , > +.Nm pthread_cond_broadcast , > +.Nm pthread_cond_signal > +.Nd block and unblock threads with condition variables > .Sh SYNOPSIS > .Lb libpthread > .In pthread.h > .Ft int > -.Fn pthread_cond_init "pthread_cond_t *cond" "const pthread_condattr_t *attr" > +.Fo pthread_cond_init > +.Fa "pthread_cond_t *cond" > +.Fa "const pthread_condattr_t *attr" > +.Fc > +.Ft int > +.Fo pthread_cond_destroy > +.Fa "pthread_cond_t *cond" > +.Fc > +.Ft int > +.Fo pthread_cond_wait > +.Fa "pthread_cond_t *cond" > +.Fa "pthread_mutex_t *mutex" > +.Fc > +.Ft int > +.Fo pthread_cond_timedwait > +.Fa "pthread_cond_t *cond" > +.Fa "pthread_mutex_t *mutex" > +.Fa "const struct timespec *abstime" > +.Fc > +.Ft int > +.Fo pthread_cond_broadcast > +.Fa "pthread_cond_t *cond" > +.Fc > +.Ft int > +.Fo pthread_cond_signal > +.Fa "pthread_cond_t *cond" > +.Fc > .Sh DESCRIPTION > The > .Fn pthread_cond_init > -function creates a new condition variable, with attributes specified with > +function creates a new condition variable with attributes specified by > .Fa attr . > If > .Fa attr > is > .Dv NULL , > the default attributes are used. > -.Sh RETURN VALUES > -If successful, the > -.Fn pthread_cond_init > -function will return zero and put the new condition variable ID into > +.Pp > +The > +.Fn pthread_cond_destroy > +function frees the resources associated with the condition variable > +.Fa cond . > +.Pp > +The > +.Fn pthread_cond_wait > +function atomically blocks the current thread by waiting on the condition > +variable > .Fa cond , > -otherwise an error number will be returned to indicate the error. > +and unlocks the mutex specified by > +.Fa mutex . > +The waiting thread unblocks only after another thread calls > +.Fn pthread_cond_broadcast > +or > +.Fn pthread_cond_signal > +with the same condition variable. > +The > +.Fn pthread_cond_timedwait > +function does the same, but returns after the system time reaches > +.Fa abstime . > +In all cases, both functions then reacquire the lock on > +.Fa mutex > +before returning. > +.Pp > +The > +.Fn pthread_cond_broadcast > +function unblocks all threads waiting for the condition variable > +.Fa cond . > +The > +.Fn pthread_cond_signal > +function unblocks at least one thread waiting for the condition variable > +.Fa cond . > +.Sh RETURN VALUES > +These functions return zero for success and positive error numbers > +for failure. > .Sh ERRORS > .Fn pthread_cond_init > -will fail if: > +fails if: > .Bl -tag -width Er > .It Bq Er EINVAL > The value specified by > @@ -71,13 +138,37 @@ variable. > The system temporarily lacks the resources to create another condition > variable. > .El > +.Pp > +The other functions fail if: > +.Bl -tag -width Er > +.It Bq Er EINVAL > +The value specified by > +.Fa cond , > +.Fa mutex , > +or > +.Fa abstime > +is invalid. > +.Pp > +.El You have to change to order of macros here: .El .Pp > +.Fn pthread_cond_destory s/destory/destroy/ > +additionally fails if: > +.Bl -tag -width Er > +.It Bq Er EBUSY > +The variable > +.Fa cond > +is locked by another thread. > +.Pp > +.El Again: .El .Pp > +.Fn pthread_cond_timedwait > +additionally fails if: > +.Bl -tag -width Er > +.It Bq Er ETIMEDOUT > +The system time has reached or exceeded the time specified in > +.Fa abstime . > +.El > .Sh SEE ALSO > -.Xr pthread_cond_broadcast 3 , > -.Xr pthread_cond_destroy 3 , > -.Xr pthread_cond_signal 3 , > -.Xr pthread_cond_timedwait 3 , > -.Xr pthread_cond_wait 3 > +.Xr pthread_condattr_init 3 , > +.Xr pthread_mutex_init 3 > .Sh STANDARDS > -.Fn pthread_cond_init > -conforms to > +These functions conform to > .St -p1003.1-96 . > Index: pthreads.3 > =================================================================== > RCS file: /home/cvs/src/lib/libpthread/man/pthreads.3,v > diff -u -p -r1.45 pthreads.3 > --- pthreads.3 21 Jun 2025 08:10:02 -0000 1.45 > +++ pthreads.3 2 Jul 2025 19:03:54 -0000 > @@ -412,12 +412,7 @@ with larger numbers generating more verb > .Xr pthread_cancel 3 , > .Xr pthread_cleanup_pop 3 , > .Xr pthread_cleanup_push 3 , > -.Xr pthread_cond_broadcast 3 , > -.Xr pthread_cond_destroy 3 , > .Xr pthread_cond_init 3 , > -.Xr pthread_cond_signal 3 , > -.Xr pthread_cond_timedwait 3 , > -.Xr pthread_cond_wait 3 , > .Xr pthread_condattr_init 3 , > .Xr pthread_create 3 , > .Xr pthread_detach 3 ,