The Design and Implementation of the FreeBSD Operating System, Second Edition
Now available: The Design and Implementation of the FreeBSD Operating System (Second Edition)


[ source navigation ] [ diff markup ] [ identifier search ] [ freetext search ] [ file search ] [ list types ] [ track identifier ]

FreeBSD/Linux Kernel Cross Reference
sys/man/thread_switch.man

Version: -  FREEBSD  -  FREEBSD-13-STABLE  -  FREEBSD-13-0  -  FREEBSD-12-STABLE  -  FREEBSD-12-0  -  FREEBSD-11-STABLE  -  FREEBSD-11-0  -  FREEBSD-10-STABLE  -  FREEBSD-10-0  -  FREEBSD-9-STABLE  -  FREEBSD-9-0  -  FREEBSD-8-STABLE  -  FREEBSD-8-0  -  FREEBSD-7-STABLE  -  FREEBSD-7-0  -  FREEBSD-6-STABLE  -  FREEBSD-6-0  -  FREEBSD-5-STABLE  -  FREEBSD-5-0  -  FREEBSD-4-STABLE  -  FREEBSD-3-STABLE  -  FREEBSD22  -  l41  -  OPENBSD  -  linux-2.6  -  MK84  -  PLAN9  -  xnu-8792 
SearchContext: -  none  -  3  -  10 

    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


[ source navigation ] [ diff markup ] [ identifier search ] [ freetext search ] [ file search ] [ list types ] [ track identifier ]


This page is part of the FreeBSD/Linux Linux Kernel Cross-Reference, and was automatically generated using a modified version of the LXR engine.