From 9a0e8f8e952238e61ceecf46c2c47cb8f0bf4326 Mon Sep 17 00:00:00 2001 From: jilles Date: Sun, 16 May 2010 11:03:46 +0000 Subject: MFC r207816: Document clock and pshared condvar attributes. Note: clock accepts CLOCK_VIRTUAL and CLOCK_PROF too, but this seems broken as it simply waits for the difference of the current and given value of the clock as if it were CLOCK_MONOTONIC. So document only CLOCK_REALTIME and CLOCK_MONOTONIC as allowed. --- share/man/man3/Makefile | 6 +- share/man/man3/pthread_cond_timedwait.3 | 10 +++- share/man/man3/pthread_condattr.3 | 102 +++++++++++++++++++++++++++++--- 3 files changed, 107 insertions(+), 11 deletions(-) diff --git a/share/man/man3/Makefile b/share/man/man3/Makefile index ad176aa..9e536a0 100644 --- a/share/man/man3/Makefile +++ b/share/man/man3/Makefile @@ -251,7 +251,11 @@ PTHREAD_MLINKS+=pthread_barrierattr.3 pthread_barrierattr_destroy.3 \ PTHREAD_MLINKS+=pthread_barrier_destroy.3 pthread_barrier_init.3 \ pthread_barrier_destroy.3 pthread_barrier_wait.3 PTHREAD_MLINKS+=pthread_condattr.3 pthread_condattr_destroy.3 \ - pthread_condattr.3 pthread_condattr_init.3 + pthread_condattr.3 pthread_condattr_init.3 \ + pthread_condattr.3 pthread_condattr_getclock.3 \ + pthread_condattr.3 pthread_condattr_setclock.3 \ + pthread_condattr.3 pthread_condattr_getpshared.3 \ + pthread_condattr.3 pthread_condattr_setpshared.3 PTHREAD_MLINKS+=pthread_getconcurrency.3 pthread_setconcurrency.3 PTHREAD_MLINKS+=pthread_multi_np.3 pthread_single_np.3 PTHREAD_MLINKS+=pthread_mutexattr.3 pthread_mutexattr_destroy.3 \ diff --git a/share/man/man3/pthread_cond_timedwait.3 b/share/man/man3/pthread_cond_timedwait.3 index 0162569..11a3c2f 100644 --- a/share/man/man3/pthread_cond_timedwait.3 +++ b/share/man/man3/pthread_cond_timedwait.3 @@ -27,7 +27,7 @@ .\" .\" $FreeBSD$ .\" -.Dd July 28, 1998 +.Dd May 9, 2010 .Dt PTHREAD_COND_TIMEDWAIT 3 .Os .Sh NAME @@ -56,6 +56,11 @@ time specified in .Fa abstime , and the current thread reacquires the lock on .Fa mutex . +.Pp +The clock used to measure +.Fa abstime +can be specified during creation of the condition variable using +.Xr pthread_condattr_setclock 3 . .Sh RETURN VALUES If successful, the .Fn pthread_cond_timedwait @@ -87,7 +92,8 @@ was not locked by the calling thread. .Xr pthread_cond_destroy 3 , .Xr pthread_cond_init 3 , .Xr pthread_cond_signal 3 , -.Xr pthread_cond_wait 3 +.Xr pthread_cond_wait 3 , +.Xr pthread_condattr_setclock 3 .Sh STANDARDS The .Fn pthread_cond_timedwait diff --git a/share/man/man3/pthread_condattr.3 b/share/man/man3/pthread_condattr.3 index bf28987..e232ef6 100644 --- a/share/man/man3/pthread_condattr.3 +++ b/share/man/man3/pthread_condattr.3 @@ -26,12 +26,16 @@ .\" EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .\" .\" $FreeBSD$ -.Dd April 28, 2000 +.Dd May 9, 2010 .Dt PTHREAD_CONDATTR 3 .Os .Sh NAME .Nm pthread_condattr_init , -.Nm pthread_condattr_destroy +.Nm pthread_condattr_destroy , +.Nm pthread_condattr_getclock , +.Nm pthread_condattr_setclock , +.Nm pthread_condattr_getpshared , +.Nm pthread_condattr_setpshared , .Nd condition attribute operations .Sh LIBRARY .Lb libpthread @@ -41,14 +45,17 @@ .Fn pthread_condattr_init "pthread_condattr_t *attr" .Ft int .Fn pthread_condattr_destroy "pthread_condattr_t *attr" +.Ft int +.Fn pthread_condattr_getclock "pthread_condattr_t * restrict attr" "clock_t * restrict clock_id" +.Ft int +.Fn pthread_condattr_setclock "pthread_condattr_t *attr" "clock_t clock_id" +.Ft int +.Fn pthread_condattr_getpshared "pthread_condattr_t * restrict attr" "int * restrict pshared" +.Ft int +.Fn pthread_condattr_setpshared "pthread_condattr_t *attr" "int pshared" .Sh DESCRIPTION Condition attribute objects are used to specify parameters to .Fn pthread_cond_init . -.Fx Ns 's -implementation of conditions does not support any non-default -attributes, so these functions are not very useful, though they are required -to be present by -.Tn POSIX . .Pp The .Fn pthread_condattr_init @@ -57,6 +64,52 @@ function initializes a condition attribute object with the default attributes. The .Fn pthread_condattr_destroy function destroys a condition attribute object. +.Pp +The +.Fn pthread_condattr_getclock +function will put the value of the clock attribute from +.Fa attr +into the memory area pointed to by +.Fa clock_id . +The +.Fn pthread_condattr_setclock +function will set the clock attribute of +.Fa attr +to the value specified in +.Fa clock_id . +The clock attribute affects the interpretation of +.Fa abstime +in +.Xr pthread_cond_timedwait 3 +and may be set to +.Dv CLOCK_REALTIME +(default) +or +.Dv CLOCK_MONOTONIC . +.Pp +The +.Fn pthread_condattr_getpshared +function will put the value of the process-shared attribute from +.Fa attr +into the memory area pointed to by +.Fa pshared . +The +.Fn pthread_condattr_setpshared +function will set the process-shared attribute of +.Fa attr +to the value specified in +.Fa pshared . +The argument +.Fa pshared +may have one of the following values: +.Bl -tag -width ".Dv PTHREAD_PROCESS_PRIVATE" +.It Dv PTHREAD_PROCESS_PRIVATE +The condition variable it is attached to may only be accessed by +threads in the same process as the one that created the object. +.It Dv PTHREAD_PROCESS_SHARED +The condition variable it is attached to may be accessed by +threads in processes other than the one that created the object. +.El .Sh RETURN VALUES If successful, these functions return 0. Otherwise, an error number is returned to indicate the error. @@ -77,8 +130,29 @@ function will fail if: Invalid value for .Fa attr . .El +.Pp +The +.Fn pthread_condattr_setclock +function will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The value specified in +.Fa clock_id +is not one of the allowed values. +.El +.Pp +The +.Fn pthread_condattr_setpshared +function will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The value specified in +.Fa pshared +is not one of the allowed values. +.El .Sh SEE ALSO -.Xr pthread_cond_init 3 +.Xr pthread_cond_init 3 , +.Xr pthread_cond_timedwait 3 .Sh STANDARDS The .Fn pthread_condattr_init @@ -86,3 +160,15 @@ and .Fn pthread_condattr_destroy functions conform to .St -p1003.1-96 +.Sh BUGS +The implementation of +condition variables +does not fully conform to +.St -p1003.2 +because the process-shared attribute is ignored; +if any value other than +.Dv PTHREAD_PROCESSES_PRIVATE +is specified in a call to +.Fn pthread_condattr_setpshared , +it will return +.Er EINVAL . -- cgit v1.1