usr/src/man/man3c/schedctl_init.3c

   1 '\" te
   2 .\" Copyright (c) 2003, Sun Microsystems, Inc.  All Rights Reserved.
   3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH SCHEDCTL_INIT 3C "May 28, 2003"
   7 .SH NAME
   8 schedctl_init, schedctl_lookup, schedctl_exit, schedctl_start, schedctl_stop \-
   9 preemption control
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 \fBcc\fR [ \fIflag\fR... ] \fIfile\fR...  [ \fIlibrary\fR... ]
  14 #include <schedctl.h>
  15
  16 \fBschedctl_t *\fR\fBschedctl_init\fR(\fBvoid\fR);
  17 .fi
  18
  19 .LP
  20 .nf
  21 \fBschedctl_t *\fR\fBschedctl_lookup\fR(\fBvoid\fR);
  22 .fi
  23
  24 .LP
  25 .nf
  26 \fBvoid\fR \fBschedctl_exit\fR(\fBvoid\fR);
  27 .fi
  28
  29 .LP
  30 .nf
  31 \fBvoid\fR \fBschedctl_start\fR(\fBschedctl_t *\fR\fIptr\fR);
  32 .fi
  33
  34 .LP
  35 .nf
  36 \fBvoid\fR \fBschedctl_stop\fR(\fBschedctl_t *\fR\fIptr\fR);
  37 .fi
  38
  39 .SH DESCRIPTION
  40 .sp
  41 .LP
  42 These functions provide limited control over the scheduling of a thread (see
  43 \fBthreads\fR(5)). They allow a running thread to give a hint to the kernel
  44 that preemptions of that thread should be avoided. The most likely use for
  45 these functions is to block preemption while holding a spinlock. Improper use
  46 of this facility, including attempts to block preemption for sustained periods
  47 of time, may result in reduced performance.
  48 .sp
  49 .LP
  50 The \fBschedctl_init()\fR function initializes preemption control for the
  51 calling thread and returns a pointer used to refer to the data. If
  52 \fBschedctl_init()\fR is called more than once by the same thread, the most
  53 recently returned pointer is the only valid one.
  54 .sp
  55 .LP
  56 The \fBschedctl_lookup()\fR function returns the currently allocated preemption
  57 control data associated with the calling thread that was previously returned by
  58 \fBschedctl_init()\fR. This can be useful in programs where it is difficult to
  59 maintain local state for each thread.
  60 .sp
  61 .LP
  62 The \fBschedctl_exit()\fR function removes the preemption control data
  63 associated with the calling thread.
  64 .sp
  65 .LP
  66 The \fBschedctl_start()\fR macro gives a hint to the kernel scheduler that
  67 preemption should be avoided on the current thread. The pointer passed to the
  68 macro must be the same as the pointer returned by the call to
  69 \fBschedctl_init()\fR by the current thread. The behavior of the program when
  70 other values are passed is undefined.
  71 .sp
  72 .LP
  73 The \fBschedctl_stop()\fR macro removes the hint that was set by
  74 \fBschedctl_start()\fR. As with \fBschedctl_start()\fR, the pointer passed to
  75 the macro must be the same as the pointer returned by the call to
  76 \fBschedctl_init()\fR by the current thread.
  77 .sp
  78 .LP
  79 The \fBschedctl_start()\fR and \fBschedctl_stop()\fR macros are intended to be
  80 used to bracket short critical sections, such as the time spent holding a
  81 spinlock. Other uses, including the failure to call \fBschedctl_stop()\fR soon
  82 after calling \fBschedctl_start()\fR, might result in poor performance.
  83 .SH RETURN VALUES
  84 .sp
  85 .LP
  86 The \fBschedctl_init()\fR function returns a pointer to a \fBschedctl_t\fR
  87 structure if the initialization was successful, or \fINULL\fR otherwise. The
  88 \fBschedctl_lookup()\fR function returns a pointer to a \fBschedctl_t\fR
  89 structure if the data for that thread was found, or \fINULL\fR otherwise.
  90 .SH ERRORS
  91 .sp
  92 .LP
  93 No errors are returned.
  94 .SH ATTRIBUTES
  95 .sp
  96 .LP
  97 See \fBattributes\fR(5) for descriptions of the following attributes:
  98 .sp
  99
 100 .sp
 101 .TS
 102 box;
 103 c | c
 104 l | l .
 105 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 106 _
 107 Interface Stability     Stable
 108 _
 109 MT-Level        MT-Safe
 110 .TE
 111
 112 .SH SEE ALSO
 113 .sp
 114 .LP
 115 \fBpriocntl\fR(1), \fBexec\fR(2), \fBfork\fR(2), \fBpriocntl\fR(2),
 116 \fBattributes\fR(5), \fBthreads\fR(5)
 117 .SH NOTES
 118 .sp
 119 .LP
 120 Preemption control is intended for use by threads belonging to the time-sharing
 121 (TS), interactive (IA), fair-share (FSS), and fixed-priority (FX) scheduling
 122 classes. If used by threads in other scheduling classes, such as real-time
 123 (RT), no errors will be returned but \fBschedctl_start()\fR and
 124 \fBschedctl_stop()\fR will not have any effect.
 125 .sp
 126 .LP
 127 The data used for preemption control are not copied in the child of a
 128 \fBfork\fR(2). Thus, if a process containing threads using preemption control
 129 calls \fBfork\fR and the child does not immediately call \fBexec\fR(2), each
 130 thread in the child must call \fBschedctl_init()\fR again prior to any future
 131 uses of \fBschedctl_start()\fR and \fBschedctl_stop()\fR. Failure to do so will
 132 result in undefined behavior.