Date: Sun, 16 May 2010 11:03:46 +0000 (UTC) From: Jilles Tjoelker <jilles@FreeBSD.org> To: src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-stable@freebsd.org, svn-src-stable-8@freebsd.org Subject: svn commit: r208138 - stable/8/share/man/man3 Message-ID: <201005161103.o4GB3k2N081392@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
Author: jilles Date: Sun May 16 11:03:46 2010 New Revision: 208138 URL: http://svn.freebsd.org/changeset/base/208138 Log: 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. Modified: stable/8/share/man/man3/Makefile stable/8/share/man/man3/pthread_cond_timedwait.3 stable/8/share/man/man3/pthread_condattr.3 Directory Properties: stable/8/share/man/man3/ (props changed) Modified: stable/8/share/man/man3/Makefile ============================================================================== --- stable/8/share/man/man3/Makefile Sun May 16 10:51:45 2010 (r208137) +++ stable/8/share/man/man3/Makefile Sun May 16 11:03:46 2010 (r208138) @@ -251,7 +251,11 @@ PTHREAD_MLINKS+=pthread_barrierattr.3 pt 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 \ Modified: stable/8/share/man/man3/pthread_cond_timedwait.3 ============================================================================== --- stable/8/share/man/man3/pthread_cond_timedwait.3 Sun May 16 10:51:45 2010 (r208137) +++ stable/8/share/man/man3/pthread_cond_timedwait.3 Sun May 16 11:03:46 2010 (r208138) @@ -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 Modified: stable/8/share/man/man3/pthread_condattr.3 ============================================================================== --- stable/8/share/man/man3/pthread_condattr.3 Sun May 16 10:51:45 2010 (r208137) +++ stable/8/share/man/man3/pthread_condattr.3 Sun May 16 11:03:46 2010 (r208138) @@ -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 attribu 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 .
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201005161103.o4GB3k2N081392>