[src/trunk]: src/lib/librt Flesh out sched_protect

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

details:   https://anonhg.NetBSD.org/src/rev/6cf8f316e60e
branches:  trunk
changeset: 816962:6cf8f316e60e
user:      christos <christos%NetBSD.org@localhost>
date:      Thu Aug 04 07:09:15 2016 +0000

description:
Flesh out sched_protect

diffstat:

 lib/librt/sched.3 |  45 +++++++++++++++++++++++++++++++++++++++++----
 1 files changed, 41 insertions(+), 4 deletions(-)

diffs (76 lines):

diff -r 2422002aeb0b -r 6cf8f316e60e lib/librt/sched.3
--- a/lib/librt/sched.3 Thu Aug 04 07:06:14 2016 +0000
+++ b/lib/librt/sched.3 Thu Aug 04 07:09:15 2016 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: sched.3,v 1.14 2016/07/06 15:55:02 wiz Exp $
+.\"    $NetBSD: sched.3,v 1.15 2016/08/04 07:09:15 christos Exp $
 .\"
 .\" Copyright (c) 2008 The NetBSD Foundation, Inc.
 .\" All rights reserved.
@@ -27,7 +27,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 .\" POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd July 5, 2016
+.Dd August 4, 2016
 .Dt SCHED 3
 .Os
 .Sh NAME
@@ -156,11 +156,33 @@
 into the
 .Fa cpuset .
 .It Fn sched_protect priority
-Performs priority protection for
+Performs priority protection using the
 .Dv PTHREAD_PRIO_PROTECT
 protocol.
-This function will increase the priority of the caller thread to
+This function will increase the protected priority of the caller thread to
+.Fa priority 
+if the current thread's protected priority is smaller than
 .Fa priority .
+Multiple calls to
+.Fn sched_protect
+with a positive priority will 
+.Dq push
+a priority level to the current thread, whereas calling
+.Fn sched_protect
+with a
+.Fa priority
+level of
+.Dv \-1
+will
+.Dq pop
+a priority level.
+When the level reaches
+.Dv 0 
+(the same number of
+.Dq pushes
+and
+.Dq pops
+have been issued) the original thread priority will be restored.
 .El
 .Sh IMPLEMENTATION NOTES
 Setting CPU
@@ -274,6 +296,21 @@
 .Fa pid
 is not zero.
 .El
+.Pp
+The
+.Fn sched_protect
+function fails if:
+.Bl -tag -width Er
+.It Bq Er EINVAL
+The thread was not priority protected.
+.It Bq Er EPERM
+The
+.Fa priority
+parameter was out of range (not in the range between
+.Dv SCHED_PRIO_MIN
+and
+.Dv SCHED_PRIO_MAX ) .
+.El
 .Sh SEE ALSO
 .Xr affinity 3 ,
 .Xr cpuset 3 ,