1 .\"
2 .\" Mach Operating System
3 .\" Copyright (c) 1991,1990 Carnegie Mellon University
4 .\" All Rights Reserved.
5 .\"
6 .\" Permission to use, copy, modify and distribute this software and its
7 .\" documentation is hereby granted, provided that both the copyright
8 .\" notice and this permission notice appear in all copies of the
9 .\" software, derivative works or modified versions, and any portions
10 .\" thereof, and that both notices appear in supporting documentation.
11 .\"
12 .\" CARNEGIE MELLON ALLOWS FREE USE OF THIS SOFTWARE IN ITS "AS IS"
13 .\" CONDITION. CARNEGIE MELLON DISCLAIMS ANY LIABILITY OF ANY KIND FOR
14 .\" ANY DAMAGES WHATSOEVER RESULTING FROM THE USE OF THIS SOFTWARE.
15 .\"
16 .\" Carnegie Mellon requests users of this software to return to
17 .\"
18 .\" Software Distribution Coordinator or Software.Distribution@CS.CMU.EDU
19 .\" School of Computer Science
20 .\" Carnegie Mellon University
21 .\" Pittsburgh PA 15213-3890
22 .\"
23 .\" any improvements or extensions that they make and grant Carnegie Mellon
24 .\" the rights to redistribute these changes.
25 .\"
26 .\"
27 .\" HISTORY
28 .\" $Log: thread_switch.man,v $
29 .\" Revision 2.5 92/02/19 16:07:26 elf
30 .\" thread_restore_priority does not exist.
31 .\" [92/01/20 rwd]
32 .\" Fixed to reflect change in timeout parameter being zero
33 .\" [92/01/10 rwd]
34 .\"
35 .\" Revision 2.4 91/05/14 17:14:56 mrt
36 .\" Correcting copyright
37 .\"
38 .\" Revision 2.3 91/02/14 14:15:48 mrt
39 .\" Changed to new Mach copyright
40 .\" [91/02/12 18:16:41 mrt]
41 .\"
42 .\" Revision 2.2 90/08/07 18:46:52 rpd
43 .\" Created.
44 .\"
45 .TH thread_switch 2 8/13/89
46 .CM 4
47 .SH NAME
48 .nf
49 thread_switch \- cause context switch with options
50 thread_depress_abort \- abort priority depression
51 .SH SYNOPSIS
52 .nf
53 .ft B
54 #include <mach.h>
55
56 .nf
57 .ft B
58 kern_return_t thread_switch(new_thread, option, time)
59 thread_t new_thread;
60 int option;
61 int time;
62
63
64 .fi
65 .ft P
66 .nf
67 .ft B
68 kern_return_t thread_depress_abort(thread)
69 thread_t thread;
70
71
72
73 .fi
74 .ft P
75 .SH ARGUMENTS
76 .TP 15
77 .B
78 new_thread
79 Thread to context switch to.
80 .TP 15
81 .B
82 option
83 Specifies options associated with context switch.
84 .TP 15
85 .B
86 time
87 Time duration for options
88 .TP 15
89 .B
90 thread
91 Thread to be affected.
92
93 .SH DESCRIPTION
94 .B thread_switch
95 provides low-level access to the scheduler's context switching code.
96 .B new_thread
97 is a hint that implements handoff scheduling. The operating system
98 will attempt to switch directly to the new thread (bypassing the normal
99 logic that selects the next thread to run) if possible. Since this
100 is a hint, it may be incorrect; it is ignored if it doesn't specify
101 a thread on the same host as the current thread or if that thread
102 can't be switched to (not runnable or already running on another processor).
103 In this case, the normal logic to select the next thread to run is
104 used; the current thread may continue running if there is no other
105 appropriate thread to run.
106
107 Options for
108 .B option
109 are defined in <mach/thread_switch.h>. Three options are recognized:
110 .B SWITCH_OPTION_NONE
111 No options, the time argument is ignored.
112 .B SWITCH_OPTION_WAIT
113 The thread is blocked for the specified
114 .B time.
115 This can be aborted by
116 .B thread_abort.
117 .B SWITCH_OPTION_DEPRESS
118 The thread's priority is depressed to the lowest possible value for
119 .B time.
120 This can be aborted by
121 .B thread_depress_abort
122 This depression is independent of operations that change the thread's
123 priority (e.g.
124 .B thread_priority
125 will not abort the depression).
126 The minimum time and units of time can be obtained as the min_timeout
127 value from
128 .B host_info. A time value of 0 along with the option
129 SWITCH_OPTION_DEPRESS indicates that the depression should last
130 until the thread is rescheduled at the depressed priority.
131
132 .B thread_switch
133 and
134 .B thread_restore_priority
135 are optimized traps that affect the current thread.
136 .B thread_depress_abort
137 is an rpc to the kernel that may affect any thread.
138
139 .B thread_switch
140 is often called when the current thread can proceed no further for
141 some reason; the various options and arguments allow information about
142 this reason to be transmitted to the kernel. The
143 .B new_thread
144 argument (handoff scheduling) is useful when the identity of the thread
145 that must make progress before the current thread runs again is known.
146 The
147 .B WAIT
148 option is used when the amount of time that the current thread must wait
149 before it can do anything useful can be estimated and is fairly long.
150 The
151 .B DEPRESS
152 option is used when the amount of time that must be waited is fairly short,
153 especially when the identity of the thread that is being waited for is
154 not known.
155
156 Users should beware of calling
157 .B thread_switch
158 with an invalid hint (e.g.
159 .B MACH_PORT_NULL
160 ) and no option. Because the time-sharing scheduler varies the priority
161 of threads based on usage, this may result in a waste of cpu time if the
162 thread that must be run is of lower priority. The use of the DEPRESS
163 option in this situation is highly recommended.
164
165 .B thread_switch
166 ignores policies. Users relying on the preemption semantics of a fixed
167 time policy should be aware that
168 .B thread_switch
169 ignores these semantics; it will run the specified
170 .B new_thread
171 indepent of its priority and the priority of any other threads that could
172 be run instead.
173
174 .SH DIAGNOSTICS
175 .TP 25
176 KERN_SUCCESS
177 The call succeeded.
178 .B thread_restore_priority
179 always succeeds, and does not have a defined return value as a result.
180 .TP 25
181 KERN_INVALID_ARGUMENT
182 .B thread
183 is not a thread, or
184 .B option
185 is not a recognized option.
186 .TP 25
187 KERN_FAILURE
188 .B kern_depress_abort
189 failed because the thread was
190 not depressed.
191
192 .SH BUGS
193 Availability limited.
194
195 .SH SEE ALSO
196 .B host_info
197
Cache object: 19b320b1132838b9b3574d05a86bc128
|