Index: lib/libc/sys/Makefile.inc =================================================================== --- lib/libc/sys/Makefile.inc +++ lib/libc/sys/Makefile.inc @@ -322,6 +322,8 @@ thr_new.2 \ thr_self.2 \ thr_set_name.2 \ + thr_suspend.2 \ + thr_wake.2 \ timer_create.2 \ timer_delete.2 \ timer_settime.2 \ Index: lib/libc/sys/thr_suspend.2 =================================================================== --- /dev/null +++ lib/libc/sys/thr_suspend.2 @@ -0,0 +1,126 @@ +.\" Copyright (c) 2016 The FreeBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This documentation was written by +.\" Konstantin Belousov 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 call +.Xr pthread_suspend_np 3 +instead. +.Ef +.Pp +The +.Fn thr_suspend +system call puts the calling thread in suspended state, where it does +not consume CPU time. +The state is terminated with the other thread calling +.Xr thr_wake 2 , +by elapsion of the timeout specified in the +.Fa timeout +argument, +or by a signal delivered to the suspended thread. +.Pp +If the +.Fa timeout +argument is +.Dv NULL , +the suspended state can be only terminated by wake or signal. +.Pp +If the wake by +.Xr thr_wake 2 +was delivered before the +.Nm +call, the thread is not put into suspended state, instead the call +returns immediately without an error. +.Pp +If the thread called +.Xr thr_wake 2 +with its thread identifier, which resulted in setting the internal kernel +flag to immediately abort interruptible sleeps with +.Er EINTR +error (see +.Xr thr_wake 2 ), +the flag is cleared. +Same as with +.Xr thr_wake 2 +called from other thread, next +.Nm +call does not result in suspension. +.Pp +.Sh RETURN VALUES +If successful, +.Fn thr_suspend +will return zero, otherwise \-1 is returned, and +.Va errno +is set to indicate the error. +.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 was elapsed. +.It Bq Er ETIMEDOUT +The +.Fa timeout +argument specified 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 and is used by the +.Lb libthr +to implement +.St -p1003.1-2001 +.Xr pthread 3 +functionality. Index: lib/libc/sys/thr_wake.2 =================================================================== --- /dev/null +++ lib/libc/sys/thr_wake.2 @@ -0,0 +1,104 @@ +.\" Copyright (c) 2016 The FreeBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This documentation was written by +.\" Konstantin Belousov 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 call +.Xr pthread_resume_np 3 +instead. +.Ef +.Pp +The +.Fn thr_wake +system call, if passed the thread identifier of the executing thread (see +.Xr thr_self 2 ), +sets a threads flag which causes next sleep in kernel, +interruptible by signal, fail immediately with the error +.Er EINTR. +The flag is cleared by the 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 the argument +.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 +.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 +If successful, +.Fn thr_wake +will return zero, otherwise \-1 is returned, and +.Va errno +is set to indicate the error. +.Sh ERRORS +The +.Fn thr_wake +operation returns the following errors: +.Bl -tag -width Er +.It Bq Er ESRCH +The specified thread was not found. +.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 the +.Lb libthr +to implement +.St -p1003.1-2001 +.Xr pthread 3 +functionality.