diff options
author | kib <kib@FreeBSD.org> | 2016-10-03 09:32:19 +0000 |
---|---|---|
committer | kib <kib@FreeBSD.org> | 2016-10-03 09:32:19 +0000 |
commit | dd5fc4845766bea393df46fa13bcdbb3969c4013 (patch) | |
tree | 8804f08898f1f4d912bc72ad1d72f969de04788c /lib/libc/sys | |
parent | 64a81b945552ab8c3f03c60e1b48bb3974727ca4 (diff) | |
download | FreeBSD-src-dd5fc4845766bea393df46fa13bcdbb3969c4013.zip FreeBSD-src-dd5fc4845766bea393df46fa13bcdbb3969c4013.tar.gz |
MFC r306334:
Document thr_suspend(2) and thr_wake(2).
MFC r306506:
Reword the statement.
Diffstat (limited to 'lib/libc/sys')
-rw-r--r-- | lib/libc/sys/Makefile.inc | 2 | ||||
-rw-r--r-- | lib/libc/sys/thr_suspend.2 | 130 | ||||
-rw-r--r-- | lib/libc/sys/thr_wake.2 | 112 |
3 files changed, 244 insertions, 0 deletions
diff --git a/lib/libc/sys/Makefile.inc b/lib/libc/sys/Makefile.inc index cb5575c..e4c89d0 100644 --- a/lib/libc/sys/Makefile.inc +++ b/lib/libc/sys/Makefile.inc @@ -316,6 +316,8 @@ MAN+= sctp_generic_recvmsg.2 \ sync.2 \ sysarch.2 \ syscall.2 \ + thr_suspend.2 \ + thr_wake.2 \ timer_create.2 \ timer_delete.2 \ timer_settime.2 \ diff --git a/lib/libc/sys/thr_suspend.2 b/lib/libc/sys/thr_suspend.2 new file mode 100644 index 0000000..b470d18 --- /dev/null +++ b/lib/libc/sys/thr_suspend.2 @@ -0,0 +1,130 @@ +.\" Copyright (c) 2016 The FreeBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This documentation was written by +.\" Konstantin Belousov <kib@FreeBSD.org> under sponsorship +.\" from the FreeBSD Foundation. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd September 23, 2016 +.Dt THR_SUSPEND 2 +.Os +.Sh NAME +.Nm thr_suspend +.Nd suspend the calling thread +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/thr.h +.Ft int +.Fn thr_suspend "struct timespec *timeout" +.Sh DESCRIPTION +.Bf -symbolic +This function is intended for implementing threading. +Normal applications should use +.Xr pthread_cond_timedwait 3 +together with +.Xr pthread_cond_broadcast 3 +for typical safe suspension with cooperation of the thread +being suspended, or +.Xr pthread_suspend_np 3 +and +.Xr pthread_resume_np 3 +in some specific situations, instead. +.Ef +.Pp +The +.Fn thr_suspend +system call puts the calling thread in a suspended state, where it is +not eligible for CPU time. +This state is exited by another thread calling +.Xr thr_wake 2 , +when the time interval specified by +.Fa timeout +has elapsed, +or by the delivery of a signal to the suspended thread. +.Pp +If the +.Fa timeout +argument is +.Dv NULL , +the suspended state can be only terminated by explicit +.Fn thr_wake +or signal. +.Pp +If a wake from +.Xr thr_wake 2 +was delivered before the +.Nm +call, the thread is not put into a suspended state. +Instead, the call +returns immediately without an error. +.Pp +If a thread previously called +.Xr thr_wake 2 +with its own thread identifier, which resulted in setting the internal kernel +flag to immediately abort interruptible sleeps with an +.Er EINTR +error +.Po +see +.Xr thr_wake 2 +.Pc , +the flag is cleared. +As with +.Xr thr_wake 2 +called from another thread, the next +.Nm +call does not result in suspension. +.Pp +.Sh RETURN VALUES +.Rv -std thr_suspend +.Sh ERRORS +The +.Fn thr_suspend +operation returns the following errors: +.Bl -tag -width Er +.It Bq Er EFAULT +The memory pointed to by the +.Fa timeout +argument is not valid. +.It Bq Er ETIMEDOUT +The specified timeout expired. +.It Bq Er ETIMEDOUT +The +.Fa timeout +argument specified a zero time interval. +.It Bq Er EINTR +The sleep was interrupted by a signal. +.El +.Sh SEE ALSO +.Xr ps 1 , +.Xr thr_wake 2 , +.Xr pthread_resume_np 3 , +.Xr pthread_suspend_np 3 +.Sh STANDARDS +The +.Fn thr_suspend +system call is non-standard. diff --git a/lib/libc/sys/thr_wake.2 b/lib/libc/sys/thr_wake.2 new file mode 100644 index 0000000..59df7d2 --- /dev/null +++ b/lib/libc/sys/thr_wake.2 @@ -0,0 +1,112 @@ +.\" Copyright (c) 2016 The FreeBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This documentation was written by +.\" Konstantin Belousov <kib@FreeBSD.org> under sponsorship +.\" from the FreeBSD Foundation. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd September 23, 2016 +.Dt THR_WAKE 2 +.Os +.Sh NAME +.Nm thr_wake +.Nd wake up the suspended thread +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/thr.h +.Ft int +.Fn thr_wake "long id" +.Sh DESCRIPTION +.Bf -symbolic +This function is intended for implementing threading. +Normal applications should use +.Xr pthread_cond_timedwait 3 +together with +.Xr pthread_cond_broadcast 3 +for typical safe suspension with cooperation of the thread +being suspended, or +.Xr pthread_suspend_np 3 +and +.Xr pthread_resume_np 3 +in some specific situations, instead. +.Ef +.Pp +Passing the thread identifier of the calling thread +.Po +see +.Xr thr_self 2 +.Pc +to +.Fn thr_wake +sets a thread's flag to cause the next signal-interruptible sleep +of that thread in the kernel to fail immediately with the +.Er EINTR +error. +The flag is cleared by an interruptible sleep attempt or by a call to +.Xr thr_suspend 2. +This is used by the system threading library to implement cancellation. +.Pp +If +.Fa id +is not equal to the current thread identifier, the specified thread is +woken up if suspended by the +.Xr thr_suspend +system call. +If the thread is not suspended at the time of the +.Nm +call, the wake is remembered and the next attempt of the thread to +suspend itself with the +.Xr thr_suspend 2 +results in immediate return with success. +Only one wake is remembered. +.Sh RETURN VALUES +.Rv -std thr_wake +.Sh ERRORS +The +.Fn thr_wake +operation returns these errors: +.Bl -tag -width Er +.It Bq Er ESRCH +The specified thread was not found or does not belong to the process +of the calling thread. +.El +.Sh SEE ALSO +.Xr ps 1 , +.Xr thr_self 2 +.Xr thr_suspend 2 , +.Xr pthread_cancel 3 , +.Xr pthread_resume_np 3 , +.Xr pthread_suspend_np 3 +.Sh STANDARDS +The +.Fn thr_suspend +system call is non-standard and is used by +.Lb libthr +to implement +.St -p1003.1-2001 +.Xr pthread 3 +functionality. |