[src/trunk]: src/lib/libpthread Document pthread_attr_setcreatesuspend_np, pt...

[christos <christos%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/fe168125466c
branches:  trunk
changeset: 555226:fe168125466c
user:      christos <christos%NetBSD.org@localhost>
date:      Wed Nov 12 02:44:22 2003 +0000

description:
Document pthread_attr_setcreatesuspend_np, pthread_suspend_np, pthread_resume_np

diffstat:

 lib/libpthread/Makefile                           |    7 +-
 lib/libpthread/pthread_attr_setcreatesuspend_np.3 |   73 +++++++++++++
 lib/libpthread/pthread_suspend_np.3               |  116 ++++++++++++++++++++++
 3 files changed, 193 insertions(+), 3 deletions(-)

diffs (232 lines):

diff -r b8a9917d0f27 -r fe168125466c lib/libpthread/Makefile
--- a/lib/libpthread/Makefile   Wed Nov 12 02:18:27 2003 +0000
+++ b/lib/libpthread/Makefile   Wed Nov 12 02:44:22 2003 +0000
@@ -1,4 +1,4 @@
-#      $NetBSD: Makefile,v 1.22 2003/10/26 07:25:34 lukem Exp $
+#      $NetBSD: Makefile,v 1.23 2003/11/12 02:44:22 christos Exp $
 #
 
 WARNS= 2
@@ -73,7 +73,7 @@
        cp _context_u.o _context_u.po
 
 MAN+=  pthread.3 \
-       pthread_attr.3 \
+       pthread_attr.3 pthread_attr_setcreatesuspend_np.3 \
        pthread_barrier_destroy.3 pthread_barrier_init.3 \
        pthread_barrier_wait.3 pthread_barrierattr.3 \
        pthread_cancel.3 pthread_cleanup_push.3 \
@@ -90,7 +90,7 @@
        pthread_schedparam.3 pthread_self.3 \
        pthread_setspecific.3 pthread_sigmask.3 pthread_spin_destroy.3 \
        pthread_spin_init.3 pthread_spin_lock.3 pthread_spin_unlock.3 \
-       pthread_testcancel.3
+       pthread_suspend_np.3 pthread_testcancel.3
 
 MLINKS+=       pthread_attr.3 pthread_attr_init.3
 MLINKS+=       pthread_attr.3 pthread_attr_destroy.3
@@ -116,6 +116,7 @@
 MLINKS+=       pthread_rwlockattr.3 pthread_rwlockattr_destroy.3
 MLINKS+=       pthread_schedparam.3 pthread_setschedparam.3
 MLINKS+=       pthread_schedparam.3 pthread_getschedparam.3
+MLINKS+=       pthread_suspend_np.3 pthread_resume_np.3
 MLINKS+=       pthread_testcancel.3 pthread_setcancelstate.3
 MLINKS+=       pthread_testcancel.3 pthread_setcanceltype.3
 
diff -r b8a9917d0f27 -r fe168125466c lib/libpthread/pthread_attr_setcreatesuspend_np.3
--- /dev/null   Thu Jan 01 00:00:00 1970 +0000
+++ b/lib/libpthread/pthread_attr_setcreatesuspend_np.3 Wed Nov 12 02:44:22 2003 +0000
@@ -0,0 +1,73 @@
+.\" $NetBSD: pthread_attr_setcreatesuspend_np.3,v 1.1 2003/11/12 02:44:22 christos Exp $
+.\"
+.\"
+.\" Copyright (c) 2003 The NetBSD Foundation, Inc.
+.\" All rights reserved.
+.\"
+.\" This code is derived from software contributed to The NetBSD Foundation
+.\" by Christos Zoulas.
+.\"
+.\" 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.
+.\" 3. All advertising materials mentioning features or use of this software
+.\"    must display the following acknowledgement:
+.\"        This product includes software developed by the NetBSD
+.\"        Foundation, Inc. and its contributors.
+.\" 4. Neither the name of The NetBSD Foundation nor the names of its
+.\"    contributors may be used to endorse or promote products derived
+.\"    from this software without specific prior written permission.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. 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 FOUNDATION 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.
+.\"
+.Dd January 30, 2003
+.Dt PTHREAD_ATTR_SETCREATESUSPEND_NP 3
+.Os
+.Sh NAME
+.Nm pthread_attr_setcreatesuspend_np 
+.Nd Set attribute to create a thread suspended.
+.Sh LIBRARY
+.Lb libpthread
+.Sh SYNOPSIS
+.In pthread.h
+.Ft int
+.Fn pthread_attr_setcreatesuspend_np "pthread_attr_t attr"
+.Sh DESCRIPTION
+The
+.Fn pthread_attr_setcreatesuspend_np
+sets the
+.Ar attr
+argument, so that if this
+.Ar attr
+is used in a
+.Xr pthread_create
+call, then the thread created will not run, but it will remain blocked
+in the suspended queue, until
+.Xr pthread_resume_np
+is called on it.
+.Sh RETURN VALUES
+The
+.Fn pthread_attr_setcreatesuspend_np
+function returns always 0.
+.Sh ERRORS
+.Fn pthread_attr_setcreatesuspend_np
+never fails.
+.Sh SEE ALSO
+.Xr pthread_create 3 ,
+.Xr pthread_resume_np 3 ,
+.Xr pthread_suspend_np 3
diff -r b8a9917d0f27 -r fe168125466c lib/libpthread/pthread_suspend_np.3
--- /dev/null   Thu Jan 01 00:00:00 1970 +0000
+++ b/lib/libpthread/pthread_suspend_np.3       Wed Nov 12 02:44:22 2003 +0000
@@ -0,0 +1,116 @@
+.\" $NetBSD: pthread_suspend_np.3,v 1.1 2003/11/12 02:44:22 christos Exp $
+.\"
+.\"
+.\" Copyright (c) 2003 The NetBSD Foundation, Inc.
+.\" All rights reserved.
+.\"
+.\" This code is derived from software contributed to The NetBSD Foundation
+.\" by Christos Zoulas.
+.\"
+.\" 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.
+.\" 3. All advertising materials mentioning features or use of this software
+.\"    must display the following acknowledgement:
+.\"        This product includes software developed by the NetBSD
+.\"        Foundation, Inc. and its contributors.
+.\" 4. Neither the name of The NetBSD Foundation nor the names of its
+.\"    contributors may be used to endorse or promote products derived
+.\"    from this software without specific prior written permission.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. 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 FOUNDATION 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.
+.\"
+.Dd January 30, 2003
+.Dt PTHREAD_SUSPEND_NP 3
+.Os
+.Sh NAME
+.Nm pthread_suspend_np ,
+.Nm pthread_resume_np
+.Nd Suspend/resume the given thread.
+.Sh LIBRARY
+.Lb libpthread
+.Sh SYNOPSIS
+.In pthread.h
+.Ft int
+.Fn pthread_suspend_np "pthread_t thread"
+.Ft int
+.Fn pthread_resume_np "pthread_t thread"
+.Sh DESCRIPTION
+The
+.Fn pthread_suspend_np
+function suspends the 
+.Ar thread
+given as argument.
+If
+.Ar thread
+is the current running thread
+as returned by
+.Xr thread_self 3 ,
+the function fails and returns
+.Er EDEADLK .
+Otherwise, it removes the named thread from the running queue, and adds it
+to the suspended queue.
+The
+.Ar thread
+will remain blocked until
+.Fn pthread_resume_np
+is called on it.
+.Pp
+.Fn pthread_resume_np
+resumes the 
+.Ar thread
+given as argument, if it was suspended.
+.Sh RETURN VALUES
+The
+.Fn pthread_suspend_np
+function returns 0 on success and an error number indicating the reason
+for the failure.
+The
+.Fn pthread_resume_np
+always returns 0.
+.Sh ERRORS
+.Fn pthread_suspend_np
+shall fail if:
+.Bl -tag -width Er
+.It Bq Er EDEADLK
+The thread requested to suspend was the current running thread.
+.El
+.Pp
+.Fn pthread_resume_np
+never fails.
+.Sh NOTES
+Some
+.Fn pthread_suspend_np
+implementations may allow suspending the current thread.
+This is dangerous, because the semantics of the function would then require
+the scheduler to schedule another thread, causing a thread context switch.
+Since that context switch can happen in a signal handler by someone calling
+.Fn pthread_suspend_np
+in a signal handler, this is currently not allowed.
+.Pp
+In
+.Fn pthread_resume_np
+we don't check if the 
+.Ar thread
+argument is not already suspended. Some implementations might return an
+error condition if
+.Fn pthread_resume_np
+is called on a non-suspended thread.
+.Sh SEE ALSO
+.Xr pthread_attr_setcreatesuspend_np 3 ,
+.Xr pthread_self 3